diff --git a/R/adjacency.R b/R/adjacency.R index f17ba443814..a526cf80c92 100644 --- a/R/adjacency.R +++ b/R/adjacency.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.adjacency()` was renamed to [graph_from_adjacency_matrix()] to create a more -#' consistent API. +#' `graph.adjacency()` was renamed to [graph_from_adjacency_matrix()] to create a more consistent API. #' @inheritParams graph_from_adjacency_matrix #' @keywords internal #' @export @@ -57,19 +56,15 @@ graph.adjacency <- function( #' Create graphs from adjacency matrices #' -#' `graph_from_adjacency_matrix()` is a flexible function for creating `igraph` -#' graphs from adjacency matrices. +#' `graph_from_adjacency_matrix()` is a flexible function for creating `igraph` graphs from adjacency matrices. #' -#' The order of the vertices are preserved, i.e. the vertex corresponding to -#' the first row will be vertex 0 in the graph, etc. +#' The order of the vertices are preserved, i.e. the vertex corresponding to the first row will be vertex 0 in the graph, etc. #' -#' `graph_from_adjacency_matrix()` operates in two main modes, depending on the -#' `weighted` argument. +#' `graph_from_adjacency_matrix()` operates in two main modes, depending on the `weighted` argument. #' -#' If this argument is `NULL` then an unweighted graph is created and an -#' element of the adjacency matrix gives the number of edges to create between -#' the two corresponding vertices. The details depend on the value of the -#' `mode` argument: +#' If this argument is `NULL` then an unweighted graph is created +#' and an element of the adjacency matrix gives the number of edges to create between the two corresponding vertices. +#' The details depend on the value of the `mode` argument: #' \describe{ #' \item{"directed"}{ #' The graph will be directed and a matrix element gives @@ -101,9 +96,8 @@ graph.adjacency <- function( #' } #' } #' -#' If the `weighted` argument is not `NULL` then the elements of the -#' matrix give the weights of the edges (if they are not zero). The details -#' depend on the value of the `mode` argument: +#' If the `weighted` argument is not `NULL` then the elements of the matrix give the weights of the edges (if they are not zero). +#' The details depend on the value of the `mode` argument: #' \describe{ #' \item{"directed"}{ #' The graph will be directed and a matrix element gives the edge weights. @@ -134,39 +128,31 @@ graph.adjacency <- function( #' } #' } #' -#' @param adjmatrix A square adjacency matrix. From igraph version 0.5.1 this -#' can be a sparse matrix created with the `Matrix` package. +#' @param adjmatrix A square adjacency matrix. +#' From igraph version 0.5.1 this can be a sparse matrix created with the `Matrix` package. #' @inheritParams rlang::args_dots_empty -#' @param mode Character scalar, specifies how igraph should interpret the -#' supplied matrix. See also the `weighted` argument, the interpretation -#' depends on that too. Possible values are: `directed`, -#' `undirected`, `upper`, `lower`, `max`, `min`, -#' `plus`. See details below. -#' @param weighted This argument specifies whether to create a weighted graph -#' from an adjacency matrix. If it is `NULL` then an unweighted graph is -#' created and the elements of the adjacency matrix gives the number of edges -#' between the vertices. If it is a character constant then for every non-zero -#' matrix entry an edge is created and the value of the entry is added as an -#' edge attribute named by the `weighted` argument. If it is `TRUE` -#' then a weighted graph is created and the name of the edge attribute will be -#' `weight`. See also details below. -#' @param diag Logical, whether to include the diagonal of the matrix in -#' the calculation. If this is `FALSE` then the diagonal is zerod out -#' first. -#' @param add.colnames Character scalar, whether to add the column names as -#' vertex attributes. If it is `NULL` (the default) then, if -#' present, column names are added as vertex attribute \sQuote{name}. If -#' `NA` or `FALSE` then they will not be added. If a character constant, -#' then it gives the name of the vertex attribute to add. -#' @param add.rownames Character scalar, whether to add the row names as vertex -#' attributes. Possible values the same as the previous argument. By default -#' row names are not added. If \sQuote{`add.rownames`} and -#' \sQuote{`add.colnames`} specify the same vertex attribute, then the -#' former is ignored. +#' @param mode Character scalar, specifies how igraph should interpret the supplied matrix. +#' See also the `weighted` argument, the interpretation depends on that too. +#' Possible values are: `directed`, `undirected`, `upper`, `lower`, `max`, `min`, `plus`. +#' See details below. +#' @param weighted This argument specifies whether to create a weighted graph from an adjacency matrix. +#' If it is `NULL` then an unweighted graph is created and the elements of the adjacency matrix gives the number of edges between the vertices. +#' If it is a character constant then for every non-zero matrix entry an edge is created and the value of the entry is added as an edge attribute named by the `weighted` argument. +#' If it is `TRUE` then a weighted graph is created and the name of the edge attribute will be `weight`. +#' See also details below. +#' @param diag Logical, whether to include the diagonal of the matrix in the calculation. +#' If this is `FALSE` then the diagonal is zerod out first. +#' @param add.colnames Character scalar, whether to add the column names as vertex attributes. +#' If it is `NULL` (the default) then, if present, column names are added as vertex attribute \sQuote{name}. +#' If `NA` or `FALSE` then they will not be added. +#' If a character constant, then it gives the name of the vertex attribute to add. +#' @param add.rownames Character scalar, whether to add the row names as vertex attributes. +#' Possible values the same as the previous argument. +#' By default row names are not added. +#' If \sQuote{`add.rownames`} and \sQuote{`add.colnames`} specify the same vertex attribute, then the former is ignored. #' @return An igraph graph object. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso [make_graph()] and [graph_from_literal()] for other ways to -#' create graphs. +#' @seealso [make_graph()] and [graph_from_literal()] for other ways to create graphs. #' @keywords graphs #' @examples #' @@ -592,8 +578,8 @@ graph.adjacency.sparse <- function( } vc <- nrow(adjmatrix) - # Exit early for empty graphs. Use na.counted = TRUE so that NA entries - # (which are stored explicitly) do not cause nnzero() to return NA. + # Exit early for empty graphs. + # Use na.counted = TRUE so that NA entries (which are stored explicitly) do not cause nnzero() to return NA. if (vc == 1 || Matrix::nnzero(adjmatrix, na.counted = TRUE) == 0) { return(make_empty_graph(n = vc, directed = (mode == "directed"))) } diff --git a/R/as_phylo.R b/R/as_phylo.R index 03e8b21e0a4..9f5496133ee 100644 --- a/R/as_phylo.R +++ b/R/as_phylo.R @@ -2,8 +2,7 @@ #' @title as_phylo #' @description `r lifecycle::badge("deprecated")` #' -#' `as_phylo` methods were renamed `as.phylo` -#' for more consistency with other R methods. +#' `as_phylo` methods were renamed `as.phylo` for more consistency with other R methods. #' #' @export #' @param x object to be coerced diff --git a/R/assortativity.R b/R/assortativity.R index ae9ce17fde4..6693c2e3c4a 100644 --- a/R/assortativity.R +++ b/R/assortativity.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `assortativity.nominal()` was renamed to [assortativity_nominal()] to create a more -#' consistent API. +#' `assortativity.nominal()` was renamed to [assortativity_nominal()] to create a more consistent API. #' @inheritParams assortativity_nominal #' @keywords internal #' @export @@ -33,8 +32,7 @@ assortativity.nominal <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `assortativity.degree()` was renamed to [assortativity_degree()] to create a more -#' consistent API. +#' `assortativity.degree()` was renamed to [assortativity_degree()] to create a more consistent API. #' @inheritParams assortativity_degree #' @keywords internal #' @export @@ -73,27 +71,26 @@ assortativity.degree <- function(graph, directed = TRUE) { #' Assortativity coefficient #' -#' The assortativity coefficient is positive if similar vertices (based on some -#' external property) tend to connect to each, and negative otherwise. +#' The assortativity coefficient is positive if similar vertices (based on some external property) tend to connect to each, +#' and negative otherwise. #' -#' The assortativity coefficient measures the level of homophyly of the graph, -#' based on some vertex labeling or values assigned to vertices. If the -#' coefficient is high, that means that connected vertices tend to have the -#' same labels or similar assigned values. +#' The assortativity coefficient measures the level of homophyly of the graph, based on some vertex labeling or values assigned to vertices. +#' If the coefficient is high, that means that connected vertices tend to have the same labels or similar assigned values. #' -#' M.E.J. Newman defined two kinds of assortativity coefficients, the first one -#' is for categorical labels of vertices. `assortativity_nominal()` -#' calculates this measure. It is defined as +#' M.E.J. +#' Newman defined two kinds of assortativity coefficients, the first one is for categorical labels of vertices. +#' `assortativity_nominal()` calculates this measure. +#' It is defined as #' #' \deqn{r=\frac{\sum_i e_{ii}-\sum_i a_i b_i}{1-\sum_i a_i b_i}}{ #' r=(sum(e(i,i), i) - sum(a(i)b(i), i)) / (1 - sum(a(i)b(i), i))} #' -#' where \eqn{e_{ij}}{e(i,j)} is the fraction of edges connecting vertices of -#' type \eqn{i} and \eqn{j}, \eqn{a_i=\sum_j e_{ij}}{a(i)=sum(e(i,j), j)} and -#' \eqn{b_j=\sum_i e_{ij}}{b(j)=sum(e(i,j), i)}. +#' where \eqn{e_{ij}}{e(i,j)} is the fraction of edges connecting vertices of type \eqn{i} and \eqn{j}, +#' \eqn{a_i=\sum_j e_{ij}}{a(i)=sum(e(i,j), j)} and \eqn{b_j=\sum_i e_{ij}}{b(j)=sum(e(i,j), i)}. #' -#' The second assortativity variant is based on values assigned to the -#' vertices. `assortativity()` calculates this measure. It is defined as +#' The second assortativity variant is based on values assigned to the vertices. +#' `assortativity()` calculates this measure. +#' It is defined as #' #' \deqn{r=\frac1{\sigma_q^2}\sum_{jk} jk(e_{jk}-q_j q_k)}{ #' sum(jk(e(j,k)-q(j)q(k)), j, k) / sigma(q)^2} @@ -103,18 +100,15 @@ assortativity.degree <- function(graph, directed = TRUE) { #' \deqn{r=\frac1{\sigma_o\sigma_i}\sum_{jk}jk(e_{jk}-q_j^o q_k^i)}{ #' sum(jk(e(j,k)-qout(j)qin(k)), j, k) / sigma(qin) / sigma(qout) } #' -#' for directed ones. Here \eqn{q_i^o=\sum_j e_{ij}}{qout(i)=sum(e(i,j), j)}, -#' \eqn{q_i^i=\sum_j e_{ji}}{qin(i)=sum(e(j,i), j)}, moreover, -#' \eqn{\sigma_q}{\sigma(q)}, \eqn{\sigma_o}{\sigma(qout)} and -#' \eqn{\sigma_i}{\sigma(qin)} are the standard deviations of \eqn{q}, +#' for directed ones. +#' Here \eqn{q_i^o=\sum_j e_{ij}}{qout(i)=sum(e(i,j), j)}, \eqn{q_i^i=\sum_j e_{ji}}{qin(i)=sum(e(j,i), j)}, moreover, +#' \eqn{\sigma_q}{\sigma(q)}, \eqn{\sigma_o}{\sigma(qout)} and \eqn{\sigma_i}{\sigma(qin)} are the standard deviations of \eqn{q}, #' \eqn{q^o}{qout} and \eqn{q^i}{qin}, respectively. #' -#' The reason of the difference is that in directed networks the relationship -#' is not symmetric, so it is possible to assign different values to the -#' outgoing and the incoming end of the edges. +#' The reason of the difference is that in directed networks the relationship is not symmetric, +#' so it is possible to assign different values to the outgoing and the incoming end of the edges. #' -#' `assortativity_degree()` uses vertex degree as vertex values -#' and calls `assortativity()`. +#' `assortativity_degree()` uses vertex degree as vertex values and calls `assortativity()`. #' #' Undirected graphs are effectively treated as directed ones with all-reciprocal edges. #' Thus, self-loops are taken into account twice in undirected graphs. @@ -123,27 +117,17 @@ assortativity.degree <- function(graph, directed = TRUE) { #' @param graph The input graph, it can be directed or undirected. #' @param values The vertex values, these can be arbitrary numeric values. #' @inheritParams rlang::args_dots_empty -#' @param values.in A second value vector to use for the incoming edges when -#' calculating assortativity for a directed graph. -#' Supply `NULL` here if -#' you want to use the same values for outgoing and incoming edges. -#' This -#' argument is ignored (with a warning) if it is not `NULL` and undirected -#' assortativity coefficient is being calculated. -#' @param directed Logical, whether to consider edge directions for -#' directed graphs. +#' @param values.in A second value vector to use for the incoming edges when calculating assortativity for a directed graph. +#' Supply `NULL` here if you want to use the same values for outgoing and incoming edges. +#' This argument is ignored (with a warning) if it is not `NULL` and undirected assortativity coefficient is being calculated. +#' @param directed Logical, whether to consider edge directions for directed graphs. #' This argument is ignored for undirected graphs. -#' Supply -#' `TRUE` here to do the natural thing, i.e. use directed version of the -#' measure for directed graphs and the undirected version for undirected -#' graphs. +#' Supply `TRUE` here to do the natural thing, +#' i.e. use directed version of the measure for directed graphs and the undirected version for undirected graphs. #' @param normalized Logical, whether to compute the normalized assortativity. #' The non-normalized nominal assortativity is identical to modularity. -#' The non-normalized value-based assortativity is simply the covariance of the -#' values at the two ends of edges. -#' @param types1,types2 -#' `r lifecycle::badge("deprecated")` -#' Deprecated aliases for `values` and `values.in`, respectively. +#' The non-normalized value-based assortativity is simply the covariance of the values at the two ends of edges. +#' @param types1,types2 `r lifecycle::badge("deprecated")` Deprecated aliases for `values` and `values.in`, respectively. #' @return A single real number. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @references M. E. J. Newman: Mixing patterns in networks, *Phys. Rev. @@ -234,10 +218,10 @@ assortativity_legacy <- function( ) } -#' @param types Vector giving the vertex types. They as assumed to be integer -#' numbers, starting with one. Non-integer values are converted to integers -#' with [as.integer()]. Character vectors are converted to integers using -#' [as.factor()]. +#' @param types Vector giving the vertex types. +#' They as assumed to be integer numbers, starting with one. +#' Non-integer values are converted to integers with [as.integer()]. +#' Character vectors are converted to integers using [as.factor()]. #' @rdname assortativity #' @inheritParams rlang::args_dots_empty #' @export diff --git a/R/attributes.R b/R/attributes.R index 13824155c1c..7d5e728d9b6 100644 --- a/R/attributes.R +++ b/R/attributes.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `set.vertex.attribute()` was renamed to [set_vertex_attr()] to create a more -#' consistent API. +#' `set.vertex.attribute()` was renamed to [set_vertex_attr()] to create a more consistent API. #' @inheritParams set_vertex_attr #' @keywords internal #' @export @@ -23,8 +22,7 @@ set.vertex.attribute <- function(graph, name, index = V(graph), value) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `set.graph.attribute()` was renamed to [set_graph_attr()] to create a more -#' consistent API. +#' `set.graph.attribute()` was renamed to [set_graph_attr()] to create a more consistent API. #' @inheritParams set_graph_attr #' @keywords internal #' @export @@ -43,8 +41,7 @@ set.graph.attribute <- function(graph, name, value) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `set.edge.attribute()` was renamed to [set_edge_attr()] to create a more -#' consistent API. +#' `set.edge.attribute()` was renamed to [set_edge_attr()] to create a more consistent API. #' @inheritParams set_edge_attr #' @keywords internal #' @export @@ -59,8 +56,7 @@ set.edge.attribute <- function(graph, name, index = E(graph), value) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `remove.vertex.attribute()` was renamed to [delete_vertex_attr()] to create a more -#' consistent API. +#' `remove.vertex.attribute()` was renamed to [delete_vertex_attr()] to create a more consistent API. #' @inheritParams delete_vertex_attr #' @keywords internal #' @export @@ -79,8 +75,7 @@ remove.vertex.attribute <- function(graph, name) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `remove.graph.attribute()` was renamed to [delete_graph_attr()] to create a more -#' consistent API. +#' `remove.graph.attribute()` was renamed to [delete_graph_attr()] to create a more consistent API. #' @inheritParams delete_graph_attr #' @keywords internal #' @export @@ -99,8 +94,7 @@ remove.graph.attribute <- function(graph, name) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `remove.edge.attribute()` was renamed to [delete_edge_attr()] to create a more -#' consistent API. +#' `remove.edge.attribute()` was renamed to [delete_edge_attr()] to create a more consistent API. #' @inheritParams delete_edge_attr #' @keywords internal #' @export @@ -119,8 +113,7 @@ remove.edge.attribute <- function(graph, name) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `list.vertex.attributes()` was renamed to [vertex_attr_names()] to create a more -#' consistent API. +#' `list.vertex.attributes()` was renamed to [vertex_attr_names()] to create a more consistent API. #' @inheritParams vertex_attr_names #' @keywords internal #' @export @@ -139,8 +132,7 @@ list.vertex.attributes <- function(graph) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `list.graph.attributes()` was renamed to [graph_attr_names()] to create a more -#' consistent API. +#' `list.graph.attributes()` was renamed to [graph_attr_names()] to create a more consistent API. #' @inheritParams graph_attr_names #' @keywords internal #' @export @@ -159,8 +151,7 @@ list.graph.attributes <- function(graph) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `list.edge.attributes()` was renamed to [edge_attr_names()] to create a more -#' consistent API. +#' `list.edge.attributes()` was renamed to [edge_attr_names()] to create a more consistent API. #' @inheritParams edge_attr_names #' @keywords internal #' @export @@ -179,8 +170,7 @@ list.edge.attributes <- function(graph) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `is.weighted()` was renamed to [is_weighted()] to create a more -#' consistent API. +#' `is.weighted()` was renamed to [is_weighted()] to create a more consistent API. #' @inheritParams is_weighted #' @keywords internal #' @export @@ -195,8 +185,7 @@ is.weighted <- function(graph) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `is.named()` was renamed to [is_named()] to create a more -#' consistent API. +#' `is.named()` was renamed to [is_named()] to create a more consistent API. #' @inheritParams is_named #' @keywords internal #' @export @@ -211,8 +200,7 @@ is.named <- function(graph) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `is.bipartite()` was renamed to [is_bipartite()] to create a more -#' consistent API. +#' `is.bipartite()` was renamed to [is_bipartite()] to create a more consistent API. #' @inheritParams is_bipartite #' @keywords internal #' @export @@ -227,8 +215,7 @@ is.bipartite <- function(graph) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `get.vertex.attribute()` was renamed to [vertex_attr()] to create a more -#' consistent API. +#' `get.vertex.attribute()` was renamed to [vertex_attr()] to create a more consistent API. #' @inheritParams vertex_attr #' @keywords internal #' @export @@ -243,8 +230,7 @@ get.vertex.attribute <- function(graph, name, index = V(graph)) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `get.graph.attribute()` was renamed to [graph_attr()] to create a more -#' consistent API. +#' `get.graph.attribute()` was renamed to [graph_attr()] to create a more consistent API. #' @inheritParams graph_attr #' @keywords internal #' @export @@ -259,8 +245,7 @@ get.graph.attribute <- function(graph, name) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `get.edge.attribute()` was renamed to [edge_attr()] to create a more -#' consistent API. +#' `get.edge.attribute()` was renamed to [edge_attr()] to create a more consistent API. #' @inheritParams edge_attr #' @keywords internal #' @export @@ -307,8 +292,8 @@ get.edge.attribute <- function(graph, name, index = E(graph)) { #' Graph attributes of a graph #' #' @param graph Input graph. -#' @param name The name of attribute to query. If missing, then all -#' attributes are returned in a list. +#' @param name The name of attribute to query. +#' If missing, then all attributes are returned in a list. #' @return A list of graph attributes, or a single graph attribute. #' #' @aliases graph.attributes @@ -337,9 +322,8 @@ graph_attr <- function(graph, name) { #' Set all or some graph attributes #' #' @param graph The graph. -#' @param name The name of the attribute to set. If missing, then -#' `value` should be a named list, and all list members -#' are set as attributes. +#' @param name The name of the attribute to set. +#' If missing, then `value` should be a named list, and all list members are set as attributes. #' @param value The value of the attribute to set #' @return The graph, with the attribute(s) added. #' @@ -430,12 +414,11 @@ graph.attributes <- function(graph) { #' Query vertex attributes of a graph #' #' @param graph The graph. -#' @param name Name of the attribute to query. If missing, then -#' all vertex attributes are returned in a list. -#' @param index An optional vertex sequence to query the attribute only -#' for these vertices. The default `NULL` selects all vertices. -#' @return The value of the vertex attribute, or the list of -#' all vertex attributes, if `name` is missing. +#' @param name Name of the attribute to query. +#' If missing, then all vertex attributes are returned in a list. +#' @param index An optional vertex sequence to query the attribute only for these vertices. +#' The default `NULL` selects all vertices. +#' @return The value of the vertex attribute, or the list of all vertex attributes, if `name` is missing. #' #' @aliases vertex.attributes #' @family attributes @@ -478,13 +461,11 @@ vertex_attr <- function(graph, name, index = NULL) { #' Set one or more vertex attributes #' #' @param graph The graph. -#' @param name The name of the vertex attribute to set. If missing, -#' then `value` must be a named list, and its entries are -#' set as vertex attributes. -#' @param index An optional vertex sequence to set the attributes -#' of a subset of vertices. The default `NULL` selects all vertices. -#' @param value The new value of the attribute(s) for all -#' (or `index`) vertices. +#' @param name The name of the vertex attribute to set. +#' If missing, then `value` must be a named list, and its entries are set as vertex attributes. +#' @param index An optional vertex sequence to set the attributes of a subset of vertices. +#' The default `NULL` selects all vertices. +#' @param value The new value of the attribute(s) for all (or `index`) vertices. #' @return The graph, with the vertex attribute(s) added or set. #' #' @aliases vertex.attributes<- @@ -517,10 +498,9 @@ vertex_attr <- function(graph, name, index = NULL) { #' #' @param graph The graph. #' @param name The name of the attribute to set. -#' @param index An optional vertex sequence to set the attributes -#' of a subset of vertices. The default `NULL` selects all vertices. -#' @param value The new value of the attribute for all (or `index`) -#' vertices. +#' @param index An optional vertex sequence to set the attributes of a subset of vertices. +#' The default `NULL` selects all vertices. +#' @param value The new value of the attribute for all (or `index`) vertices. #' If `NULL`, the input is returned unchanged. #' @return The graph, with the vertex attribute added or set. #' @@ -563,8 +543,8 @@ set_vertex_attr <- function(graph, name, index = NULL, value) { #' #' @param graph The graph. #' @param ... <[`dynamic-dots`][rlang::dyn-dots]> Named arguments, where the names are the attributes -#' @param index An optional vertex sequence to set the attributes -#' of a subset of vertices. The default `NULL` selects all vertices. +#' @param index An optional vertex sequence to set the attributes of a subset of vertices. +#' The default `NULL` selects all vertices. #' @return The graph, with the vertex attributes added or set. #' #' @family attributes @@ -754,12 +734,11 @@ set_value_at <- function(value, idx, length_out) { #' Query edge attributes of a graph #' #' @param graph The graph -#' @param name The name of the attribute to query. If missing, then -#' all edge attributes are returned in a list. -#' @param index An optional edge sequence to query edge attributes -#' for a subset of edges. The default `NULL` selects all edges. -#' @return The value of the edge attribute, or the list of all -#' edge attributes if `name` is missing. +#' @param name The name of the attribute to query. +#' If missing, then all edge attributes are returned in a list. +#' @param index An optional edge sequence to query edge attributes for a subset of edges. +#' The default `NULL` selects all edges. +#' @return The value of the edge attribute, or the list of all edge attributes if `name` is missing. #' #' @aliases edge.attributes #' @family attributes @@ -803,13 +782,11 @@ edge_attr <- function(graph, name, index = NULL) { #' Set one or more edge attributes #' #' @param graph The graph. -#' @param name The name of the edge attribute to set. If missing, -#' then `value` must be a named list, and its entries are -#' set as edge attributes. -#' @param index An optional edge sequence to set the attributes -#' of a subset of edges. The default `NULL` selects all edges. -#' @param value The new value of the attribute(s) for all -#' (or `index`) edges. +#' @param name The name of the edge attribute to set. +#' If missing, then `value` must be a named list, and its entries are set as edge attributes. +#' @param index An optional edge sequence to set the attributes of a subset of edges. +#' The default `NULL` selects all edges. +#' @param value The new value of the attribute(s) for all (or `index`) edges. #' @return The graph, with the edge attribute(s) added or set. #' #' @aliases edge.attributes<- @@ -841,10 +818,9 @@ edge_attr <- function(graph, name, index = NULL) { #' #' @param graph The graph #' @param name The name of the attribute to set. -#' @param index An optional edge sequence to set the attributes of -#' a subset of edges. The default `NULL` selects all edges. -#' @param value The new value of the attribute for all (or `index`) -#' edges. +#' @param index An optional edge sequence to set the attributes of a subset of edges. +#' The default `NULL` selects all edges. +#' @param value The new value of the attribute for all (or `index`) edges. #' If `NULL`, the input is returned unchanged. #' @return The graph, with the edge attribute added or set. #' @@ -1223,20 +1199,15 @@ delete_edge_attr <- function(graph, name) { #' Named graphs #' -#' An igraph graph is named, if there is a symbolic name associated with its -#' vertices. +#' An igraph graph is named, if there is a symbolic name associated with its vertices. #' -#' In igraph vertices can always be identified and specified via their numeric -#' vertex IDs. This is, however, not always convenient, and in many cases there -#' exist symbolic IDs that correspond to the vertices. To allow this more -#' flexible identification of vertices, one can assign a vertex attribute -#' called \sQuote{name} to an igraph graph. After doing this, the symbolic -#' vertex names can be used in all igraph functions, instead of the numeric -#' IDs. +#' In igraph vertices can always be identified and specified via their numeric vertex IDs. +#' This is, however, not always convenient, and in many cases there exist symbolic IDs that correspond to the vertices. +#' To allow this more flexible identification of vertices, one can assign a vertex attribute called \sQuote{name} to an igraph graph. +#' After doing this, the symbolic vertex names can be used in all igraph functions, instead of the numeric IDs. #' -#' Note that the uniqueness of vertex names are currently not enforced in -#' igraph, you have to check that for yourself, when assigning the vertex -#' names. +#' Note that the uniqueness of vertex names are currently not enforced in igraph, you have to check that for yourself, +#' when assigning the vertex names. #' #' @param graph The input graph. #' @return A logical scalar. @@ -1260,19 +1231,16 @@ is_named <- function(graph) { #' Weighted graphs #' -#' In weighted graphs, a real number is assigned to each (directed or -#' undirected) edge. +#' In weighted graphs, a real number is assigned to each (directed or undirected) edge. #' -#' In igraph edge weights are represented via an edge attribute, called -#' \sQuote{weight}. The `is_weighted()` function only checks that such an -#' attribute exists. (It does not even checks that it is a numeric edge -#' attribute.) +#' In igraph edge weights are represented via an edge attribute, called \sQuote{weight}. +#' The `is_weighted()` function only checks that such an attribute exists. +#' (It does not even checks that it is a numeric edge attribute.) #' #' Edge weights are used for different purposes by the different functions. -#' E.g. shortest path functions use it as the cost of the path; community -#' finding methods use it as the strength of the relationship between two -#' vertices, etc. Check the manual pages of the functions working with weighted -#' graphs for details. +#' E.g. shortest path functions use it as the cost of the path; +#' community finding methods use it as the strength of the relationship between two vertices, +#' etc. Check the manual pages of the functions working with weighted graphs for details. #' #' @param graph The input graph. #' @return A logical scalar. @@ -1293,8 +1261,8 @@ is_weighted <- function(graph) { } #' @title Checks whether the graph has a vertex attribute called `type`. -#' @description It does not check whether the graph is bipartite in the -#' mathematical sense. Use [bipartite_mapping()] for that. +#' @description It does not check whether the graph is bipartite in the mathematical sense. +#' Use [bipartite_mapping()] for that. #' @family bipartite #' @param graph The input graph #' @export @@ -1333,11 +1301,10 @@ igraph.i.attribute.combination <- function(comb, allow_rename = FALSE) { if (anyDuplicated(names(comb)) > 0) { cli::cli_warn("Some attributes are duplicated") } - # `known_codes` are the numeric values of the `igraph_attribute_combination_type_t` - # enum in the C library (see src/vendor/cigraph/include/igraph_attributes.h). - # Each code must stay aligned with its name in `known_names`. The DEFAULT (1) and - # FUNCTION (2) enum values are intentionally absent: FUNCTION is handled by the - # `!is.character(x)` branch below, and DEFAULT is not selectable by name. + # `known_codes` are the numeric values of the `igraph_attribute_combination_type_t` enum in the C library (see src/vendor/cigraph/include/igraph_attributes.h). + # Each code must stay aligned with its name in `known_names`. + # The DEFAULT (1) and FUNCTION (2) enum values are intentionally absent: FUNCTION is handled by the `!is.character(x)` branch below, + # and DEFAULT is not selectable by name. known_names <- c( "concat", "first", @@ -1380,18 +1347,13 @@ igraph.i.attribute.combination <- function(comb, allow_rename = FALSE) { #' How igraph functions handle attributes when the graph changes #' -#' Many times, when the structure of a graph is modified, vertices/edges map of -#' the original graph map to vertices/edges in the newly created (modified) -#' graph. For example [simplify()] maps multiple edges to single -#' edges. igraph provides a flexible mechanism to specify what to do with the -#' vertex/edge attributes in these cases. +#' Many times, when the structure of a graph is modified, +#' vertices/edges map of the original graph map to vertices/edges in the newly created (modified) graph. +#' For example [simplify()] maps multiple edges to single edges. igraph provides a flexible mechanism to specify what to do with the 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` -#' 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 -#' attributes of the new graph. +#' The functions that support the combination of attributes have one or two extra arguments called `vertex.attr.comb` and/or `edge.attr.comb` 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 attributes of the new graph. #' #' The specification of the combination of (vertex or edge) attributes can be #' given as \enumerate{ @@ -1400,21 +1362,19 @@ igraph.i.attribute.combination <- function(comb, allow_rename = FALSE) { #' \item a list of character scalars and/or function objects. #' } #' -#' If it is a character scalar, then it refers to one of the predefined -#' combinations, see their list below. +#' If it is a character scalar, then it refers to one of the predefined combinations, see their list below. #' -#' If it is a function, then the given function is expected to perform the -#' combination. It will be called once for each new vertex/edge in the graph, -#' with a single argument: the attribute values of the vertices that map to -#' that single vertex. +#' If it is a function, then the given function is expected to perform the combination. +#' It will be called once for each new vertex/edge in the graph, with a single argument: +#' the attribute values of the vertices that map to that single vertex. #' -#' The third option, a list can be used to specify different combination -#' methods for different attributes. A named entry of the list corresponds to -#' the attribute with the same name. An unnamed entry (i.e. if the name is the -#' empty string) of the list specifies the default combination method. I.e. +#' The third option, a list can be used to specify different combination methods for different attributes. +#' A named entry of the list corresponds to the attribute with the same name. +#' An unnamed entry (i.e. if the name is the empty string) of the list specifies the default combination method. +#' I.e. #' \preformatted{list(weight="sum", "ignore")} specifies that the weight of the -#' new edge should be sum of the weights of the corresponding edges in the old -#' graph; and that the rest of the attributes should be ignored (=dropped). +#' new edge should be sum of the weights of the corresponding edges in the old graph; +#' and that the rest of the attributes should be ignored (=dropped). #' #' @family attributes #' @name igraph-attribute-combination @@ -1470,22 +1430,18 @@ igraph.i.attribute.combination <- function(comb, allow_rename = FALSE) { #' This results almost always a complex attribute. #' } #' \item{"rename"}{ -#' Keep clashing attributes side-by-side under disambiguated names by -#' appending `_1`, `_2`, ... suffixes. For example, if two graphs each -#' have an attribute called `group`, the resulting graph will have -#' attributes `group_1` and `group_2`, corresponding to the first and -#' second input graph, respectively. This is the default for the -#' graph operators [union()], [intersection()], [compose()] and -#' [disjoint_union()] and preserves their historical behaviour. -#' Only those operators accept `"rename"`; [simplify()] and -#' [contract()] will reject it because the rename strategy has no -#' per-element interpretation when many input values collapse into one. +#' Keep clashing attributes side-by-side under disambiguated names by appending `_1`, `_2`, ... suffixes. +#' For example, if two graphs each have an attribute called `group`, the resulting graph will have attributes `group_1` and `group_2`, +#' corresponding to the first and second input graph, respectively. +#' This is the default for the graph operators [union()], [intersection()], [compose()] and [disjoint_union()] +#' and preserves their historical behaviour. +#' Only those operators accept `"rename"`; [simplify()] and [contract()] will reject it because the rename strategy has no per-element interpretation +#' when many input values collapse into one. #' } #' } #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso [graph_attr()], [vertex_attr()], -#' [edge_attr()] on how to use graph/vertex/edge attributes in -#' general. [igraph_options()] on igraph parameters. +#' @seealso [graph_attr()], [vertex_attr()], [edge_attr()] on how to use graph/vertex/edge attributes in general. +#' [igraph_options()] on igraph parameters. #' @keywords graphs #' @examples #' @@ -1521,9 +1477,8 @@ NULL #' Getting and setting graph attributes, shortcut #' -#' The `$` operator is a shortcut to get and and set -#' graph attributes. It is shorter and just as readable as -#' [graph_attr()] and [set_graph_attr()]. +#' The `$` operator is a shortcut to get and and set graph attributes. +#' It is shorter and just as readable as [graph_attr()] and [set_graph_attr()]. #' #' @param x An igraph graph #' @param name Name of the attribute to get/set. diff --git a/R/basic.R b/R/basic.R index 4769854df36..007de8191a9 100644 --- a/R/basic.R +++ b/R/basic.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `is.igraph()` was renamed to [is_igraph()] to create a more -#' consistent API. +#' `is.igraph()` was renamed to [is_igraph()] to create a more consistent API. #' @inheritParams is_igraph #' @keywords internal #' @export @@ -37,8 +36,7 @@ is.igraph <- function(graph) { #' Is this object an igraph graph? #' #' @param graph An R object. -#' @return A logical constant, `TRUE` if argument `graph` is a graph -#' object. +#' @return A logical constant, `TRUE` if argument `graph` is a graph object. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @export #' @keywords graphs @@ -58,9 +56,8 @@ is_igraph <- function(graph) { #' Head of the edge(s) in a graph #' -#' For undirected graphs, head and tail is not defined. In this case -#' `head_of()` returns vertices incident to the supplied edges, and -#' `tail_of()` returns the other end(s) of the edge(s). +#' For undirected graphs, head and tail is not defined. +#' In this case `head_of()` returns vertices incident to the supplied edges, and `tail_of()` returns the other end(s) of the edge(s). #' #' @param graph The input graph. #' @param es The edges to query. @@ -75,9 +72,8 @@ head_of <- function(graph, es) { #' Tails of the edge(s) in a graph #' -#' For undirected graphs, head and tail is not defined. In this case -#' `tail_of()` returns vertices incident to the supplied edges, and -#' `head_of()` returns the other end(s) of the edge(s). +#' For undirected graphs, head and tail is not defined. +#' In this case `tail_of()` returns vertices incident to the supplied edges, and `head_of()` returns the other end(s) of the edge(s). #' #' @param graph The input graph. #' @param es The edges to query. diff --git a/R/bipartite.R b/R/bipartite.R index 27d99b8f0c1..db526f38fa2 100644 --- a/R/bipartite.R +++ b/R/bipartite.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `bipartite.projection.size()` was renamed to [bipartite_projection_size()] to create a more -#' consistent API. +#' `bipartite.projection.size()` was renamed to [bipartite_projection_size()] to create a more consistent API. #' @inheritParams bipartite_projection_size #' @keywords internal #' @export @@ -23,8 +22,7 @@ bipartite.projection.size <- function(graph, types = NULL) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `bipartite.projection()` was renamed to [bipartite_projection()] to create a more -#' consistent API. +#' `bipartite.projection()` was renamed to [bipartite_projection()] to create a more consistent API. #' @inheritParams bipartite_projection #' @keywords internal #' @export @@ -57,8 +55,7 @@ bipartite.projection <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `bipartite.mapping()` was renamed to [bipartite_mapping()] to create a more -#' consistent API. +#' `bipartite.mapping()` was renamed to [bipartite_mapping()] to create a more consistent API. #' @inheritParams bipartite_mapping #' @keywords internal #' @export @@ -96,46 +93,39 @@ bipartite.mapping <- function(graph) { #' #' A bipartite graph is projected into two one-mode networks #' -#' Bipartite graphs have a `type` vertex attribute in igraph, this is -#' boolean and `FALSE` for the vertices of the first kind and `TRUE` -#' for vertices of the second kind. +#' Bipartite graphs have a `type` vertex attribute in igraph, +#' this is boolean and `FALSE` for the vertices of the first kind and `TRUE` for vertices of the second kind. #' -#' `bipartite_projection_size()` calculates the number of vertices and edges -#' in the two projections of the bipartite graphs, without calculating the -#' projections themselves. This is useful to check how much memory the -#' projections would need if you have a large bipartite graph. +#' `bipartite_projection_size()` calculates the number of vertices and edges in the two projections of the bipartite graphs, +#' without calculating the projections themselves. +#' This is useful to check how much memory the projections would need if you have a large bipartite graph. #' -#' `bipartite_projection()` calculates the actual projections. You can use -#' the `probe1` argument to specify the order of the projections in the -#' result. By default vertex type `FALSE` is the first and `TRUE` is -#' the second. +#' `bipartite_projection()` calculates the actual projections. +#' You can use the `probe1` argument to specify the order of the projections in the result. +#' By default vertex type `FALSE` is the first and `TRUE` is the second. #' #' `bipartite_projection()` keeps vertex attributes. #' -#' @param graph The input graph. It can be directed, but edge directions are -#' ignored during the computation. -#' @param types An optional vertex type vector to use instead of the -#' \sQuote{`type`} vertex attribute. You must supply this argument if the -#' graph has no \sQuote{`type`} vertex attribute. +#' @param graph The input graph. +#' It can be directed, but edge directions are ignored during the computation. +#' @param types An optional vertex type vector to use instead of the \sQuote{`type`} vertex attribute. +#' You must supply this argument if the graph has no \sQuote{`type`} vertex attribute. #' @inheritParams rlang::args_dots_empty -#' @param multiplicity If `TRUE`, then igraph keeps the multiplicity of -#' the edges as an edge attribute called \sQuote{weight}. -#' E.g. if there is an A-C-B and also an A-D-B -#' triple in the bipartite graph (but no more X, such that A-X-B is also in the -#' graph), then the multiplicity of the A-B edge in the projection will be 2. -#' @param probe1 This argument can be used to specify the order of the -#' projections in the resulting list. If given, then it is considered as a -#' vertex ID (or a symbolic vertex name); the projection containing this vertex -#' will be the first one in the result list. This argument is ignored if only -#' one projection is requested in argument `which`. +#' @param multiplicity If `TRUE`, then igraph keeps the multiplicity of the edges as an edge attribute called \sQuote{weight}. +#' E.g. if there is an A-C-B and also an A-D-B triple in the bipartite graph (but no more X, such that A-X-B is also in the graph), +#' then the multiplicity of the A-B edge in the projection will be 2. +#' @param probe1 This argument can be used to specify the order of the projections in the resulting list. +#' If given, then it is considered as a vertex ID (or a symbolic vertex name); +#' the projection containing this vertex will be the first one in the result list. +#' This argument is ignored if only one projection is requested in argument `which`. #' @param which A character scalar to specify which projection(s) to calculate. #' The default is to calculate both. -#' @param remove.type Logical, whether to remove the `type` vertex -#' attribute from the projections. This makes sense because these graphs are -#' not bipartite any more. However if you want to combine them with each other -#' (or other bipartite graphs), then it is worth keeping this attribute. By -#' default it will be removed. -#' @return A list of two undirected graphs. See details above. +#' @param remove.type Logical, whether to remove the `type` vertex attribute from the projections. +#' This makes sense because these graphs are not bipartite any more. +#' However if you want to combine them with each other (or other bipartite graphs), then it is worth keeping this attribute. +#' By default it will be removed. +#' @return A list of two undirected graphs. +#' See details above. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @family bipartite #' @export @@ -278,23 +268,19 @@ bipartite_projection_size <- function(graph, types = NULL) { #' Decide whether a graph is bipartite #' -#' This function decides whether the vertices of a network can be mapped to two -#' vertex types in a way that no vertices of the same type are connected. +#' This function decides whether the vertices of a network can be mapped to two vertex types in a way that no vertices of the same type are connected. #' -#' A bipartite graph in igraph has a \sQuote{`type`} vertex attribute -#' giving the two vertex types. +#' A bipartite graph in igraph has a \sQuote{`type`} vertex attribute giving the two vertex types. #' -#' This function simply checks whether a graph *could* be bipartite. It -#' tries to find a mapping that gives a possible division of the vertices into -#' two classes, such that no two vertices of the same class are connected by an -#' edge. +#' This function simply checks whether a graph *could* be bipartite. +#' It tries to find a mapping that gives a possible division of the vertices into two classes, +#' such that no two vertices of the same class are connected by an edge. #' -#' The existence of such a mapping is equivalent of having no circuits of odd -#' length in the graph. A graph with loop edges cannot bipartite. +#' The existence of such a mapping is equivalent of having no circuits of odd length in the graph. +#' A graph with loop edges cannot bipartite. #' -#' Note that the mapping is not necessarily unique, e.g. if the graph has at -#' least two components, then the vertices in the separate components can be -#' mapped independently. +#' Note that the mapping is not necessarily unique, e.g. if the graph has at least two components, +#' then the vertices in the separate components can be mapped independently. #' #' @param graph The input graph. #' @return A named list with two elements: diff --git a/R/centrality.R b/R/centrality.R index aa62926c4be..eaee14957c4 100644 --- a/R/centrality.R +++ b/R/centrality.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `subgraph.centrality()` was renamed to [subgraph_centrality()] to create a more -#' consistent API. +#' `subgraph.centrality()` was renamed to [subgraph_centrality()] to create a more consistent API. #' @inheritParams subgraph_centrality #' @keywords internal #' @export @@ -23,8 +22,7 @@ subgraph.centrality <- function(graph, diag = FALSE) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `page.rank()` was renamed to [page_rank()] to create a more -#' consistent API. +#' `page.rank()` was renamed to [page_rank()] to create a more consistent API. #' @inheritParams page_rank #' @keywords internal #' @export @@ -57,8 +55,7 @@ page.rank <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `hub.score()` was renamed to [hub_score()] to create a more -#' consistent API. +#' `hub.score()` was renamed to [hub_score()] to create a more consistent API. #' @inheritParams hub_score #' @keywords internal #' @export @@ -76,8 +73,7 @@ hub.score <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `authority.score()` was renamed to [authority_score()] to create a more -#' consistent API. +#' `authority.score()` was renamed to [authority_score()] to create a more consistent API. #' @inheritParams authority_score #' @keywords internal #' @export @@ -95,8 +91,7 @@ authority.score <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.strength()` was renamed to [strength()] to create a more -#' consistent API. +#' `graph.strength()` was renamed to [strength()] to create a more consistent API. #' @inheritParams strength #' @keywords internal #' @export @@ -123,8 +118,7 @@ graph.strength <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.eigen()` was renamed to [spectrum()] to create a more -#' consistent API. +#' `graph.eigen()` was renamed to [spectrum()] to create a more consistent API. #' @inheritParams spectrum #' @keywords internal #' @export @@ -156,8 +150,7 @@ graph.eigen <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.diversity()` was renamed to [diversity()] to create a more -#' consistent API. +#' `graph.diversity()` was renamed to [diversity()] to create a more consistent API. #' @inheritParams diversity #' @keywords internal #' @export @@ -172,8 +165,7 @@ graph.diversity <- function(graph, weights = NULL, vids = V(graph)) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `evcent()` was renamed to [eigen_centrality()] to create a more -#' consistent API. +#' `evcent()` was renamed to [eigen_centrality()] to create a more consistent API. #' @inheritParams eigen_centrality #' @keywords internal #' @export @@ -200,8 +192,7 @@ evcent <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `edge.betweenness()` was renamed to [edge_betweenness()] to create a more -#' consistent API. +#' `edge.betweenness()` was renamed to [edge_betweenness()] to create a more consistent API. #' @inheritParams edge_betweenness #' @keywords internal #' @export @@ -228,8 +219,7 @@ edge.betweenness <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `bonpow()` was renamed to [power_centrality()] to create a more -#' consistent API. +#' `bonpow()` was renamed to [power_centrality()] to create a more consistent API. #' @inheritParams power_centrality #' @keywords internal #' @export @@ -260,8 +250,7 @@ bonpow <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `alpha.centrality()` was renamed to [alpha_centrality()] to create a more -#' consistent API. +#' `alpha.centrality()` was renamed to [alpha_centrality()] to create a more consistent API. #' @inheritParams alpha_centrality #' @keywords internal #' @export @@ -315,8 +304,7 @@ alpha.centrality <- function( #' `r lifecycle::badge("deprecated")` #' #' Use [betweenness()] with the `cutoff` argument instead. -#' @param vids The vertices for which the vertex betweenness estimation will be -#' calculated. +#' @param vids The vertices for which the vertex betweenness estimation will be calculated. #' @inheritParams betweenness #' @keywords internal #' @export @@ -349,8 +337,7 @@ betweenness.estimate <- estimate_betweenness #' Vertex and edge betweenness centrality #' -#' The vertex and edge betweenness are (roughly) defined by the number of -#' geodesics (shortest paths) going through a vertex or an edge. +#' The vertex and edge betweenness are (roughly) defined by the number of geodesics (shortest paths) going through a vertex or an edge. #' #' The vertex betweenness of vertex `v` is defined by #' @@ -361,22 +348,17 @@ betweenness.estimate <- estimate_betweenness #' #' \deqn{\sum_{i\ne j} g_{iej}/g_{ij}.}{sum( g_iej / g_ij, i!=j).} #' -#' `betweenness()` calculates vertex betweenness, `edge_betweenness()` -#' calculates edge betweenness. +#' `betweenness()` calculates vertex betweenness, `edge_betweenness()` calculates edge betweenness. #' -#' Here \eqn{g_{ij}}{g_ij} is the total number of shortest paths between vertices -#' \eqn{i} and \eqn{j} while \eqn{g_{ivj}} is the number of those shortest paths -#' which pass though vertex \eqn{v}. +#' Here \eqn{g_{ij}}{g_ij} is the total number of shortest paths between vertices \eqn{i} and \eqn{j} +#' while \eqn{g_{ivj}} is the number of those shortest paths which pass though vertex \eqn{v}. #' -#' Both functions allow you to consider only paths of length `cutoff` or -#' smaller; this can be run for larger graphs, as the running time is not -#' quadratic (if `cutoff` is small). If `cutoff` is negative (the default), -#' then the function calculates the exact betweenness scores. Since igraph 1.6.0, -#' a `cutoff` value of zero is treated literally, i.e. paths of length larger -#' than zero are ignored. +#' Both functions allow you to consider only paths of length `cutoff` or smaller; this can be run for larger graphs, +#' as the running time is not quadratic (if `cutoff` is small). +#' If `cutoff` is negative (the default), then the function calculates the exact betweenness scores. +#' Since igraph 1.6.0, a `cutoff` value of zero is treated literally, i.e. paths of length larger than zero are ignored. #' -#' For calculating the betweenness a similar algorithm to the one proposed by -#' Brandes (see References) is used. +#' For calculating the betweenness a similar algorithm to the one proposed by Brandes (see References) is used. #' #' @aliases betweenness.estimate #' @aliases edge.betweenness.estimate @@ -384,33 +366,25 @@ betweenness.estimate <- estimate_betweenness #' @param v The vertices for which the vertex betweenness will be calculated. #' The default `NULL` selects all vertices. #' @inheritParams rlang::args_dots_empty -#' @param directed Logical, whether directed paths should be considered while -#' determining the shortest paths. -#' @param weights Optional positive weight vector for calculating weighted -#' betweenness. If the graph has a `weight` edge attribute, then this is -#' used by default. Weights are used to calculate weighted shortest paths, -#' so they are interpreted as distances. -#' @param normalized Logical, whether to normalize the betweenness -#' scores. If `TRUE`, then the results are normalized by the number of ordered -#' or unordered vertex pairs in directed and undirected graphs, respectively. +#' @param directed Logical, whether directed paths should be considered while determining the shortest paths. +#' @param weights Optional positive weight vector for calculating weighted betweenness. +#' If the graph has a `weight` edge attribute, then this is used by default. +#' Weights are used to calculate weighted shortest paths, so they are interpreted as distances. +#' @param normalized Logical, whether to normalize the betweenness scores. +#' If `TRUE`, +#' then the results are normalized by the number of ordered or unordered vertex pairs in directed and undirected graphs, respectively. #' In an undirected graph, #' \deqn{B^n=\frac{2B}{(n-1)(n-2)},}{Bnorm=2 B / ((n-1)(n-2)),} -#' where -#' \eqn{B^n}{Bnorm} is the normalized, \eqn{B} the raw betweenness, and -#' \eqn{n} is the number of vertices in the graph. Note that the same -#' normalization factor is used even when setting a `cutoff` on the considered -#' shortest path lengths, even though the number of vertex pairs reachable -#' from each other may be less than \eqn{(n-1)(n-2)/2}. -#' @param cutoff The maximum shortest path length to consider when calculating -#' betweenness. If negative, then there is no such limit. -#' @return A numeric vector with the betweenness score for each vertex in -#' `v` for `betweenness()`. -#' -#' A numeric vector with the edge betweenness score for each edge in `e` -#' for `edge_betweenness()`. -#' -#' @note `edge_betweenness()` might give false values for graphs with -#' multiple edges. +#' where \eqn{B^n}{Bnorm} is the normalized, \eqn{B} the raw betweenness, and \eqn{n} is the number of vertices in the graph. +#' Note that the same normalization factor is used even when setting a `cutoff` on the considered shortest path lengths, +#' even though the number of vertex pairs reachable from each other may be less than \eqn{(n-1)(n-2)/2}. +#' @param cutoff The maximum shortest path length to consider when calculating betweenness. +#' If negative, then there is no such limit. +#' @return A numeric vector with the betweenness score for each vertex in `v` for `betweenness()`. +#' +#' A numeric vector with the edge betweenness score for each edge in `e` for `edge_betweenness()`. +#' +#' @note `edge_betweenness()` might give false values for graphs with multiple edges. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @seealso [closeness()], [degree()], [harmonic_centrality()] #' @references Freeman, L.C. (1979). Centrality in Social Networks I: @@ -603,51 +577,40 @@ edge.betweenness.estimate <- estimate_edge_betweenness #' Closeness centrality of vertices #' -#' Closeness centrality measures how many steps are required to access every other -#' vertex from a given vertex. +#' Closeness centrality measures how many steps are required to access every other vertex from a given vertex. #' -#' The closeness centrality of a vertex is defined as the inverse of the -#' sum of distances to all the other vertices in the graph: +#' The closeness centrality of a vertex is defined as the inverse of the sum of distances to all the other vertices in the graph: #' #' \deqn{\frac{1}{\sum_{i\ne v} d_{vi}}}{1/sum( d(v,i), i != v)} #' -#' If there is no (directed) path between vertex `v` and `i`, then -#' `i` is omitted from the calculation. If no other vertices are reachable -#' from `v`, then its closeness is returned as NaN. +#' If there is no (directed) path between vertex `v` and `i`, then `i` is omitted from the calculation. +#' If no other vertices are reachable from `v`, then its closeness is returned as NaN. #' # " You may use the \code{cutoff} argument to consider only paths of length -#' `cutoff` or smaller. This can be run for larger graphs, as the running -#' time is not quadratic (if `cutoff` is small). If `cutoff` is -#' negative (which is the default), then the function calculates the exact -#' closeness scores. Since igraph 1.6.0, a `cutoff` value of zero is treated -#' literally, i.e. path with a length greater than zero are ignored. +#' `cutoff` or smaller. +#' This can be run for larger graphs, as the running time is not quadratic (if `cutoff` is small). +#' If `cutoff` is negative (which is the default), then the function calculates the exact closeness scores. +#' Since igraph 1.6.0, a `cutoff` value of zero is treated literally, i.e. path with a length greater than zero are ignored. #' -#' Closeness centrality is meaningful only for connected graphs. In disconnected -#' graphs, consider using the harmonic centrality with -#' [harmonic_centrality()] +#' Closeness centrality is meaningful only for connected graphs. +#' In disconnected graphs, consider using the harmonic centrality with [harmonic_centrality()] #' #' @aliases closeness.estimate #' @param graph The graph to analyze. #' @param vids The vertices for which closeness will be calculated. #' The default `NULL` selects all vertices. #' @inheritParams rlang::args_dots_empty -#' @param mode Character string, defined the types of the paths used for -#' measuring the distance in directed graphs. \dQuote{in} measures the paths -#' *to* a vertex, \dQuote{out} measures paths *from* a vertex, -#' *all* uses undirected paths. This argument is ignored for undirected -#' graphs. -#' @param normalized Logical, whether to calculate the normalized -#' closeness, i.e. the inverse average distance to all reachable vertices. -#' The non-normalized closeness is the inverse of the sum of distances to -#' all reachable vertices. -#' @param weights Optional positive weight vector for calculating weighted -#' closeness. If the graph has a `weight` edge attribute, then this is -#' used by default. Weights are used for calculating weighted shortest -#' paths, so they are interpreted as distances. -#' @param cutoff The maximum path length to consider when calculating the -#' closeness. If zero or negative then there is no such limit. -#' @return Numeric vector with the closeness values of all the vertices in -#' `v`. +#' @param mode Character string, defined the types of the paths used for measuring the distance in directed graphs. +#' \dQuote{in} measures the paths *to* a vertex, \dQuote{out} measures paths *from* a vertex, *all* uses undirected paths. +#' This argument is ignored for undirected graphs. +#' @param normalized Logical, whether to calculate the normalized closeness, i.e. the inverse average distance to all reachable vertices. +#' The non-normalized closeness is the inverse of the sum of distances to all reachable vertices. +#' @param weights Optional positive weight vector for calculating weighted closeness. +#' If the graph has a `weight` edge attribute, then this is used by default. +#' Weights are used for calculating weighted shortest paths, so they are interpreted as distances. +#' @param cutoff The maximum path length to consider when calculating the closeness. +#' If zero or negative then there is no such limit. +#' @return Numeric vector with the closeness values of all the vertices in `v`. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @references Freeman, L.C. (1979). Centrality in Social Networks I: #' Conceptual Clarification. *Social Networks*, 1, 215-239. @@ -787,32 +750,27 @@ arpack_defaults <- function() { #' ARPACK eigenvector calculation #' -#' Interface to the ARPACK library for calculating eigenvectors of sparse -#' matrices +#' Interface to the ARPACK library for calculating eigenvectors of sparse matrices #' #' @details -#' ARPACK is a library for solving large scale eigenvalue problems. The -#' package is designed to compute a few eigenvalues and corresponding -#' eigenvectors of a general \eqn{n} by \eqn{n} matrix \eqn{A}. It is most -#' appropriate for large sparse or structured matrices \eqn{A} where structured -#' means that a matrix-vector product `w <- Av` requires order \eqn{n} -#' rather than the usual order \eqn{n^2} floating point operations. -#' -#' This function is an interface to ARPACK. igraph does not contain all ARPACK -#' routines, only the ones dealing with symmetric and non-symmetric eigenvalue -#' problems using double precision real numbers. -#' -#' The eigenvalue calculation in ARPACK (in the simplest case) involves the -#' calculation of the \eqn{Av} product where \eqn{A} is the matrix we work with -#' and \eqn{v} is an arbitrary vector. The function supplied in the `fun` -#' argument is expected to perform this product. If the product can be done -#' efficiently, e.g. if the matrix is sparse, then `arpack()` is usually -#' able to calculate the eigenvalues very quickly. +#' ARPACK is a library for solving large scale eigenvalue problems. +#' The package is designed to compute a few eigenvalues and corresponding eigenvectors of a general \eqn{n} by \eqn{n} matrix \eqn{A}. +#' It is most appropriate for large sparse or structured matrices \eqn{A} +#' where structured means that a matrix-vector product `w <- Av` requires order \eqn{n} rather than the usual order \eqn{n^2} floating point operations. +#' +#' This function is an interface to ARPACK. igraph does not contain all ARPACK routines, +#' only the ones dealing with symmetric and non-symmetric eigenvalue problems using double precision real numbers. +#' +#' The eigenvalue calculation in ARPACK (in the simplest case) involves the calculation of the \eqn{Av} product +#' where \eqn{A} is the matrix we work with and \eqn{v} is an arbitrary vector. +#' The function supplied in the `fun` argument is expected to perform this product. +#' If the product can be done efficiently, e.g. if the matrix is sparse, +#' then `arpack()` is usually able to calculate the eigenvalues very quickly. #' #' @details #' The `options` argument specifies what kind of calculation to perform. -#' It is a list with the following members, they correspond directly to ARPACK -#' parameters. On input it has the following fields: +#' It is a list with the following members, they correspond directly to ARPACK parameters. +#' On input it has the following fields: #' \describe{ #' \item{bmat}{ #' Character constant, possible values: @@ -875,8 +833,8 @@ arpack_defaults <- function() { #' Numeric scalar. The number of eigenvalues to be computed. #' } #' \item{tol}{ -#' Numeric scalar. Stopping criterion: -#' the relative accuracy of the Ritz value is considered acceptable +#' Numeric scalar. +#' Stopping criterion: the relative accuracy of the Ritz value is considered acceptable #' if its error is less than `tol` times its estimated value. #' If this is set to zero then machine precision is used. #' } @@ -899,7 +857,8 @@ arpack_defaults <- function() { #' Blocksize to be used in the recurrence. Please always leave this on the default value, one. #' } #' \item{mode}{ -#' The type of the eigenproblem to be solved. Possible values if the input matrix is symmetric: +#' The type of the eigenproblem to be solved. +#' Possible values if the input matrix is symmetric: #' \describe{ #' \item{1}{ #' \eqn{Ax=\lambda x}{A*x=lambda*x}, \eqn{A} is symmetric. @@ -990,22 +949,19 @@ arpack_defaults <- function() { #' #' @aliases arpack arpack-options arpack.unpack.complex #' @aliases arpack_defaults -#' @param func The function to perform the matrix-vector multiplication. ARPACK -#' requires to perform these by the user. The function gets the vector \eqn{x} -#' as the first argument, and it should return \eqn{Ax}, where \eqn{A} is the -#' \dQuote{input matrix}. (The input matrix is never given explicitly.) The -#' second argument is `extra`. +#' @param func The function to perform the matrix-vector multiplication. +#' ARPACK requires to perform these by the user. +#' The function gets the vector \eqn{x} as the first argument, and it should return \eqn{Ax}, where \eqn{A} is the \dQuote{input matrix}. +#' (The input matrix is never given explicitly.) The second argument is `extra`. #' @param extra Extra argument to supply to `func`. -#' @param sym Logical, whether the input matrix is symmetric. Always -#' supply `TRUE` here if it is, since it can speed up the computation. -#' @param options Options to ARPACK, a named list to overwrite some of the -#' default option values. See details below. +#' @param sym Logical, whether the input matrix is symmetric. +#' Always supply `TRUE` here if it is, since it can speed up the computation. +#' @param options Options to ARPACK, a named list to overwrite some of the default option values. +#' See details below. #' @param env The environment in which `func` will be evaluated. -#' @param complex Whether to convert the eigenvectors returned by ARPACK into R -#' complex vectors. By default this is not done for symmetric problems (these -#' only have real eigenvectors/values), but only non-symmetric ones. If you -#' have a non-symmetric problem, but you're sure that the results will be real, -#' then supply `FALSE` here. +#' @param complex Whether to convert the eigenvectors returned by ARPACK into R complex vectors. +#' By default this is not done for symmetric problems (these only have real eigenvectors/values), but only non-symmetric ones. +#' If you have a non-symmetric problem, but you're sure that the results will be real, then supply `FALSE` here. #' @return A named list with the following members: #' \describe{ #' \item{values}{ @@ -1024,9 +980,8 @@ arpack_defaults <- function() { #' } #' @author Rich Lehoucq, Kristi Maschhoff, Danny Sorensen, Chao Yang for #' ARPACK, Gabor Csardi \email{csardi.gabor@@gmail.com} for the R interface. -#' @seealso [eigen_centrality()], [page_rank()], -#' [hub_score()], [cluster_leading_eigen()] are some of the -#' functions in igraph that use ARPACK. +#' @seealso [eigen_centrality()], [page_rank()], [hub_score()], +#' [cluster_leading_eigen()] are some of the functions in igraph that use ARPACK. #' @references D.C. Sorensen, Implicit Application of Polynomial Filters in a #' k-Step Arnoldi Method. *SIAM J. Matr. Anal. Apps.*, 13 (1992), pp #' 357-385. @@ -1171,22 +1126,19 @@ arpack.unpack.complex <- function(vectors, values, nev) { #' Find subgraph centrality scores of network positions #' -#' Subgraph centrality of a vertex measures the number of subgraphs a vertex -#' participates in, weighting them according to their size. +#' Subgraph centrality of a vertex measures the number of subgraphs a vertex participates in, weighting them according to their size. #' -#' The subgraph centrality of a vertex is defined as the number of closed walks -#' originating at the vertex, where longer walks are downweighted by the -#' factorial of their length. +#' The subgraph centrality of a vertex is defined as the number of closed walks originating at the vertex, +#' where longer walks are downweighted by the factorial of their length. #' -#' Currently the calculation is performed by explicitly calculating all -#' eigenvalues and eigenvectors of the adjacency matrix of the graph. This -#' effectively means that the measure can only be calculated for small graphs. +#' Currently the calculation is performed by explicitly calculating all eigenvalues and eigenvectors of the adjacency matrix of the graph. +#' This effectively means that the measure can only be calculated for small graphs. #' -#' @param graph The input graph. It will be treated as undirected. +#' @param graph The input graph. +#' It will be treated as undirected. #' @inheritParams rlang::args_dots_empty -#' @param diag Logical, whether to include the diagonal of the adjacency -#' matrix in the analysis. Giving `FALSE` here effectively eliminates the -#' loops edges from the graph before the calculation. +#' @param diag Logical, whether to include the diagonal of the adjacency matrix in the analysis. +#' Giving `FALSE` here effectively eliminates the loops edges from the graph before the calculation. #' @return A numeric vector, the subgraph centrality scores of the vertices. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} based on the Matlab #' code by Ernesto Estrada @@ -1263,11 +1215,9 @@ subgraph_centrality <- function( #' Eigenvalues and eigenvectors of the adjacency matrix of a graph #' -#' Calculate selected eigenvalues and eigenvectors of a (supposedly sparse) -#' graph. +#' Calculate selected eigenvalues and eigenvectors of a (supposedly sparse) graph. #' -#' The `which` argument is a list and it specifies which eigenvalues and -#' corresponding eigenvectors to calculate: There are eight options: +#' The `which` argument is a list and it specifies which eigenvalues and corresponding eigenvectors to calculate: There are eight options: #' \enumerate{ \item Eigenvalues with the largest magnitude. Set `pos` to #' `LM`, and `howmany` to the number of eigenvalues you want. \item #' Eigenvalues with the smallest magnitude. Set `pos` to `SM` and @@ -1288,13 +1238,13 @@ subgraph_centrality <- function( #' #' @aliases spectrum igraph.eigen.default #' @param graph The input graph, can be directed or undirected. -#' @param algorithm The algorithm to use. Currently only `arpack` is -#' implemented, which uses the ARPACK solver. See also [arpack()]. -#' @param which A list to specify which eigenvalues and eigenvectors to -#' calculate. By default the leading (i.e. largest magnitude) eigenvalue and -#' the corresponding eigenvector is calculated. -#' @param options Options for the ARPACK solver. See -#' [arpack_defaults()]. +#' @param algorithm The algorithm to use. +#' Currently only `arpack` is implemented, which uses the ARPACK solver. +#' See also [arpack()]. +#' @param which A list to specify which eigenvalues and eigenvectors to calculate. +#' By default the leading (i.e. largest magnitude) eigenvalue and the corresponding eigenvector is calculated. +#' @param options Options for the ARPACK solver. +#' See [arpack_defaults()]. #' @return Depends on the algorithm used. #' #' For `arpack` a list with three entries is returned: @@ -1376,68 +1326,55 @@ eigen_defaults <- function() { #' Eigenvector centrality of vertices #' -#' `eigen_centrality()` takes a graph (`graph`) and returns the -#' eigenvector centralities of the vertices `v` within it. -#' -#' Eigenvector centrality scores correspond to the values of the principal -#' eigenvector of the graph's adjacency matrix; these scores may, in turn, be -#' interpreted as arising from a reciprocal process in which the centrality of -#' each actor is proportional to the sum of the centralities of those actors to -#' whom he or she is connected. In general, vertices with high eigenvector -#' centralities are those which are connected to many other vertices which are, -#' in turn, connected to many others (and so on). The perceptive may realize -#' that this implies that the largest values will be obtained by individuals in -#' large cliques (or high-density substructures). This is also intelligible -#' from an algebraic point of view, with the first eigenvector being closely -#' related to the best rank-1 approximation of the adjacency matrix (a -#' relationship which is easy to see in the special case of a diagonalizable -#' symmetric real matrix via the \eqn{SLS^-1}{$S \Lambda S^{-1}$} -#' decomposition). -#' -#' The adjacency matrix used in the eigenvector centrality calculation assumes -#' that loop edges are counted *twice* in undirected graphs; this is because -#' each loop edge has *two* endpoints that are both connected to the same vertex, +#' `eigen_centrality()` takes a graph (`graph`) and returns the eigenvector centralities of the vertices `v` within it. +#' +#' Eigenvector centrality scores correspond to the values of the principal eigenvector of the graph's adjacency matrix; these scores may, +#' in turn, +#' be interpreted as arising from a reciprocal process +#' in which the centrality of each actor is proportional to the sum of the centralities of those actors to whom he or she is connected. +#' In general, +#' vertices with high eigenvector centralities are those which are connected to many other vertices which are, in turn, +#' connected to many others (and so on). +#' The perceptive may realize that this implies +#' that the largest values will be obtained by individuals in large cliques (or high-density substructures). +#' This is also intelligible from an algebraic point of view, +#' with the first eigenvector being closely related to the best rank-1 approximation of the adjacency matrix (a relationship which is easy to see in the special case of a diagonalizable symmetric real matrix via the \eqn{SLS^-1}{$S \Lambda S^{-1}$} decomposition). +#' +#' The adjacency matrix used in the eigenvector centrality calculation assumes that loop edges are counted *twice* in undirected graphs; +#' this is because each loop edge has *two* endpoints that are both connected to the same vertex, #' and you could traverse the loop edge via either endpoint. #' -#' In the directed case, the left eigenvector of the adjacency matrix is -#' calculated. In other words, the centrality of a vertex is proportional to -#' the sum of centralities of vertices pointing to it. +#' In the directed case, the left eigenvector of the adjacency matrix is calculated. +#' In other words, the centrality of a vertex is proportional to the sum of centralities of vertices pointing to it. #' #' Eigenvector centrality is meaningful only for (strongly) connected graphs. -#' Undirected graphs that are not connected should be decomposed into connected -#' components, and the eigenvector centrality calculated for each separately. -#' This function does not verify that the graph is connected. If it is not, in -#' the undirected case the scores of all but one component will be zeros. -#' -#' Also note that the adjacency matrix of a directed acyclic graph or the -#' adjacency matrix of an empty graph does not possess positive eigenvalues, -#' therefore the eigenvector centrality is not defined for these graphs. -#' igraph will return an eigenvalue of zero in such cases. The eigenvector -#' centralities will all be equal for an empty graph and will all be zeros for -#' a directed acyclic graph. Such pathological cases can be detected by checking -#' whether the eigenvalue is very close to zero. -#' -#' From igraph version 0.5 this function uses ARPACK for the underlying -#' computation, see [arpack()] for more about ARPACK in igraph. +#' Undirected graphs that are not connected should be decomposed into connected components, +#' and the eigenvector centrality calculated for each separately. +#' This function does not verify that the graph is connected. +#' If it is not, in the undirected case the scores of all but one component will be zeros. +#' +#' Also note that the adjacency matrix of a directed acyclic graph or the adjacency matrix of an empty graph does not possess positive eigenvalues, +#' therefore the eigenvector centrality is not defined for these graphs. igraph will return an eigenvalue of zero in such cases. +#' The eigenvector centralities will all be equal for an empty graph and will all be zeros for a directed acyclic graph. +#' Such pathological cases can be detected by checking whether the eigenvalue is very close to zero. +#' +#' From igraph version 0.5 this function uses ARPACK for the underlying computation, see [arpack()] for more about ARPACK in igraph. #' #' @param graph Graph to be analyzed. -#' @param directed Logical, whether to consider direction of the edges -#' in directed graphs. It is ignored for undirected graphs. -#' @param scale `r lifecycle::badge("deprecated")` Normalization will always take -#' place. -#' @param weights A numerical vector or `NULL`. This argument can be used -#' to give edge weights for calculating the weighted eigenvector centrality of -#' vertices. If this is `NULL` and the graph has a `weight` edge -#' attribute then that is used. If `weights` is a numerical vector then it is -#' used, even if the graph has a `weight` edge attribute. If this is -#' `NA`, then no edge weights are used (even if the graph has a -#' `weight` edge attribute). Note that if there are negative edge weights -#' and the direction of the edges is considered, then the eigenvector might be -#' complex. In this case only the real part is reported. -#' This function interprets weights as connection strength. Higher -#' weights spread the centrality better. -#' @param options A named list, to override some ARPACK options. See -#' [arpack()] for details. +#' @param directed Logical, whether to consider direction of the edges in directed graphs. +#' It is ignored for undirected graphs. +#' @param scale `r lifecycle::badge("deprecated")` Normalization will always take place. +#' @param weights A numerical vector or `NULL`. +#' This argument can be used to give edge weights for calculating the weighted eigenvector centrality of vertices. +#' If this is `NULL` and the graph has a `weight` edge attribute then that is used. +#' If `weights` is a numerical vector then it is used, even if the graph has a `weight` edge attribute. +#' If this is `NA`, then no edge weights are used (even if the graph has a `weight` edge attribute). +#' Note that if there are negative edge weights and the direction of the edges is considered, then the eigenvector might be complex. +#' In this case only the real part is reported. +#' This function interprets weights as connection strength. +#' Higher weights spread the centrality better. +#' @param options A named list, to override some ARPACK options. +#' See [arpack()] for details. #' @return A named list with components: #' \describe{ #' \item{vector}{ @@ -1516,15 +1453,13 @@ eigen_centrality <- function( #' @param vids The vertices for which the strength will be calculated. #' The default `NULL` selects all vertices. #' @inheritParams rlang::args_dots_empty -#' @param mode Character string, \dQuote{out} for out-degree, \dQuote{in} for -#' in-degree or \dQuote{all} for the sum of the two. For undirected graphs this -#' argument is ignored. +#' @param mode Character string, \dQuote{out} for out-degree, \dQuote{in} for in-degree or \dQuote{all} for the sum of the two. +#' For undirected graphs this argument is ignored. #' @inheritParams degree -#' @param weights Weight vector. If the graph has a `weight` edge -#' attribute, then this is used by default. If the graph does not have a -#' `weight` edge attribute and this argument is `NULL`, then a -#' [degree()] is called. If this is `NA`, then no edge weights are used -#' (even if the graph has a `weight` edge attribute). +#' @param weights Weight vector. +#' If the graph has a `weight` edge attribute, then this is used by default. +#' If the graph does not have a `weight` edge attribute and this argument is `NULL`, then a [degree()] is called. +#' If this is `NA`, then no edge weights are used (even if the graph has a `weight` edge attribute). #' @return A numeric vector giving the strength of the vertices. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @seealso [degree()] for the unweighted version. @@ -1610,24 +1545,23 @@ strength <- function( #' #' Calculates a measure of diversity for all vertices. #' -#' The diversity of a vertex is defined as the (scaled) Shannon entropy of the -#' weights of its incident edges: +#' The diversity of a vertex is defined as the (scaled) Shannon entropy of the weights of its incident edges: #' \deqn{D(i)=\frac{H(i)}{\log k_i}}{D(i)=H(i)/log(k[i])} #' and #' \deqn{H(i)=-\sum_{j=1}^{k_i} p_{ij}\log p_{ij},}{H(i) = #' -sum(p[i,j] log(p[i,j]), j=1..k[i]),} where #' \deqn{p_{ij}=\frac{w_{ij}}{\sum_{l=1}^{k_i}}V_{il},}{p[i,j] = w[i,j] / #' sum(w[i,l], l=1..k[i]),} and \eqn{k_i}{k[i]} is the (total) degree of vertex -#' \eqn{i}, \eqn{w_{ij}}{w[i,j]} is the weight of the edge(s) between vertices -#' \eqn{i} and \eqn{j}. +#' \eqn{i}, \eqn{w_{ij}}{w[i,j]} is the weight of the edge(s) between vertices \eqn{i} and \eqn{j}. #' #' For vertices with degree less than two the function returns `NaN`. #' -#' @param graph The input graph. Edge directions are ignored. +#' @param graph The input graph. +#' Edge directions are ignored. #' @inheritParams rlang::args_dots_empty -#' @param weights `NULL`, or the vector of edge weights to use for the -#' computation. If `NULL`, then the \sQuote{weight} attibute is used. Note -#' that this measure is not defined for unweighted graphs. +#' @param weights `NULL`, or the vector of edge weights to use for the computation. +#' If `NULL`, then the \sQuote{weight} attibute is used. +#' Note that this measure is not defined for unweighted graphs. #' @param vids The vertex IDs for which to calculate the measure. #' The default `NULL` selects all vertices. #' @return A numeric vector, its length is the number of vertices. @@ -1705,28 +1639,25 @@ diversity <- function( #' Kleinberg's hub and authority centrality scores. #' -#' The hub scores of the vertices are defined as the principal eigenvector -#' of \eqn{A A^T}{A*t(A)}, where \eqn{A} is the adjacency matrix of the -#' graph. +#' The hub scores of the vertices are defined as the principal eigenvector of \eqn{A A^T}{A*t(A)}, +#' where \eqn{A} is the adjacency matrix of the graph. #' -#' Similarly, the authority scores of the vertices are defined as the principal -#' eigenvector of \eqn{A^T A}{t(A)*A}, where \eqn{A} is the adjacency matrix of -#' the graph. +#' Similarly, the authority scores of the vertices are defined as the principal eigenvector of \eqn{A^T A}{t(A)*A}, +#' where \eqn{A} is the adjacency matrix of the graph. #' -#' For undirected matrices the adjacency matrix is symmetric and the hub -#' scores are the same as authority scores. +#' For undirected matrices the adjacency matrix is symmetric and the hub scores are the same as authority scores. #' #' @param graph The input graph. -#' @param scale Logical, whether to scale the result to have a maximum -#' score of one. If no scaling is used then the result vector has unit length -#' in the Euclidean norm. -#' @param weights Optional positive weight vector for calculating weighted -#' scores. If the graph has a `weight` edge attribute, then this is used -#' by default. Pass `NA` to ignore the weight attribute. This function -#' interprets edge weights as connection strengths. The weights of parallel -#' edges are effectively added up. -#' @param options A named list, to override some ARPACK options. See -#' [arpack()] for details. The default `NULL` uses [arpack_defaults()]. +#' @param scale Logical, whether to scale the result to have a maximum score of one. +#' If no scaling is used then the result vector has unit length in the Euclidean norm. +#' @param weights Optional positive weight vector for calculating weighted scores. +#' If the graph has a `weight` edge attribute, then this is used by default. +#' Pass `NA` to ignore the weight attribute. +#' This function interprets edge weights as connection strengths. +#' The weights of parallel edges are effectively added up. +#' @param options A named list, to override some ARPACK options. +#' See [arpack()] for details. +#' The default `NULL` uses [arpack_defaults()]. #' @inheritParams rlang::args_dots_empty #' @return A named list with members: #' \describe{ @@ -1743,9 +1674,8 @@ diversity <- function( #' Some information about the ARPACK computation, it has the same members as the `options` member returned by [arpack()], see that for documentation. #' } #' } -#' @seealso [eigen_centrality()] for eigenvector centrality, -#' [page_rank()] for the Page Rank scores. [arpack()] for -#' the underlining machinery of the computation. +#' @seealso [eigen_centrality()] for eigenvector centrality, [page_rank()] for the Page Rank scores. +#' [arpack()] for the underlining machinery of the computation. #' @references J. Kleinberg. Authoritative sources in a hyperlinked #' environment. *Proc. 9th ACM-SIAM Symposium on Discrete Algorithms*, #' 1998. Extended version in *Journal of the ACM* 46(1999). Also appears @@ -1784,8 +1714,8 @@ hits_scores <- function( #' @title Kleinberg's authority centrality scores. #' @rdname hub_score -#' @param options A named list, to override some ARPACK options. See -#' [arpack()] for details. +#' @param options A named list, to override some ARPACK options. +#' See [arpack()] for details. #' @export authority_score <- function( graph, @@ -1819,17 +1749,14 @@ authority_score <- function( #' @title Kleinberg's hub centrality scores. #' @rdname hub_score #' @param graph The input graph. -#' @param scale Logical, whether to scale the result to have a maximum -#' score of one. If no scaling is used then the result vector has unit length -#' in the Euclidean norm. -#' @param weights Optional positive weight vector for calculating weighted -#' scores. If the graph has a `weight` edge attribute, then this is used -#' by default. -#' This function interprets edge weights as connection strengths. In the -#' random surfer model, an edge with a larger weight is more likely to be -#' selected by the surfer. -#' @param options A named list, to override some ARPACK options. See -#' [arpack()] for details. +#' @param scale Logical, whether to scale the result to have a maximum score of one. +#' If no scaling is used then the result vector has unit length in the Euclidean norm. +#' @param weights Optional positive weight vector for calculating weighted scores. +#' If the graph has a `weight` edge attribute, then this is used by default. +#' This function interprets edge weights as connection strengths. +#' In the random surfer model, an edge with a larger weight is more likely to be selected by the surfer. +#' @param options A named list, to override some ARPACK options. +#' See [arpack()] for details. #' @family centrality #' @export hub_score <- function( @@ -1865,55 +1792,46 @@ hub_score <- function( #' #' Calculates the Google PageRank for the specified vertices. #' -#' For the explanation of the PageRank algorithm, see the following webpage: -#' , or the following -#' reference: +#' For the explanation of the PageRank algorithm, see the following webpage: , +#' or the following reference: #' -#' Sergey Brin and Larry Page: The Anatomy of a Large-Scale Hypertextual Web -#' Search Engine. Proceedings of the 7th World-Wide Web Conference, Brisbane, -#' Australia, April 1998. +#' Sergey Brin and Larry Page: The Anatomy of a Large-Scale Hypertextual Web Search Engine. +#' Proceedings of the 7th World-Wide Web Conference, Brisbane, Australia, April 1998. #' -#' The `page_rank()` function can use either the PRPACK library or ARPACK -#' (see [arpack()]) to perform the calculation. +#' The `page_rank()` function can use either the PRPACK library or ARPACK (see [arpack()]) to perform the calculation. #' -#' Please note that the PageRank of a given vertex depends on the PageRank of -#' all other vertices, so even if you want to calculate the PageRank for only -#' some of the vertices, all of them must be calculated. Requesting the -#' PageRank for only some of the vertices does not result in any performance -#' increase at all. +#' Please note that the PageRank of a given vertex depends on the PageRank of all other vertices, +#' so even if you want to calculate the PageRank for only some of the vertices, all of them must be calculated. +#' Requesting the PageRank for only some of the vertices does not result in any performance increase at all. #' #' @param graph The graph object. #' @inheritParams rlang::args_dots_empty -#' @param algo Character scalar, which implementation to use to carry out the -#' calculation. The default is `"prpack"`, which uses the PRPACK library -#' () to calculate PageRank scores -#' by solving a set of linear equations. This is a new implementation in igraph -#' version 0.7, and the suggested one, as it is the most stable and the fastest -#' for all but small graphs. `"arpack"` uses the ARPACK library, the -#' default implementation from igraph version 0.5 until version 0.7. It computes -#' PageRank scores by solving an eingevalue problem. +#' @param algo Character scalar, which implementation to use to carry out the calculation. +#' The default is `"prpack"`, +#' which uses the PRPACK library () to calculate PageRank scores by solving a set of linear equations. +#' This is a new implementation in igraph version 0.7, and the suggested one, +#' as it is the most stable and the fastest for all but small graphs. +#' `"arpack"` uses the ARPACK library, +#' the default implementation from igraph version 0.5 until version 0.7. It computes PageRank scores by solving an eingevalue problem. #' @param vids The vertices of interest. #' The default `NULL` selects all vertices. -#' @param directed Logical, if true directed paths will be considered for -#' directed graphs. It is ignored for undirected graphs. +#' @param directed Logical, if true directed paths will be considered for directed graphs. +#' It is ignored for undirected graphs. #' @param damping The damping factor (\sQuote{d} in the original paper). -#' @param personalized Optional vector giving a probability distribution to -#' calculate personalized PageRank. For personalized PageRank, the probability -#' of jumping to a node when abandoning the random walk is not uniform, but it -#' is given by this vector. The vector should contains an entry for each vertex -#' and it will be rescaled to sum up to one. -#' @param weights A numerical vector or `NULL`. This argument can be used -#' to give edge weights for calculating the weighted PageRank of vertices. If -#' this is `NULL` and the graph has a `weight` edge attribute then -#' that is used. If `weights` is a numerical vector then it used, even if -#' the graph has a `weights` edge attribute. If this is `NA`, then no -#' edge weights are used (even if the graph has a `weight` edge attribute. -#' This function interprets edge weights as connection strengths. In the -#' random surfer model, an edge with a larger weight is more likely to be -#' selected by the surfer. -#' @param options A named list, to override some ARPACK options. See -#' [arpack()] for details. This argument is ignored if the PRPACK -#' implementation is used. +#' @param personalized Optional vector giving a probability distribution to calculate personalized PageRank. +#' For personalized PageRank, the probability of jumping to a node when abandoning the random walk is not uniform, +#' but it is given by this vector. +#' The vector should contains an entry for each vertex and it will be rescaled to sum up to one. +#' @param weights A numerical vector or `NULL`. +#' This argument can be used to give edge weights for calculating the weighted PageRank of vertices. +#' If this is `NULL` and the graph has a `weight` edge attribute then that is used. +#' If `weights` is a numerical vector then it used, even if the graph has a `weights` edge attribute. +#' If this is `NA`, then no edge weights are used (even if the graph has a `weight` edge attribute. +#' This function interprets edge weights as connection strengths. +#' In the random surfer model, an edge with a larger weight is more likely to be selected by the surfer. +#' @param options A named list, to override some ARPACK options. +#' See [arpack()] for details. +#' This argument is ignored if the PRPACK implementation is used. #' @return A named list with entries: #' \describe{ #' \item{vector}{ @@ -2028,36 +1946,31 @@ page_rank <- function( #' Harmonic centrality of vertices #' -#' The harmonic centrality of a vertex is the mean inverse distance to all other -#' vertices. The inverse distance to an unreachable vertex is considered to be zero. +#' The harmonic centrality of a vertex is the mean inverse distance to all other vertices. +#' The inverse distance to an unreachable vertex is considered to be zero. #' -#' The `cutoff` argument can be used to restrict the calculation to paths -#' of length `cutoff` or smaller only; this can be used for larger graphs -#' to speed up the calculation. If `cutoff` is negative (which is the -#' default), then the function calculates the exact harmonic centrality scores. +#' The `cutoff` argument can be used to restrict the calculation to paths of length `cutoff` or smaller only; +#' this can be used for larger graphs to speed up the calculation. +#' If `cutoff` is negative (which is the default), then the function calculates the exact harmonic centrality scores. #' #' @param graph The graph to analyze. #' @param vids The vertices for which harmonic centrality will be calculated. #' The default `NULL` selects all vertices. #' @inheritParams rlang::args_dots_empty -#' @param mode Character string, defining the types of the paths used for -#' measuring the distance in directed graphs. \dQuote{out} follows paths along -#' the edge directions only, \dQuote{in} traverses the edges in reverse, while -#' \dQuote{all} ignores edge directions. This argument is ignored for undirected -#' graphs. -#' @param normalized Logical, whether to calculate the normalized -#' harmonic centrality. If true, the result is the mean inverse path length to -#' other vertices, i.e. it is normalized by the number of vertices minus one. +#' @param mode Character string, defining the types of the paths used for measuring the distance in directed graphs. +#' \dQuote{out} follows paths along the edge directions only, \dQuote{in} traverses the edges in reverse, +#' while \dQuote{all} ignores edge directions. +#' This argument is ignored for undirected graphs. +#' @param normalized Logical, whether to calculate the normalized harmonic centrality. +#' If true, the result is the mean inverse path length to other vertices, i.e. it is normalized by the number of vertices minus one. #' If false, the result is the sum of inverse path lengths to other vertices. -#' @param weights Optional positive weight vector for calculating weighted -#' harmonic centrality. If the graph has a `weight` edge attribute, then -#' this is used by default. Weights are used for calculating weighted shortest -#' paths, so they are interpreted as distances. -#' @param cutoff The maximum path length to consider when calculating the -#' harmonic centrality. There is no such limit when the cutoff is negative. Note that -#' zero cutoff means that only paths of at most length 0 are considered. -#' @return Numeric vector with the harmonic centrality scores of all the vertices in -#' `v`. +#' @param weights Optional positive weight vector for calculating weighted harmonic centrality. +#' If the graph has a `weight` edge attribute, then this is used by default. +#' Weights are used for calculating weighted shortest paths, so they are interpreted as distances. +#' @param cutoff The maximum path length to consider when calculating the harmonic centrality. +#' There is no such limit when the cutoff is negative. +#' Note that zero cutoff means that only paths of at most length 0 are considered. +#' @return Numeric vector with the harmonic centrality scores of all the vertices in `v`. #' @seealso [betweenness()], [closeness()] #' @references M. Marchiori and V. Latora, Harmony in the small-world, #' *Physica A* 285, pp. 539-546 (2000). @@ -2204,79 +2117,69 @@ bonpow.sparse <- function( #' Find Bonacich Power Centrality Scores of Network Positions #' -#' `power_centrality()` takes a graph (`dat`) and returns the Boncich power -#' centralities of positions (selected by `nodes`). The decay rate for -#' power contributions is specified by `exponent` (1 by default). +#' `power_centrality()` takes a graph (`dat`) and returns the Boncich power centralities of positions (selected by `nodes`). +#' The decay rate for power contributions is specified by `exponent` (1 by default). #' -#' Bonacich's power centrality measure is defined by -#' \eqn{C_{BP}\left(\alpha,\beta\right)=\alpha\left(\mathbf{I}-\beta\mathbf{A}\right)^{-1}\mathbf{A}\mathbf{1}}{C_BP(alpha,beta)=alpha +#' Bonacich's power centrality measure is defined by \eqn{C_{BP}\left(\alpha,\beta\right)=\alpha\left(\mathbf{I}-\beta\mathbf{A}\right)^{-1}\mathbf{A}\mathbf{1}}{C_BP(alpha,beta)=alpha #' (I-beta A)^-1 A 1}, where \eqn{\beta}{beta} is an attenuation parameter (set -#' here by `exponent`) and \eqn{\mathbf{A}}{A} is the graph adjacency -#' matrix. (The coefficient \eqn{\alpha}{alpha} acts as a scaling parameter, -#' and is set here (following Bonacich (1987)) such that the sum of squared -#' scores is equal to the number of vertices. This allows 1 to be used as a -#' reference value for the ``middle'' of the centrality range.) When -#' \eqn{\beta \rightarrow }{beta->1/lambda_A1}\eqn{ +#' here by `exponent`) and \eqn{\mathbf{A}}{A} is the graph adjacency matrix. +#' (The coefficient \eqn{\alpha}{alpha} acts as a scaling parameter, +#' and is set here (following Bonacich (1987)) such that the sum of squared scores is equal to the number of vertices. +#' This allows 1 to be used as a reference value for the ``middle'' of the centrality range.) +#' When \eqn{\beta \rightarrow }{beta->1/lambda_A1}\eqn{ #' 1/\lambda_{\mathbf{A}1}}{beta->1/lambda_A1} (the reciprocal of the largest -#' eigenvalue of \eqn{\mathbf{A}}{A}), this is to within a constant multiple of -#' the familiar eigenvector centrality score; for other values of \eqn{\beta}, -#' the behavior of the measure is quite different. In particular, \eqn{\beta} -#' gives positive and negative weight to even and odd walks, respectively, as -#' can be seen from the series expansion -#' \eqn{C_{BP}\left(\alpha,\beta\right)=\alpha \sum_{k=0}^\infty \beta^k +#' eigenvalue of \eqn{\mathbf{A}}{A}), this is to within a constant multiple of the familiar eigenvector centrality score; +#' for other values of \eqn{\beta}, the behavior of the measure is quite different. +#' In particular, +#' \eqn{\beta} gives positive and negative weight to even and odd walks, respectively, +#' as can be seen from the series expansion \eqn{C_{BP}\left(\alpha,\beta\right)=\alpha \sum_{k=0}^\infty \beta^k #' }{C_BP(alpha,beta) = alpha sum( beta^k A^(k+1) 1, k in 0..infinity )}\eqn{ #' \mathbf{A}^{k+1} \mathbf{1}}{C_BP(alpha,beta) = alpha sum( beta^k A^(k+1) 1, #' k in 0..infinity )} which converges so long as \eqn{|\beta| #' }{|beta|<1/lambda_A1}\eqn{ < 1/\lambda_{\mathbf{A}1}}{|beta|<1/lambda_A1}. -#' The magnitude of \eqn{\beta}{beta} controls the influence of distant actors -#' on ego's centrality score, with larger magnitudes indicating slower rates of -#' decay. (High rates, hence, imply a greater sensitivity to edge effects.) -#' -#' Interpretively, the Bonacich power measure corresponds to the notion that -#' the power of a vertex is recursively defined by the sum of the power of its -#' alters. The nature of the recursion involved is then controlled by the -#' power exponent: positive values imply that vertices become more powerful as -#' their alters become more powerful (as occurs in cooperative relations), -#' while negative values imply that vertices become more powerful only as their -#' alters become *weaker* (as occurs in competitive or antagonistic -#' relations). The magnitude of the exponent indicates the tendency of the -#' effect to decay across long walks; higher magnitudes imply slower decay. -#' One interesting feature of this measure is its relative instability to -#' changes in exponent magnitude (particularly in the negative case). If your -#' theory motivates use of this measure, you should be very careful to choose a -#' decay parameter on a non-ad hoc basis. -#' -#' For directed networks, the Bonacich power measure can be understood as -#' similar to status in the network where higher status nodes have more edges -#' that point from them to others with status. Node A's centrality depends -#' on the centrality of all the nodes that A points toward, and their centrality -#' depends on the nodes they point toward, etc. Note, this means that a node -#' with an out-degree of 0 will have a Bonacich power centrality of 0 as they -#' do not point towards anyone. When using this with directed network it -#' is important to think about the edge direction and what it represents. +#' The magnitude of \eqn{\beta}{beta} controls the influence of distant actors on ego's centrality score, +#' with larger magnitudes indicating slower rates of decay. +#' (High rates, hence, imply a greater sensitivity to edge effects.) +#' +#' Interpretively, the Bonacich power measure corresponds to the notion +#' that the power of a vertex is recursively defined by the sum of the power of its alters. +#' The nature of the recursion involved is then controlled by the power exponent: +#' positive values imply that vertices become more powerful as their alters become more powerful (as occurs in cooperative relations), +#' while negative values imply that vertices become more powerful only +#' as their alters become *weaker* (as occurs in competitive or antagonistic relations). +#' The magnitude of the exponent indicates the tendency of the effect to decay across long walks; +#' higher magnitudes imply slower decay. +#' One interesting feature of this measure is its relative instability to changes in exponent magnitude (particularly in the negative case). +#' If your theory motivates use of this measure, +#' you should be very careful to choose a decay parameter on a non-ad hoc basis. +#' +#' For directed networks, +#' the Bonacich power measure can be understood as similar to status in the network +#' where higher status nodes have more edges that point from them to others with status. +#' Node A's centrality depends on the centrality of all the nodes that A points toward, +#' and their centrality depends on the nodes they point toward, etc. Note, +#' this means that a node with an out-degree of 0 will have a Bonacich power centrality of 0 as they do not point towards anyone. +#' When using this with directed network it is important to think about the edge direction and what it represents. #' #' @param graph the input graph. -#' @param nodes vertex sequence indicating which vertices are to be included in -#' the calculation. The default `NULL` selects all vertices. +#' @param nodes vertex sequence indicating which vertices are to be included in the calculation. +#' The default `NULL` selects all vertices. #' @inheritParams rlang::args_dots_empty -#' @param loops Logical indicating whether or not the diagonal should be -#' treated as valid data. Set this true if and only if the data can contain -#' loops. `loops` is `FALSE` by default. -#' @param exponent exponent (decay rate) for the Bonacich power centrality -#' score; can be negative -#' @param rescale if true, centrality scores are rescaled such that they sum to -#' 1. -#' @param tol tolerance for near-singularities during matrix inversion (see -#' [Matrix::solve()]) -#' @param sparse Logical, whether to use sparse matrices for the -#' calculation. The \sQuote{Matrix} package is required for sparse matrix -#' support +#' @param loops Logical indicating whether or not the diagonal should be treated as valid data. +#' Set this true if and only +#' if the data can contain loops. +#' `loops` is `FALSE` by default. +#' @param exponent exponent (decay rate) for the Bonacich power centrality score; can be negative +#' @param rescale if true, centrality scores are rescaled such that they sum to 1. +#' @param tol tolerance for near-singularities during matrix inversion (see [Matrix::solve()]) +#' @param sparse Logical, whether to use sparse matrices for the calculation. +#' The \sQuote{Matrix} package is required for sparse matrix support #' @inheritParams as_adjacency_matrix #' @return A vector, containing the centrality scores. #' @note This function was ported (i.e. copied) from the SNA package. #' @section Warning : Singular adjacency matrices cause no end of headaches for -#' this algorithm; thus, the routine may fail in certain cases. This will be -#' fixed when we get a better algorithm. +#' this algorithm; thus, the routine may fail in certain cases. +#' This will be fixed when we get a better algorithm. #' @author Carter T. Butts #' (), ported to #' igraph by Gabor Csardi \email{csardi.gabor@@gmail.com} @@ -2473,43 +2376,33 @@ alpha.centrality.sparse <- function( #' Find Bonacich alpha centrality scores of network positions #' -#' `alpha_centrality()` calculates the alpha centrality of some (or all) -#' vertices in a graph. +#' `alpha_centrality()` calculates the alpha centrality of some (or all) vertices in a graph. #' -#' The alpha centrality measure can be considered as a generalization of -#' eigenvector centrality to directed graphs. It was proposed by Bonacich in -#' 2001 (see reference below). +#' The alpha centrality measure can be considered as a generalization of eigenvector centrality to directed graphs. +#' It was proposed by Bonacich in 2001 (see reference below). #' #' The alpha centrality of the vertices in a graph is defined as the solution #' of the following matrix equation: \deqn{x=\alpha A^T x+e,}{x=alpha t(A)x+e,} -#' where \eqn{A}{A} is the (not necessarily symmetric) adjacency matrix of the -#' graph, \eqn{e}{e} is the vector of exogenous sources of status of the -#' vertices and \eqn{\alpha}{alpha} is the relative importance of the -#' endogenous versus exogenous factors. -#' -#' @param graph The input graph, can be directed or undirected. In undirected -#' graphs, edges are treated as if they were reciprocal directed ones. -#' @param nodes Vertex sequence, the vertices for which the alpha centrality -#' values are returned. The default `NULL` selects all vertices. +#' where \eqn{A}{A} is the (not necessarily symmetric) adjacency matrix of the graph, +#' \eqn{e}{e} is the vector of exogenous sources of status of the vertices and \eqn{\alpha}{alpha} is the relative importance of the endogenous versus exogenous factors. +#' +#' @param graph The input graph, can be directed or undirected. +#' In undirected graphs, edges are treated as if they were reciprocal directed ones. +#' @param nodes Vertex sequence, the vertices for which the alpha centrality values are returned. +#' The default `NULL` selects all vertices. #' (For technical reasons they will be calculated for all vertices, anyway.) #' @inheritParams rlang::args_dots_empty -#' @param alpha Parameter specifying the relative importance of endogenous -#' versus exogenous factors in the determination of centrality. See details -#' below. -#' @param loops Whether to eliminate loop edges from the graph before the -#' calculation. -#' @param exo The exogenous factors, in most cases this is either a constant -- -#' the same factor for every node, or a vector giving the factor for every -#' vertex. Note that too long vectors will be truncated and too short vectors -#' will be replicated to match the number of vertices. +#' @param alpha Parameter specifying the relative importance of endogenous versus exogenous factors in the determination of centrality. +#' See details below. +#' @param loops Whether to eliminate loop edges from the graph before the calculation. +#' @param exo The exogenous factors, in most cases this is either a constant -- the same factor for every node, +#' or a vector giving the factor for every vertex. +#' Note that too long vectors will be truncated and too short vectors will be replicated to match the number of vertices. #' @inheritParams as_adjacency_matrix -#' @param tol Tolerance for near-singularities during matrix inversion, see -#' [Matrix::solve()]. -#' @param sparse Logical, whether to use sparse matrices for the -#' calculation. The \sQuote{Matrix} package is required for sparse matrix -#' support -#' @return A numeric vector contaning the centrality scores for the selected -#' vertices. +#' @param tol Tolerance for near-singularities during matrix inversion, see [Matrix::solve()]. +#' @param sparse Logical, whether to use sparse matrices for the calculation. +#' The \sQuote{Matrix} package is required for sparse matrix support +#' @return A numeric vector contaning the centrality scores for the selected vertices. #' @section Warning: Singular adjacency matrices cause problems for this #' algorithm, the routine may fail is certain cases. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} diff --git a/R/centralization.R b/R/centralization.R index 5d9a3cd52c5..c93aba2ccfc 100644 --- a/R/centralization.R +++ b/R/centralization.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `centralize.scores()` was renamed to [centralize()] to create a more -#' consistent API. +#' `centralize.scores()` was renamed to [centralize()] to create a more consistent API. #' @inheritParams centralize #' @keywords internal #' @export @@ -23,8 +22,7 @@ centralize.scores <- function(scores, theoretical.max = 0, normalized = TRUE) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `centralization.evcent.tmax()` was renamed to [centr_eigen_tmax()] to create a more -#' consistent API. +#' `centralization.evcent.tmax()` was renamed to [centr_eigen_tmax()] to create a more consistent API. #' @inheritParams centr_eigen_tmax #' @keywords internal #' @export @@ -53,8 +51,7 @@ centralization.evcent.tmax <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `centralization.evcent()` was renamed to [centr_eigen()] to create a more -#' consistent API. +#' `centralization.evcent()` was renamed to [centr_eigen()] to create a more consistent API. #' @inheritParams centr_eigen #' @keywords internal #' @export @@ -81,8 +78,7 @@ centralization.evcent <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `centralization.degree.tmax()` was renamed to [centr_degree_tmax()] to create a more -#' consistent API. +#' `centralization.degree.tmax()` was renamed to [centr_degree_tmax()] to create a more consistent API. #' @inheritParams centr_degree_tmax #' @keywords internal #' @export @@ -106,8 +102,7 @@ centralization.degree.tmax <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `centralization.degree()` was renamed to [centr_degree()] to create a more -#' consistent API. +#' `centralization.degree()` was renamed to [centr_degree()] to create a more consistent API. #' @inheritParams centr_degree #' @keywords internal #' @export @@ -136,8 +131,7 @@ centralization.degree <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `centralization.closeness.tmax()` was renamed to [centr_clo_tmax()] to create a more -#' consistent API. +#' `centralization.closeness.tmax()` was renamed to [centr_clo_tmax()] to create a more consistent API. #' @inheritParams centr_clo_tmax #' @keywords internal #' @export @@ -160,8 +154,7 @@ centralization.closeness.tmax <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `centralization.closeness()` was renamed to [centr_clo()] to create a more -#' consistent API. +#' `centralization.closeness()` was renamed to [centr_clo()] to create a more consistent API. #' @inheritParams centr_clo #' @keywords internal #' @export @@ -184,8 +177,7 @@ centralization.closeness <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `centralization.betweenness.tmax()` was renamed to [centr_betw_tmax()] to create a more -#' consistent API. +#' `centralization.betweenness.tmax()` was renamed to [centr_betw_tmax()] to create a more consistent API. #' @inheritParams centr_betw_tmax #' @keywords internal #' @export @@ -208,8 +200,7 @@ centralization.betweenness.tmax <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `centralization.betweenness()` was renamed to [centr_betw()] to create a more -#' consistent API. +#' `centralization.betweenness()` was renamed to [centr_betw()] to create a more consistent API. #' @inheritParams centr_betw #' @keywords internal #' @export @@ -254,39 +245,31 @@ 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 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 +#' 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. +#' 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 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). +#' 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. +#' `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. +#' @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 @@ -371,12 +354,10 @@ centralize <- function( #' #' @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. +#' @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}{ @@ -463,13 +444,15 @@ centr_degree <- function( #' #' 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. +#' @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. +#' @return Real scalar, +#' the theoretical maximum (unnormalized) graph degree centrality score for graphs with given order and other parameters. #' #' @family centralization related #' @@ -520,8 +503,7 @@ centr_degree_tmax <- function( #' #' @param graph The input graph. #' @inheritParams rlang::args_dots_empty -#' @param directed Logical, whether to use directed shortest paths for -#' calculating betweenness. +#' @param directed Logical, whether to use directed shortest paths for calculating betweenness. #' @inheritParams centr_degree #' @return A named list with the following components: #' \describe{ @@ -614,17 +596,15 @@ centr_betw <- function( #' #' 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. +#' @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. +#' @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 #' @@ -690,8 +670,7 @@ centr_betw_tmax <- function( #' #' @param graph The input graph. #' @inheritParams rlang::args_dots_empty -#' @param mode This is the same as the `mode` argument of -#' `closeness()`. +#' @param mode This is the same as the `mode` argument of `closeness()`. #' @inheritParams centr_degree #' @return A named list with the following components: #' \describe{ @@ -775,16 +754,15 @@ centr_clo <- function( #' #' 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 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. +#' @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 #' @@ -849,12 +827,10 @@ centr_clo_tmax <- function( #' 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. +#' @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{ @@ -922,17 +898,16 @@ centr_eigen <- function( #' #' 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. +#' @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 #' diff --git a/R/cliques.R b/R/cliques.R index 5befee23761..69b7a5d6661 100644 --- a/R/cliques.R +++ b/R/cliques.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `maximal.independent.vertex.sets()` was renamed to [max_ivs()] to create a more -#' consistent API. +#' `maximal.independent.vertex.sets()` was renamed to [max_ivs()] to create a more consistent API. #' @inheritParams max_ivs #' @keywords internal #' @export @@ -23,8 +22,7 @@ maximal.independent.vertex.sets <- function(graph) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `maximal.cliques.count()` was renamed to [count_max_cliques()] to create a more -#' consistent API. +#' `maximal.cliques.count()` was renamed to [count_max_cliques()] to create a more consistent API. #' @inheritParams count_max_cliques #' @keywords internal #' @export @@ -48,8 +46,7 @@ maximal.cliques.count <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `maximal.cliques()` was renamed to [max_cliques()] to create a more -#' consistent API. +#' `maximal.cliques()` was renamed to [max_cliques()] to create a more consistent API. #' @inheritParams max_cliques #' @keywords internal #' @export @@ -70,8 +67,7 @@ maximal.cliques <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `largest.independent.vertex.sets()` was renamed to [largest_ivs()] to create a more -#' consistent API. +#' `largest.independent.vertex.sets()` was renamed to [largest_ivs()] to create a more consistent API. #' @inheritParams largest_ivs #' @keywords internal #' @export @@ -90,8 +86,7 @@ largest.independent.vertex.sets <- function(graph) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `largest.cliques()` was renamed to [largest_cliques()] to create a more -#' consistent API. +#' `largest.cliques()` was renamed to [largest_cliques()] to create a more consistent API. #' @inheritParams largest_cliques #' @keywords internal #' @export @@ -106,8 +101,7 @@ largest.cliques <- function(graph) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `independent.vertex.sets()` was renamed to [ivs()] to create a more -#' consistent API. +#' `independent.vertex.sets()` was renamed to [ivs()] to create a more consistent API. #' @inheritParams ivs #' @keywords internal #' @export @@ -122,8 +116,7 @@ independent.vertex.sets <- function(graph, min = NULL, max = NULL) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `independence.number()` was renamed to [ivs_size()] to create a more -#' consistent API. +#' `independence.number()` was renamed to [ivs_size()] to create a more consistent API. #' @inheritParams ivs_size #' @keywords internal #' @export @@ -138,8 +131,7 @@ independence.number <- function(graph) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `clique.number()` was renamed to [clique_num()] to create a more -#' consistent API. +#' `clique.number()` was renamed to [clique_num()] to create a more consistent API. #' @inheritParams clique_num #' @keywords internal #' @export @@ -171,66 +163,57 @@ clique.number <- function(graph) { #' Functions to find cliques, i.e. complete subgraphs in a graph #' -#' These functions find all, the largest or all the maximal cliques in an -#' undirected graph. The size of the largest clique can also be calculated. +#' These functions find all, the largest or all the maximal cliques in an undirected graph. +#' The size of the largest clique can also be calculated. #' -#' `cliques()` find all complete subgraphs in the input graph, obeying the -#' size limitations given in the `min` and `max` arguments. +#' `cliques()` find all complete subgraphs in the input graph, obeying the size limitations given in the `min` and `max` arguments. #' -#' `largest_cliques()` finds all largest cliques in the input graph. A -#' clique is largest if there is no other clique including more vertices. +#' `largest_cliques()` finds all largest cliques in the input graph. +#' A clique is largest if there is no other clique including more vertices. #' -#' `max_cliques()` finds all maximal cliques in the input graph. A -#' clique is maximal if it cannot be extended to a larger clique. The largest -#' cliques are always maximal, but a maximal clique is not necessarily the -#' largest. +#' `max_cliques()` finds all maximal cliques in the input graph. +#' A clique is maximal if it cannot be extended to a larger clique. +#' The largest cliques are always maximal, but a maximal clique is not necessarily the largest. #' #' `count_max_cliques()` counts the maximal cliques. #' #' `clique_num()` calculates the size of the largest clique(s). #' -#' `clique_size_counts()` returns a numeric vector representing a histogram -#' of clique sizes, between the given minimum and maximum clique size. +#' `clique_size_counts()` returns a numeric vector representing a histogram of clique sizes, +#' between the given minimum and maximum clique size. #' #' `is_clique()` tests whether all pairs within a vertex set are connected. #' #' @inheritParams weighted_cliques -#' @param graph The input graph, directed graphs will be considered as -#' undirected ones, multiple edges and loops are ignored. +#' @param graph The input graph, directed graphs will be considered as undirected ones, multiple edges and loops are ignored. #' @param min Numeric constant, lower limit on the size of the cliques to find. #' `NULL` means no limit, i.e. it is the same as 0. #' @param max Numeric constant, upper limit on the size of the cliques to find. #' `NULL` means no limit. #' @param ... These dots are for future extensions and must be empty. -#' @param callback Optional function to call for each clique found. If provided, -#' the function should accept one argument: `clique` (integer vector of vertex -#' IDs in the clique, 1-based indexing). The function should return `FALSE` to -#' continue the search or `TRUE` to stop it. If `NULL` (the default), all -#' cliques are collected and returned as a list. -#' -#' **Important limitation:** Callback functions must NOT call any igraph -#' functions (including simple queries like `vcount()` or `ecount()`). Doing -#' so will cause R to crash due to reentrancy issues. Extract -#' any needed graph information before calling the function with a callback, or -#' use collector mode (the default) and process results afterward. -#' @return `cliques()` returns a list containing numeric vectors of vertex IDs if -#' `callback` is `NULL`. Each list element is a clique, i.e. a vertex sequence -#' of class [igraph.vs][V]. If `callback` is provided, returns `NULL` invisibly. -#' -#' `largest_cliques()` and `clique_num()` return a list containing numeric -#' vectors of vertex IDs. Each list element is a clique, i.e. a vertex sequence -#' of class [igraph.vs][V]. -#' -#' `max_cliques()` returns `NULL`, invisibly, if its `file` -#' argument is not `NULL`. The output is written to the specified file in -#' this case. -#' -#' `clique_num()` and `count_max_cliques()` return an integer -#' scalar. -#' -#' `clique_size_counts()` returns a numeric vector with the clique sizes such that -#' the i-th item belongs to cliques of size i. Trailing zeros are currently -#' truncated, but this might change in future versions. +#' @param callback Optional function to call for each clique found. +#' If provided, the function should accept one argument: `clique` (integer vector of vertex IDs in the clique, 1-based indexing). +#' The function should return `FALSE` to continue the search or `TRUE` to stop it. +#' If `NULL` (the default), all cliques are collected and returned as a list. +#' +#' **Important limitation:** Callback functions must NOT call any igraph functions (including simple queries like `vcount()` or `ecount()`). +#' Doing so will cause R to crash due to reentrancy issues. +#' Extract any needed graph information before calling the function with a callback, +#' or use collector mode (the default) and process results afterward. +#' @return `cliques()` returns a list containing numeric vectors of vertex IDs if `callback` is `NULL`. +#' Each list element is a clique, i.e. a vertex sequence of class [igraph.vs][V]. +#' If `callback` is provided, returns `NULL` invisibly. +#' +#' `largest_cliques()` and `clique_num()` return a list containing numeric vectors of vertex IDs. +#' Each list element is a clique, i.e. a vertex sequence of class [igraph.vs][V]. +#' +#' `max_cliques()` returns `NULL`, invisibly, if its `file` argument is not `NULL`. +#' The output is written to the specified file in this case. +#' +#' `clique_num()` and `count_max_cliques()` return an integer scalar. +#' +#' `clique_size_counts()` returns a numeric vector with the clique sizes such that the i-th item belongs to cliques of size i. +#' Trailing zeros are currently truncated, but this might change in future versions. #' #' @author Tamas Nepusz \email{ntamas@@gmail.com} and Gabor Csardi #' \email{csardi.gabor@@gmail.com} @@ -286,16 +269,14 @@ largest_cliques <- function(graph) { } #' @rdname cliques -#' @param subset If not `NULL`, then it must be a vector of vertex IDs, -#' numeric or symbolic if the graph is named. The algorithm is run from these -#' vertices only, so only a subset of all maximal cliques is returned. See the -#' Eppstein paper for details. This argument makes it possible to easily -#' parallelize the finding of maximal cliques. -#' @param file If not `NULL`, then it must be a file name, i.e. a -#' character scalar. The output of the algorithm is written to this file. (If -#' it exists, then it will be overwritten.) Each clique will be a separate line -#' in the file, given with the numeric IDs of its vertices, separated by -#' whitespace. +#' @param subset If not `NULL`, then it must be a vector of vertex IDs, numeric or symbolic if the graph is named. +#' The algorithm is run from these vertices only, so only a subset of all maximal cliques is returned. +#' See the Eppstein paper for details. +#' This argument makes it possible to easily parallelize the finding of maximal cliques. +#' @param file If not `NULL`, then it must be a file name, i.e. a character scalar. +#' The output of the algorithm is written to this file. +#' (If it exists, then it will be overwritten.) +#' Each clique will be a separate line in the file, given with the numeric IDs of its vertices, separated by whitespace. #' @export max_cliques <- function( graph, @@ -458,37 +439,30 @@ clique_num <- function(graph) { #' Functions to find weighted cliques, i.e. vertex-weighted complete subgraphs in a graph #' -#' These functions find all, the largest or all the maximal weighted cliques in -#' an undirected graph. The weight of a clique is the sum of the weights of its -#' vertices. +#' These functions find all, the largest or all the maximal weighted cliques in an undirected graph. +#' The weight of a clique is the sum of the weights of its vertices. #' #' `weighted_cliques()` finds all complete subgraphs in the input graph, -#' obeying the weight limitations given in the `min` and `max` -#' arguments. +#' obeying the weight limitations given in the `min` and `max` arguments. #' -#' `largest_weighted_cliques()` finds all largest weighted cliques in the -#' input graph. A clique is largest if there is no other clique whose total -#' weight is larger than the weight of this clique. +#' `largest_weighted_cliques()` finds all largest weighted cliques in the input graph. +#' A clique is largest if there is no other clique whose total weight is larger than the weight of this clique. #' #' `weighted_clique_num()` calculates the weight of the largest weighted clique(s). #' -#' @param graph The input graph, directed graphs will be considered as -#' undirected ones, multiple edges and loops are ignored. +#' @param graph The input graph, directed graphs will be considered as undirected ones, multiple edges and loops are ignored. #' @param min.weight Numeric constant, lower limit on the weight of the cliques to find. #' `NULL` means no limit, i.e. it is the same as 0. #' @param max.weight Numeric constant, upper limit on the weight of the cliques to find. #' `NULL` means no limit. #' @inheritParams rlang::args_dots_empty -#' @param vertex.weights Vertex weight vector. If the graph has a `weight` -#' vertex attribute, then this is used by default. If the graph does not have a -#' `weight` vertex attribute and this argument is `NULL`, then every -#' vertex is assumed to have a weight of 1. Note that the current implementation -#' of the weighted clique finder supports positive integer weights only. -#' @param maximal Specifies whether to look for all weighted cliques (`FALSE`) -#' or only the maximal ones (`TRUE`). -#' @return `weighted_cliques()` and `largest_weighted_cliques()` return a -#' list containing numeric vectors of vertex IDs. Each list element is a weighted -#' clique, i.e. a vertex sequence of class [igraph.vs][V]. +#' @param vertex.weights Vertex weight vector. +#' If the graph has a `weight` vertex attribute, then this is used by default. +#' If the graph does not have a `weight` vertex attribute and this argument is `NULL`, +#' then every vertex is assumed to have a weight of 1. Note that the current implementation of the weighted clique finder supports positive integer weights only. +#' @param maximal Specifies whether to look for all weighted cliques (`FALSE`) or only the maximal ones (`TRUE`). +#' @return `weighted_cliques()` and `largest_weighted_cliques()` return a list containing numeric vectors of vertex IDs. +#' Each list element is a weighted clique, i.e. a vertex sequence of class [igraph.vs][V]. #' #' `weighted_clique_num()` returns an integer scalar. #' @@ -662,43 +636,34 @@ weighted_clique_num <- function( #' Independent vertex sets #' -#' A vertex set is called independent if there no edges between any two -#' vertices in it. These functions find independent vertex sets in undirected -#' graphs +#' A vertex set is called independent if there no edges between any two vertices in it. +#' These functions find independent vertex sets in undirected graphs #' -#' `ivs()` finds all independent vertex sets in the -#' network, obeying the size limitations given in the `min` and `max` -#' arguments. +#' `ivs()` finds all independent vertex sets in the network, obeying the size limitations given in the `min` and `max` arguments. #' -#' `largest_ivs()` finds the largest independent vertex -#' sets in the graph. An independent vertex set is largest if there is no -#' independent vertex set with more vertices. +#' `largest_ivs()` finds the largest independent vertex sets in the graph. +#' An independent vertex set is largest if there is no independent vertex set with more vertices. #' -#' `max_ivs()` finds the maximal independent vertex -#' sets in the graph. An independent vertex set is maximal if it cannot be -#' extended to a larger independent vertex set. The largest independent vertex -#' sets are maximal, but the opposite is not always true. +#' `max_ivs()` finds the maximal independent vertex sets in the graph. +#' An independent vertex set is maximal if it cannot be extended to a larger independent vertex set. +#' The largest independent vertex sets are maximal, but the opposite is not always true. #' -#' `ivs_size()` calculate the size of the largest independent -#' vertex set(s). +#' `ivs_size()` calculate the size of the largest independent vertex set(s). #' #' `independence_number()` is an alias for `ivs_size()`. #' -#' These functions use the algorithm described by Tsukiyama et al., see -#' reference below. +#' These functions use the algorithm described by Tsukiyama et al., see reference below. #' #' `is_ivs()` tests if no pairs within a vertex set are connected. #' #' @param graph The input graph, directed graphs are considered as undirected, #' loop edges and multiple edges are ignored. -#' @param min Numeric constant, limit for the minimum size of the independent -#' vertex sets to find. `NULL` means no limit. -#' @param max Numeric constant, limit for the maximum size of the independent -#' vertex sets to find. `NULL` means no limit. -#' @return `ivs()`, -#' `largest_ivs()` and -#' `max_ivs()` return a list containing numeric -#' vertex IDs, each list element is an independent vertex set. +#' @param min Numeric constant, limit for the minimum size of the independent vertex sets to find. +#' `NULL` means no limit. +#' @param max Numeric constant, limit for the maximum size of the independent vertex sets to find. +#' `NULL` means no limit. +#' @return `ivs()`, `largest_ivs()` and `max_ivs()` return a list containing numeric vertex IDs, +#' each list element is an independent vertex set. #' #' `ivs_size()` returns an integer constant. #' @author Tamas Nepusz \email{ntamas@@gmail.com} ported it from the Very Nauty @@ -773,8 +738,7 @@ max_ivs <- function(graph) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `maximal_ivs()` was renamed to [max_ivs()] to create a more -#' consistent API. +#' `maximal_ivs()` was renamed to [max_ivs()] to create a more consistent API. #' @export #' @inheritParams max_ivs #' @keywords internal @@ -862,9 +826,8 @@ clique_size_counts <- function( #' Is this a complete graph? #' -#' A graph is considered complete if there is an edge between all distinct -#' directed pairs of vertices. igraph considers both the singleton graph -#' and the null graph complete. +#' A graph is considered complete +#' if there is an edge between all distinct directed pairs of vertices. igraph considers both the singleton graph and the null graph complete. #' #' @param graph The input graph. #' @return True if the graph is complete. @@ -889,14 +852,13 @@ is_complete <- function(graph) { #' @rdname cliques #' #' @description -#' Tests if all pairs within a set of vertices are adjacent, i.e. whether they -#' form a clique. An empty set and singleton set are considered to be a clique. +#' Tests if all pairs within a set of vertices are adjacent, i.e. whether they form a clique. +#' An empty set and singleton set are considered to be a clique. #' #' @param graph The input graph. #' @param candidate The vertex set to test for being a clique. #' @param directed Whether to consider edge directions. -#' @return `is_clique()` returns `TRUE` if the candidate vertex set forms -#' a clique. +#' @return `is_clique()` returns `TRUE` if the candidate vertex set forms a clique. #' @keywords graphs #' @export is_clique <- function( @@ -951,8 +913,7 @@ is_clique <- function( #' #' @param graph The input graph. #' @param candidate The vertex set to test for being an independent set. -#' @return `is_ivs()` returns `TRUE` if the candidate vertex set forms an -#' independent set. +#' @return `is_ivs()` returns `TRUE` if the candidate vertex set forms an independent set. #' @keywords graphs #' @export is_ivs <- function(graph, candidate) { diff --git a/R/cocitation.R b/R/cocitation.R index f5c67ab2774..1b4e0f3ab99 100644 --- a/R/cocitation.R +++ b/R/cocitation.R @@ -22,27 +22,22 @@ #' Cocitation coupling #' #' Two vertices are cocited if there is another vertex citing both of them. -#' `cocitation()` simply counts how many types two vertices are cocited. The -#' bibliographic coupling of two vertices is the number of other vertices they -#' both cite, `bibcoupling()` calculates this. +#' `cocitation()` simply counts how many types two vertices are cocited. +#' The bibliographic coupling of two vertices is the number of other vertices they both cite, `bibcoupling()` calculates this. #' -#' `cocitation()` calculates the cocitation counts for the vertices in the -#' `v` argument and all vertices in the graph. +#' `cocitation()` calculates the cocitation counts for the vertices in the `v` argument and all vertices in the graph. #' -#' `bibcoupling()` calculates the bibliographic coupling for vertices in -#' `v` and all vertices in the graph. +#' `bibcoupling()` calculates the bibliographic coupling for vertices in `v` and all vertices in the graph. #' -#' Calculating the cocitation or bibliographic coupling for only one vertex -#' costs the same amount of computation as for all vertices. This might change -#' in the future. +#' Calculating the cocitation or bibliographic coupling for only one vertex costs the same amount of computation as for all vertices. +#' This might change in the future. #' #' @param graph The graph object to analyze -#' @param v Vertex sequence or numeric vector, the vertex IDs for which the -#' cocitation or bibliographic coupling values we want to calculate. The -#' default `NULL` selects all vertices. -#' @return A numeric matrix with `length(v)` lines and -#' `vcount(graph)` columns. Element `(i,j)` contains the cocitation -#' or bibliographic coupling for vertices `v[i]` and `j`. +#' @param v Vertex sequence or numeric vector, +#' the vertex IDs for which the cocitation or bibliographic coupling values we want to calculate. +#' The default `NULL` selects all vertices. +#' @return A numeric matrix with `length(v)` lines and `vcount(graph)` columns. +#' Element `(i,j)` contains the cocitation or bibliographic coupling for vertices `v[i]` and `j`. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @family cocitation #' @export diff --git a/R/cohesive.blocks.R b/R/cohesive.blocks.R index ce601cc1a2e..3f0f700aefe 100644 --- a/R/cohesive.blocks.R +++ b/R/cohesive.blocks.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `exportPajek()` was renamed to [export_pajek()] to create a more -#' consistent API. +#' `exportPajek()` was renamed to [export_pajek()] to create a more consistent API. #' @inheritParams export_pajek #' @keywords internal #' @export @@ -24,8 +23,7 @@ exportPajek <- function(blocks, graph, file, project.file = TRUE) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `plotHierarchy()` was renamed to [plot_hierarchy()] to create a more -#' consistent API. +#' `plotHierarchy()` was renamed to [plot_hierarchy()] to create a more consistent API. #' @inheritParams plot_hierarchy #' @keywords internal #' @export @@ -44,8 +42,7 @@ plotHierarchy <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `maxcohesion()` was renamed to [max_cohesion()] to create a more -#' consistent API. +#' `maxcohesion()` was renamed to [max_cohesion()] to create a more consistent API. #' @inheritParams max_cohesion #' @keywords internal #' @export @@ -60,8 +57,7 @@ maxcohesion <- function(blocks) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.cohesion()` was renamed to [cohesion()] to create a more -#' consistent API. +#' `graph.cohesion()` was renamed to [cohesion()] to create a more consistent API. #' @param x x #' @param ... passed to `cohesion()` #' @keywords internal @@ -77,8 +73,7 @@ graph.cohesion <- function(x, ...) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `cohesive.blocks()` was renamed to [cohesive_blocks()] to create a more -#' consistent API. +#' `cohesive.blocks()` was renamed to [cohesive_blocks()] to create a more consistent API. #' @inheritParams cohesive_blocks #' @keywords internal #' @export @@ -93,8 +88,7 @@ cohesive.blocks <- function(graph, labels = TRUE) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `blockGraphs()` was renamed to [graphs_from_cohesive_blocks()] to create a more -#' consistent API. +#' `blockGraphs()` was renamed to [graphs_from_cohesive_blocks()] to create a more consistent API. #' @inheritParams graphs_from_cohesive_blocks #' @keywords internal #' @export @@ -132,153 +126,124 @@ blockGraphs <- function(blocks, graph) { #' #' Calculates cohesive blocks for objects of class `igraph`. #' -#' Cohesive blocking is a method of determining hierarchical subsets of graph -#' vertices based on their structural cohesion (or vertex connectivity). For a -#' given graph \eqn{G}, a subset of its vertices \eqn{S\subset V(G)}{S} is said -#' to be maximally \eqn{k}-cohesive if there is no superset of \eqn{S} with -#' vertex connectivity greater than or equal to \eqn{k}. Cohesive blocking is a -#' process through which, given a \eqn{k}-cohesive set of vertices, maximally -#' \eqn{l}-cohesive subsets are recursively identified with \eqn{l>k}. Thus a -#' hierarchy of vertex subsets is found, with the entire graph \eqn{G} at its -#' root. -#' -#' The function `cohesive_blocks()` implements cohesive blocking. It -#' returns a `cohesiveBlocks` object. `cohesiveBlocks` should be -#' handled as an opaque class, i.e. its internal structure should not be -#' accessed directly, but through the functions listed here. -#' -#' The function `length` can be used on `cohesiveBlocks` objects and -#' it gives the number of blocks. -#' -#' The function `blocks()` returns the actual blocks stored in the -#' `cohesiveBlocks` object. They are returned in a list of numeric -#' vectors, each containing vertex IDs. -#' -#' The function `graphs_from_cohesive_blocks()` is similar, but returns the blocks as -#' (induced) subgraphs of the input graph. The various (graph, vertex and edge) -#' attributes are kept in the subgraph. -#' -#' The function `cohesion()` returns a numeric vector, the cohesion of the -#' different blocks. The order of the blocks is the same as for the -#' `blocks()` and `graphs_from_cohesive_blocks()` functions. -#' -#' The block hierarchy can be queried using the `hierarchy()` function. It -#' returns an igraph graph, its vertex IDs are ordered according the order of -#' the blocks in the `blocks()` and `graphs_from_cohesive_blocks()`, `cohesion()`, +#' Cohesive blocking is a method of determining hierarchical subsets of graph vertices based on their structural cohesion (or vertex connectivity). +#' For a given graph \eqn{G}, +#' a subset of its vertices \eqn{S\subset V(G)}{S} is said to be maximally \eqn{k}-cohesive +#' if there is no superset of \eqn{S} with vertex connectivity greater than or equal to \eqn{k}. +#' Cohesive blocking is a process through which, given a \eqn{k}-cohesive set of vertices, +#' maximally \eqn{l}-cohesive subsets are recursively identified with \eqn{l>k}. +#' Thus a hierarchy of vertex subsets is found, with the entire graph \eqn{G} at its root. +#' +#' The function `cohesive_blocks()` implements cohesive blocking. +#' It returns a `cohesiveBlocks` object. +#' `cohesiveBlocks` should be handled as an opaque class, i.e. its internal structure should not be accessed directly, +#' but through the functions listed here. +#' +#' The function `length` can be used on `cohesiveBlocks` objects and it gives the number of blocks. +#' +#' The function `blocks()` returns the actual blocks stored in the `cohesiveBlocks` object. +#' They are returned in a list of numeric vectors, each containing vertex IDs. +#' +#' The function `graphs_from_cohesive_blocks()` is similar, but returns the blocks as (induced) subgraphs of the input graph. +#' The various (graph, vertex and edge) attributes are kept in the subgraph. +#' +#' The function `cohesion()` returns a numeric vector, the cohesion of the different blocks. +#' The order of the blocks is the same as for the `blocks()` and `graphs_from_cohesive_blocks()` functions. +#' +#' The block hierarchy can be queried using the `hierarchy()` function. +#' It returns an igraph graph, +#' its vertex IDs are ordered according the order of the blocks in the `blocks()` and `graphs_from_cohesive_blocks()`, `cohesion()`, #' etc. functions. #' #' `parent()` gives the parent vertex of each block, in the block hierarchy, #' for the root vertex it gives 0. #' -#' `plot_hierarchy()` plots the hierarchy tree of the cohesive blocks on the -#' active graphics device, by calling `igraph.plot`. -#' -#' The `export_pajek()` function can be used to export the graph and its -#' cohesive blocks in Pajek format. It can either export a single Pajek project -#' file with all the information, or a set of files, depending on its -#' `project.file` argument. If `project.file` is `TRUE`, then -#' the following information is written to the file (or connection) given in -#' the `file` argument: (1) the input graph, together with its attributes, -#' see [write_graph()] for details; (2) the hierarchy graph; and (3) -#' one binary partition for each cohesive block. If `project.file` is -#' `FALSE`, then the `file` argument must be a character scalar and -#' it is used as the base name for the generated files. If `file` is -#' \sQuote{basename}, then the following files are created: (1) -#' \sQuote{basename.net} for the original graph; (2) -#' \sQuote{basename_hierarchy.net} for the hierarchy graph; (3) -#' \sQuote{basename_block_x.net} for each cohesive block, where \sQuote{x} is -#' the number of the block, starting with one. -#' -#' `max_cohesion()` returns the maximal cohesion of each vertex, i.e. the -#' cohesion of the most cohesive block of the vertex. -#' -#' The generic function [summary()] works on `cohesiveBlocks` objects -#' and it prints a one line summary to the terminal. -#' -#' The generic function [print()] is also defined on `cohesiveBlocks` -#' objects and it is invoked automatically if the name of the -#' `cohesiveBlocks` object is typed in. It produces an output like this: +#' `plot_hierarchy()` plots the hierarchy tree of the cohesive blocks on the active graphics device, by calling `igraph.plot`. +#' +#' The `export_pajek()` function can be used to export the graph and its cohesive blocks in Pajek format. +#' It can either export a single Pajek project file with all the information, or a set of files, depending on its `project.file` argument. +#' If `project.file` is `TRUE`, then the following information is written to the file (or connection) given in the `file` argument: +#' (1) the input graph, together with its attributes, see [write_graph()] for details; (2) the hierarchy graph; +#' and (3) one binary partition for each cohesive block. +#' If `project.file` is `FALSE`, +#' then the `file` argument must be a character scalar and it is used as the base name for the generated files. +#' If `file` is \sQuote{basename}, then the following files are created: (1) \sQuote{basename.net} for the original graph; +#' (2) \sQuote{basename_hierarchy.net} for the hierarchy graph; (3) \sQuote{basename_block_x.net} for each cohesive block, +#' where \sQuote{x} is the number of the block, starting with one. +#' +#' `max_cohesion()` returns the maximal cohesion of each vertex, i.e. the cohesion of the most cohesive block of the vertex. +#' +#' The generic function [summary()] works on `cohesiveBlocks` objects and it prints a one line summary to the terminal. +#' +#' The generic function [print()] is also defined on `cohesiveBlocks` objects and it is invoked automatically +#' if the name of the `cohesiveBlocks` object is typed in. +#' It produces an output like this: #' \preformatted{ Cohesive block structure: #' B-1 c 1, n 23 #' '- B-2 c 2, n 14 oooooooo.. .o......oo ooo #' '- B-4 c 5, n 7 ooooooo... .......... ... #' '- B-3 c 2, n 10 ......o.oo o.oooooo.. ... #' '- B-5 c 3, n 4 ......o.oo o......... ... } -#' The left part shows the block structure, in this case for five -#' blocks. The first block always corresponds to the whole graph, even if its -#' cohesion is zero. Then cohesion of the block and the number of vertices in -#' the block are shown. The last part is only printed if the display is wide -#' enough and shows the vertices in the blocks, ordered by vertex IDs. -#' \sQuote{o} means that the vertex is included, a dot means that it is not, -#' and the vertices are shown in groups of ten. +#' The left part shows the block structure, in this case for five blocks. +#' The first block always corresponds to the whole graph, even if its cohesion is zero. +#' Then cohesion of the block and the number of vertices in the block are shown. +#' The last part is only printed if the display is wide enough and shows the vertices in the blocks, ordered by vertex IDs. +#' \sQuote{o} means that the vertex is included, a dot means that it is not, and the vertices are shown in groups of ten. #' -#' The generic function [plot()] plots the graph, showing one or more -#' cohesive blocks in it. +#' The generic function [plot()] plots the graph, showing one or more cohesive blocks in it. #' #' @aliases cohesiveBlocks blocks #' @aliases hierarchy parent export_pajek plot.cohesiveBlocks summary.cohesiveBlocks length.cohesiveBlocks print.cohesiveBlocks -#' @param graph For `cohesive_blocks()` a graph object of class -#' `igraph`. It must be undirected and simple. (See -#' [is_simple()].) -#' -#' For `graphs_from_cohesive_blocks()` and `export_pajek()` the same graph must be -#' supplied whose cohesive block structure is given in the `blocks()` -#' argument. -#' @param labels Logical, whether to add the vertex labels to the result -#' object. These labels can be then used when reporting and plotting the -#' cohesive blocks. -#' @param blocks,x,object A `cohesiveBlocks` object, created with the -#' `cohesive_blocks()` function. +#' @param graph For `cohesive_blocks()` a graph object of class `igraph`. +#' It must be undirected and simple. +#' (See [is_simple()].) +#' +#' For `graphs_from_cohesive_blocks()` and `export_pajek()` the same graph must be supplied whose cohesive block structure is given in the `blocks()` argument. +#' @param labels Logical, whether to add the vertex labels to the result object. +#' These labels can be then used when reporting and plotting the cohesive blocks. +#' @param blocks,x,object A `cohesiveBlocks` object, created with the `cohesive_blocks()` function. #' @param file Defines the file (or connection) the Pajek file is written to. #' -#' If the `project.file` argument is `TRUE`, then it can be a -#' filename (with extension), a file object, or in general any king of -#' connection object. The file/connection will be opened if it wasn't already. +#' If the `project.file` argument is `TRUE`, then it can be a filename (with extension), a file object, +#' or in general any king of connection object. +#' The file/connection will be opened if it wasn't already. #' -#' If the `project.file` argument is `FALSE`, then several files are -#' created and `file` must be a character scalar containing the base name -#' of the files, without extension. (But it can contain the path to the files.) +#' If the `project.file` argument is `FALSE`, +#' then several files are created and `file` must be a character scalar containing the base name of the files, without extension. +#' (But it can contain the path to the files.) #' #' See also details below. -#' @param project.file Logical, whether to create a single Pajek project -#' file containing all the data, or to create separated files for each item. +#' @param project.file Logical, whether to create a single Pajek project file containing all the data, +#' or to create separated files for each item. #' See details below. -#' @param y The graph whose cohesive blocks are supplied in the `x` -#' argument. -#' @param colbar Color bar for the vertex colors. Its length should be at least -#' \eqn{m+1}, where \eqn{m} is the maximum cohesion in the graph. -#' Alternatively, the vertex colors can also be directly specified via the -#' `col` argument. -#' @param col A vector of vertex colors, in any of the usual formats. (Symbolic -#' color names (e.g. \sQuote{red}, \sQuote{blue}, etc.) , RGB colors (e.g. -#' \sQuote{#FF9900FF}), integer numbers referring to the current palette. By -#' default the given `colbar` is used and vertices with the same maximal -#' cohesion will have the same color. -#' @param mark.groups A list of vertex sets to mark on the plot by circling -#' them. By default all cohesive blocks are marked, except the one -#' corresponding to the all vertices. -#' @param layout The layout of a plot, it is simply passed on to -#' `plot.igraph()`, see the possible formats there. The default `NULL` uses -#' the Reingold-Tilford layout generator. -#' @param \dots Additional arguments. `plot_hierarchy()` and [plot()] pass -#' them to `plot.igraph()`. [print()] and [summary()] ignore them. -#' `cohesive_blocks()` and `export_pajek()` do not accept extra arguments; -#' these dots must be empty for them. +#' @param y The graph whose cohesive blocks are supplied in the `x` argument. +#' @param colbar Color bar for the vertex colors. +#' Its length should be at least \eqn{m+1}, where \eqn{m} is the maximum cohesion in the graph. +#' Alternatively, the vertex colors can also be directly specified via the `col` argument. +#' @param col A vector of vertex colors, in any of the usual formats. +#' (Symbolic color names (e.g. \sQuote{red}, \sQuote{blue}, etc.) , RGB colors (e.g. \sQuote{#FF9900FF}), +#' integer numbers referring to the current palette. +#' By default the given `colbar` is used and vertices with the same maximal cohesion will have the same color. +#' @param mark.groups A list of vertex sets to mark on the plot by circling them. +#' By default all cohesive blocks are marked, except the one corresponding to the all vertices. +#' @param layout The layout of a plot, it is simply passed on to `plot.igraph()`, see the possible formats there. +#' The default `NULL` uses the Reingold-Tilford layout generator. +#' @param \dots Additional arguments. +#' `plot_hierarchy()` and [plot()] pass them to `plot.igraph()`. +#' [print()] and [summary()] ignore them. +#' `cohesive_blocks()` and `export_pajek()` do not accept extra arguments; these dots must be empty for them. #' @return `cohesive_blocks()` returns a `cohesiveBlocks` object. #' #' `blocks()` returns a list of numeric vectors, containing vertex IDs. #' -#' `graphs_from_cohesive_blocks()` returns a list of igraph graphs, corresponding to the -#' cohesive blocks. +#' `graphs_from_cohesive_blocks()` returns a list of igraph graphs, corresponding to the cohesive blocks. #' #' `cohesion()` returns a numeric vector, the cohesion of each block. #' -#' `hierarchy()` returns an igraph graph, the representation of the cohesive -#' block hierarchy. +#' `hierarchy()` returns an igraph graph, the representation of the cohesive block hierarchy. #' -#' `parent()` returns a numeric vector giving the parent block of each -#' cohesive block, in the block hierarchy. The block at the root of the -#' hierarchy has no parent and `0` is returned for it. +#' `parent()` returns a numeric vector giving the parent block of each cohesive block, in the block hierarchy. +#' The block at the root of the hierarchy has no parent and `0` is returned for it. #' #' `plot_hierarchy()`, [plot()] and `export_pajek()` return `NULL`, #' invisibly. @@ -286,8 +251,7 @@ blockGraphs <- function(blocks, graph) { #' `max_cohesion()` returns a numeric vector with one entry for each vertex, #' giving the cohesion of its most cohesive block. #' -#' [print()] and [summary()] return the `cohesiveBlocks` object -#' itself, invisibly. +#' [print()] and [summary()] return the `cohesiveBlocks` object itself, invisibly. #' #' `length` returns a numeric scalar, the number of blocks. #' @author Gabor Csardi \email{csardi.gabor@gmail.com} for the current diff --git a/R/coloring.R b/R/coloring.R index c1db02671d9..749cf473603 100644 --- a/R/coloring.R +++ b/R/coloring.R @@ -1,26 +1,19 @@ #' Greedy vertex coloring #' -#' `greedy_vertex_coloring()` finds a coloring for the vertices of a graph -#' based on a simple greedy algorithm. +#' `greedy_vertex_coloring()` finds a coloring for the vertices of a graph based on a simple greedy algorithm. #' -#' The goal of vertex coloring is to assign a "color" (represented as a positive -#' integer) to each vertex of the graph such that neighboring vertices never -#' have the same color. This function solves the problem by considering the -#' vertices one by one according to a heuristic, always choosing the smallest -#' color that differs from that of already colored neighbors. The coloring -#' obtained this way is not necessarily minimum but it can be calculated in -#' linear time. +#' The goal of vertex coloring is to assign a "color" (represented as a positive integer) to each vertex of the graph such that neighboring vertices never have the same color. +#' This function solves the problem by considering the vertices one by one according to a heuristic, +#' always choosing the smallest color that differs from that of already colored neighbors. +#' The coloring obtained this way is not necessarily minimum but it can be calculated in linear time. #' #' @param graph The graph object to color. #' @inheritParams rlang::args_dots_empty #' @param heuristic The selection heuristic for the next vertex to consider. -#' Possible values are: \dQuote{colored_neighbors} selects the vertex with the -#' largest number of already colored neighbors. \dQuote{dsatur} selects the -#' vertex with the largest number of unique colors in its neighborhood, i.e. -#' its "saturation degree"; when there are several maximum saturation degree -#' vertices, the one with the most uncolored neighbors will be selected. -#' @return A numeric vector where item `i` contains the color index -#' associated to vertex `i`. +#' Possible values are: \dQuote{colored_neighbors} selects the vertex with the largest number of already colored neighbors. +#' \dQuote{dsatur} selects the vertex with the largest number of unique colors in its neighborhood, i.e. its "saturation degree"; +#' when there are several maximum saturation degree vertices, the one with the most uncolored neighbors will be selected. +#' @return A numeric vector where item `i` contains the color index associated to vertex `i`. #' #' @family coloring #' @export diff --git a/R/community.R b/R/community.R index 0989f11dcfa..99955623509 100644 --- a/R/community.R +++ b/R/community.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `create.communities()` was renamed to [make_clusters()] to create a more -#' consistent API. +#' `create.communities()` was renamed to [make_clusters()] to create a more consistent API. #' @inheritParams make_clusters #' @keywords internal #' @export @@ -31,8 +30,7 @@ create.communities <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `walktrap.community()` was renamed to [cluster_walktrap()] to create a more -#' consistent API. +#' `walktrap.community()` was renamed to [cluster_walktrap()] to create a more consistent API. #' @inheritParams cluster_walktrap #' @keywords internal #' @export @@ -65,8 +63,7 @@ walktrap.community <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `spinglass.community()` was renamed to [cluster_spinglass()] to create a more -#' consistent API. +#' `spinglass.community()` was renamed to [cluster_spinglass()] to create a more consistent API. #' @inheritParams cluster_spinglass #' @keywords internal #' @export @@ -111,8 +108,7 @@ spinglass.community <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `showtrace()` was renamed to [show_trace()] to create a more -#' consistent API. +#' `showtrace()` was renamed to [show_trace()] to create a more consistent API. #' @inheritParams show_trace #' @keywords internal #' @export @@ -127,8 +123,7 @@ showtrace <- function(communities) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `optimal.community()` was renamed to [cluster_optimal()] to create a more -#' consistent API. +#' `optimal.community()` was renamed to [cluster_optimal()] to create a more consistent API. #' @inheritParams cluster_optimal #' @keywords internal #' @export @@ -143,8 +138,7 @@ optimal.community <- function(graph, weights = NULL) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `multilevel.community()` was renamed to [cluster_louvain()] to create a more -#' consistent API. +#' `multilevel.community()` was renamed to [cluster_louvain()] to create a more consistent API. #' @inheritParams cluster_louvain #' @keywords internal #' @export @@ -163,8 +157,7 @@ multilevel.community <- function(graph, weights = NULL, resolution = 1) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `mod.matrix()` was renamed to [modularity_matrix()] to create a more -#' consistent API. +#' `mod.matrix()` was renamed to [modularity_matrix()] to create a more consistent API. #' @inheritParams modularity_matrix #' @keywords internal #' @export @@ -191,8 +184,7 @@ mod.matrix <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `leading.eigenvector.community()` was renamed to [cluster_leading_eigen()] to create a more -#' consistent API. +#' `leading.eigenvector.community()` was renamed to [cluster_leading_eigen()] to create a more consistent API. #' @inheritParams cluster_leading_eigen #' @keywords internal #' @export @@ -229,8 +221,7 @@ leading.eigenvector.community <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `label.propagation.community()` was renamed to [cluster_label_prop()] to create a more -#' consistent API. +#' `label.propagation.community()` was renamed to [cluster_label_prop()] to create a more consistent API. #' @inheritParams cluster_label_prop #' @keywords internal #' @export @@ -263,8 +254,7 @@ label.propagation.community <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `is.hierarchical()` was renamed to [is_hierarchical()] to create a more -#' consistent API. +#' `is.hierarchical()` was renamed to [is_hierarchical()] to create a more consistent API. #' @inheritParams is_hierarchical #' @keywords internal #' @export @@ -279,8 +269,7 @@ is.hierarchical <- function(communities) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `infomap.community()` was renamed to [cluster_infomap()] to create a more -#' consistent API. +#' `infomap.community()` was renamed to [cluster_infomap()] to create a more consistent API. #' @inheritParams cluster_infomap #' @keywords internal #' @export @@ -307,8 +296,7 @@ infomap.community <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `fastgreedy.community()` was renamed to [cluster_fast_greedy()] to create a more -#' consistent API. +#' `fastgreedy.community()` was renamed to [cluster_fast_greedy()] to create a more consistent API. #' @inheritParams cluster_fast_greedy #' @keywords internal #' @export @@ -339,8 +327,7 @@ fastgreedy.community <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `edge.betweenness.community()` was renamed to [cluster_edge_betweenness()] to create a more -#' consistent API. +#' `edge.betweenness.community()` was renamed to [cluster_edge_betweenness()] to create a more consistent API. #' @inheritParams cluster_edge_betweenness #' @keywords internal #' @export @@ -377,8 +364,7 @@ edge.betweenness.community <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `dendPlot()` was renamed to [plot_dendrogram()] to create a more -#' consistent API. +#' `dendPlot()` was renamed to [plot_dendrogram()] to create a more consistent API. #' @inheritParams plot_dendrogram #' @keywords internal #' @export @@ -393,8 +379,7 @@ dendPlot <- function(x, mode = igraph_opt("dend.plot.type"), ...) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `cutat()` was renamed to [cut_at()] to create a more -#' consistent API. +#' `cutat()` was renamed to [cut_at()] to create a more consistent API. #' @inheritParams cut_at #' @keywords internal #' @export @@ -409,8 +394,7 @@ cutat <- function(communities, no, steps) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `contract.vertices()` was renamed to [contract()] to create a more -#' consistent API. +#' `contract.vertices()` was renamed to [contract()] to create a more consistent API. #' @inheritParams contract #' @keywords internal #' @export @@ -433,8 +417,7 @@ contract.vertices <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `code.length()` was renamed to [code_len()] to create a more -#' consistent API. +#' `code.length()` was renamed to [code_len()] to create a more consistent API. #' @inheritParams code_len #' @keywords internal #' @export @@ -470,136 +453,107 @@ code.length <- function(communities) { #' Functions to deal with the result of network community detection #' -#' igraph community detection functions return their results as an object from -#' the `communities` class. This manual page describes the operations of -#' this class. -#' -#' Community structure detection algorithms try to find dense subgraphs in -#' directed or undirected graphs, by optimizing some criteria, and usually -#' using heuristics. -#' -#' igraph implements a number of community detection methods (see them below), -#' all of which return an object of the class `communities`. Because the -#' community structure detection algorithms are different, `communities` -#' objects do not always have the same structure. Nevertheless, they have some -#' common operations, these are documented here. -#' -#' The [print()] generic function is defined for `communities`, it -#' prints a short summary. -#' -#' The `length` generic function call be called on `communities` and -#' returns the number of communities. -#' -#' The `sizes()` function returns the community sizes, in the order of their -#' IDs. -#' -#' `membership()` gives the division of the vertices, into communities. It -#' returns a numeric vector, one value for each vertex, the ID of its -#' community. Community IDs start from one. Note that some algorithms calculate -#' the complete (or incomplete) hierarchical structure of the communities, and -#' not just a single partitioning. For these algorithms typically the -#' membership for the highest modularity value is returned, but see also the -#' manual pages of the individual algorithms. -#' -#' `communities()` is also the name of a function, that returns a list of -#' communities, each identified by their vertices. The vertices will have -#' symbolic names if the `add.vertex.names` igraph option is set, and the -#' graph itself was named. Otherwise numeric vertex IDs are used. -#' -#' `modularity()` gives the modularity score of the partitioning. (See -#' [modularity.igraph()] for details. For algorithms that do not -#' result a single partitioning, the highest modularity value is returned. -#' -#' `algorithm()` gives the name of the algorithm that was used to calculate -#' the community structure. -#' -#' `crossing()` returns a logical vector, with one value for each edge, -#' ordered according to the edge IDs. The value is `TRUE` iff the edge -#' connects two different communities, according to the (best) membership -#' vector, as returned by `membership()`. -#' -#' `is_hierarchical()` checks whether a hierarchical algorithm was used to -#' find the community structure. Some functions only make sense for -#' hierarchical methods (e.g. `merges()`, `cut_at()` and -#' [as.dendrogram()]). -#' -#' `merges()` returns the merge matrix for hierarchical methods. An error -#' message is given, if a non-hierarchical method was used to find the -#' community structure. You can check this by calling `is_hierarchical()` on -#' the `communities` object. -#' -#' `cut_at()` cuts the merge tree of a hierarchical community finding method, -#' at the desired place and returns a membership vector. The desired place can -#' be expressed as the desired number of communities or as the number of merge -#' steps to make. The function gives an error message, if called with a -#' non-hierarchical method. -#' -#' [as.dendrogram()] converts a hierarchical community structure to a -#' `dendrogram` object. It only works for hierarchical methods, and gives -#' an error message to others. See [stats::dendrogram()] for details. -#' -#' [stats::as.hclust()] is similar to [as.dendrogram()], but converts a -#' hierarchical community structure to a `hclust` object. -#' -#' [ape::as.phylo()] converts a hierarchical community structure to a `phylo` -#' object, you will need the `ape` package for this. -#' -#' `show_trace()` works (currently) only for communities found by the leading -#' eigenvector method ([cluster_leading_eigen()]), and -#' returns a character vector that gives the steps performed by the algorithm -#' while finding the communities. -#' -#' `code_len()` is defined for the InfoMAP method -#' ([cluster_infomap()] and returns the code length of the -#' partition. -#' -#' It is possibly to call the [plot()] function on `communities` -#' objects. This will plot the graph (and uses [plot.igraph()] -#' internally), with the communities shown. By default it colores the vertices -#' according to their communities, and also marks the vertex groups -#' corresponding to the communities. It passes additional arguments to -#' [plot.igraph()], please see that and also -#' [igraph.plotting] on how to change the plot. +#' igraph community detection functions return their results as an object from the `communities` class. +#' This manual page describes the operations of this class. +#' +#' Community structure detection algorithms try to find dense subgraphs in directed or undirected graphs, by optimizing some criteria, +#' and usually using heuristics. +#' +#' igraph implements a number of community detection methods (see them below), all of which return an object of the class `communities`. +#' Because the community structure detection algorithms are different, `communities` objects do not always have the same structure. +#' Nevertheless, they have some common operations, these are documented here. +#' +#' The [print()] generic function is defined for `communities`, it prints a short summary. +#' +#' The `length` generic function call be called on `communities` and returns the number of communities. +#' +#' The `sizes()` function returns the community sizes, in the order of their IDs. +#' +#' `membership()` gives the division of the vertices, into communities. +#' It returns a numeric vector, one value for each vertex, the ID of its community. +#' Community IDs start from one. +#' Note that some algorithms calculate the complete (or incomplete) hierarchical structure of the communities, +#' and not just a single partitioning. +#' For these algorithms typically the membership for the highest modularity value is returned, +#' but see also the manual pages of the individual algorithms. +#' +#' `communities()` is also the name of a function, that returns a list of communities, each identified by their vertices. +#' The vertices will have symbolic names if the `add.vertex.names` igraph option is set, and the graph itself was named. +#' Otherwise numeric vertex IDs are used. +#' +#' `modularity()` gives the modularity score of the partitioning. +#' (See [modularity.igraph()] for details. +#' For algorithms that do not result a single partitioning, the highest modularity value is returned. +#' +#' `algorithm()` gives the name of the algorithm that was used to calculate the community structure. +#' +#' `crossing()` returns a logical vector, with one value for each edge, ordered according to the edge IDs. +#' The value is `TRUE` iff the edge connects two different communities, according to the (best) membership vector, +#' as returned by `membership()`. +#' +#' `is_hierarchical()` checks whether a hierarchical algorithm was used to find the community structure. +#' Some functions only make sense for hierarchical methods (e.g. `merges()`, `cut_at()` and [as.dendrogram()]). +#' +#' `merges()` returns the merge matrix for hierarchical methods. +#' An error message is given, if a non-hierarchical method was used to find the community structure. +#' You can check this by calling `is_hierarchical()` on the `communities` object. +#' +#' `cut_at()` cuts the merge tree of a hierarchical community finding method, at the desired place and returns a membership vector. +#' The desired place can be expressed as the desired number of communities or as the number of merge steps to make. +#' The function gives an error message, if called with a non-hierarchical method. +#' +#' [as.dendrogram()] converts a hierarchical community structure to a `dendrogram` object. +#' It only works for hierarchical methods, and gives an error message to others. +#' See [stats::dendrogram()] for details. +#' +#' [stats::as.hclust()] is similar to [as.dendrogram()], but converts a hierarchical community structure to a `hclust` object. +#' +#' [ape::as.phylo()] converts a hierarchical community structure to a `phylo` object, you will need the `ape` package for this. +#' +#' `show_trace()` works (currently) only for communities found by the leading eigenvector method ([cluster_leading_eigen()]), +#' and returns a character vector that gives the steps performed by the algorithm while finding the communities. +#' +#' `code_len()` is defined for the InfoMAP method ([cluster_infomap()] and returns the code length of the partition. +#' +#' It is possibly to call the [plot()] function on `communities` objects. +#' This will plot the graph (and uses [plot.igraph()] internally), with the communities shown. +#' By default it colores the vertices according to their communities, and also marks the vertex groups corresponding to the communities. +#' It passes additional arguments to [plot.igraph()], please see that and also [igraph.plotting] on how to change the plot. #' #' @rdname communities #' @family community -#' @param communities,x,object A `communities` object, the result of an -#' igraph community detection function. +#' @param communities,x,object A `communities` object, the result of an igraph community detection function. #' @param graph An igraph graph object, corresponding to `communities`. -#' @param y An igraph graph object, corresponding to the communities in -#' `x`. -#' @param no Integer scalar, the desired number of communities. If too low or -#' two high, then an error message is given. Exactly one of `no` and -#' `steps` must be supplied. -#' @param steps The number of merge operations to perform to produce the -#' communities. Exactly one of `no` and `steps` must be supplied. -#' @param col A vector of colors, in any format that is accepted by the regular -#' R plotting methods. This vector gives the colors of the vertices explicitly. -#' @param mark.groups A list of numeric vectors. The communities can be -#' highlighted using colored polygons. The groups for which the polygons are -#' drawn are given here. The default is to use the groups given by the -#' communities. Supply `NULL` here if you do not want to highlight any -#' groups. -#' @param edge.color The colors of the edges. By default the edges within -#' communities are colored green and other edges are red. -#' @param hang Numeric scalar indicating how the height of leaves should be -#' computed from the heights of their parents; see [plot.hclust()]. -#' @param use.modularity Logical, whether to use the modularity values -#' to define the height of the branches. -#' @param \dots Additional arguments. `plot.communities` passes these to -#' [plot.igraph()]. The other functions silently ignore -#' them. -#' @param membership Numeric vector, one value for each vertex, the membership -#' vector of the community structure. Might also be `NULL` if the -#' community structure is given in another way, e.g. by a merge matrix. -#' @param algorithm Name of the algorithm that produced the community -#' structure (character scalar). Default: `NULL`, meaning an unknown algorithm. -#' @param merges Merge matrix of the hierarchical -#' community structure. See `merges()` below for more information on its -#' format. Default: `NULL`. -#' @param modularity Numeric scalar or vector, the modularity value of the -#' community structure. It can also be `NULL`, if the modularity of the -#' (best) split is not available. +#' @param y An igraph graph object, corresponding to the communities in `x`. +#' @param no Integer scalar, the desired number of communities. +#' If too low or two high, then an error message is given. +#' Exactly one of `no` and `steps` must be supplied. +#' @param steps The number of merge operations to perform to produce the communities. +#' Exactly one of `no` and `steps` must be supplied. +#' @param col A vector of colors, in any format that is accepted by the regular R plotting methods. +#' This vector gives the colors of the vertices explicitly. +#' @param mark.groups A list of numeric vectors. +#' The communities can be highlighted using colored polygons. +#' The groups for which the polygons are drawn are given here. +#' The default is to use the groups given by the communities. +#' Supply `NULL` here if you do not want to highlight any groups. +#' @param edge.color The colors of the edges. +#' By default the edges within communities are colored green and other edges are red. +#' @param hang Numeric scalar indicating how the height of leaves should be computed from the heights of their parents; +#' see [plot.hclust()]. +#' @param use.modularity Logical, whether to use the modularity values to define the height of the branches. +#' @param \dots Additional arguments. +#' `plot.communities` passes these to [plot.igraph()]. +#' The other functions silently ignore them. +#' @param membership Numeric vector, one value for each vertex, the membership vector of the community structure. +#' Might also be `NULL` if the community structure is given in another way, e.g. by a merge matrix. +#' @param algorithm Name of the algorithm that produced the community structure (character scalar). +#' Default: `NULL`, meaning an unknown algorithm. +#' @param merges Merge matrix of the hierarchical community structure. +#' See `merges()` below for more information on its format. +#' Default: `NULL`. +#' @param modularity Numeric scalar or vector, the modularity value of the community structure. +#' It can also be `NULL`, if the modularity of the (best) split is not available. #' @return [print()] returns the `communities` object itself, #' invisibly. #' @@ -607,8 +561,7 @@ code.length <- function(communities) { #' #' `sizes()` returns a numeric vector. #' -#' `membership()` returns a numeric vector, one number for each vertex in -#' the graph that was the input of the community detection. +#' `membership()` returns a numeric vector, one number for each vertex in the graph that was the input of the community detection. #' #' `modularity()` returns a numeric scalar. #' @@ -620,24 +573,20 @@ code.length <- function(communities) { #' #' `merges()` returns a two-column numeric matrix. #' -#' `cut_at()` returns a numeric vector, the membership vector of the -#' vertices. +#' `cut_at()` returns a numeric vector, the membership vector of the vertices. #' #' [as.dendrogram()] returns a [dendrogram] object. #' #' `show_trace()` returns a character vector. #' -#' `code_len()` returns a numeric scalar for communities found with the -#' InfoMAP method and `NULL` for other methods. +#' `code_len()` returns a numeric scalar for communities found with the InfoMAP method and `NULL` for other methods. #' #' [plot()] for `communities` objects returns `NULL`, invisibly. #' #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso See [plot_dendrogram()] for plotting community structure -#' dendrograms. +#' @seealso See [plot_dendrogram()] for plotting community structure dendrograms. #' -#' See [compare()] for comparing two community structures -#' on the same graph. +#' See [compare()] for comparing two community structures on the same graph. #' @keywords graphs #' @export #' @examples @@ -677,9 +626,8 @@ print.membership <- function(x, ...) print(unclass(x), ...) #' Declare a numeric vector as a membership vector #' -#' This is useful if you want to use functions defined on -#' membership vectors, but your membership vector does not -#' come from an igraph clustering method. +#' This is useful if you want to use functions defined on membership vectors, +#' but your membership vector does not come from an igraph clustering method. #' #' @param x The input vector. #' @return The input vector, with the `membership` class added. @@ -738,21 +686,16 @@ print.communities <- function(x, ...) { #' Creates a communities object. #' -#' This is useful to integrate the results of community finding algorithms -#' that are not included in igraph. +#' This is useful to integrate the results of community finding algorithms that are not included in igraph. #' #' @param graph The graph of the community structure. -#' @param membership The membership vector of the community structure, a -#' numeric vector denoting the ID of the community for each vertex. It -#' might be `NULL` for hierarchical community structures. +#' @param membership The membership vector of the community structure, a numeric vector denoting the ID of the community for each vertex. +#' It might be `NULL` for hierarchical community structures. #' @inheritParams rlang::args_dots_empty -#' @param algorithm Character string, the algorithm that generated -#' the community structure, it can be arbitrary. -#' @param merges A merge matrix, for hierarchical community structures (or -#' `NULL` otherwise. -#' @param modularity Modularity value of the community structure. If this -#' is `TRUE` and the membership vector is available, then it the -#' modularity values is calculated automatically. +#' @param algorithm Character string, the algorithm that generated the community structure, it can be arbitrary. +#' @param merges A merge matrix, for hierarchical community structures (or `NULL` otherwise. +#' @param modularity Modularity value of the community structure. +#' If this is `TRUE` and the membership vector is available, then it the modularity values is calculated automatically. #' @return A `communities` object. #' \describe{ #' \item{membership}{ @@ -870,71 +813,58 @@ modularity <- function(x, ...) { #' Modularity of a community structure of a graph #' -#' This function calculates how modular is a given division of a graph into -#' subgraphs. +#' This function calculates how modular is a given division of a graph into subgraphs. #' -#' `modularity()` calculates the modularity of a graph with respect to the -#' given `membership` vector. +#' `modularity()` calculates the modularity of a graph with respect to the given `membership` vector. #' -#' The modularity of a graph with respect to some division (or vertex types) -#' measures how good the division is, or how separated are the different vertex +#' The modularity of a graph with respect to some division (or vertex types) measures how good the division is, +#' or how separated are the different vertex #' types from each other. It defined as \deqn{Q=\frac{1}{2m} \sum_{i,j} #' (A_{ij}-\gamma\frac{k_i k_j}{2m})\delta(c_i,c_j),}{Q=1/(2m) * sum( (Aij-gamma*ki*kj/(2m) #' ) delta(ci,cj),i,j),} here \eqn{m} is the number of edges, \eqn{A_{ij}}{Aij} -#' is the element of the \eqn{A} adjacency matrix in row \eqn{i} and column -#' \eqn{j}, \eqn{k_i}{ki} is the degree of \eqn{i}, \eqn{k_j}{kj} is the degree -#' of \eqn{j}, \eqn{c_i}{ci} is the type (or component) of \eqn{i}, -#' \eqn{c_j}{cj} that of \eqn{j}, the sum goes over all \eqn{i} and \eqn{j} -#' pairs of vertices, and \eqn{\delta(x,y)}{delta(x,y)} is 1 if \eqn{x=y} and 0 -#' otherwise. For directed graphs, it is defined as +#' is the element of the \eqn{A} adjacency matrix in row \eqn{i} and column \eqn{j}, \eqn{k_i}{ki} is the degree of \eqn{i}, +#' \eqn{k_j}{kj} is the degree of \eqn{j}, \eqn{c_i}{ci} is the type (or component) of \eqn{i}, \eqn{c_j}{cj} that of \eqn{j}, +#' the sum goes over all \eqn{i} and \eqn{j} pairs of vertices, and \eqn{\delta(x,y)}{delta(x,y)} is 1 if \eqn{x=y} and 0 otherwise. +#' For directed graphs, it is defined as #' \deqn{Q = \frac{1}{m} \sum_{i,j} (A_{ij}-\gamma #' \frac{k_i^{out} k_j^{in}}{m})\delta(c_i,c_j).}{Q=1/(m) * sum( #' (Aij-gamma*ki^out*kj^in/(m) ) delta(ci,cj),i,j).} #' -#' The resolution parameter \eqn{\gamma}{gamma} allows weighting the random -#' null model, which might be useful when finding partitions with a high -#' modularity. Maximizing modularity with higher values of the resolution -#' parameter typically results in more, smaller clusters when finding -#' partitions with a high modularity. Lower values typically results in fewer, -#' larger clusters. The original definition of modularity is retrieved when -#' setting \eqn{\gamma}{gamma} to 1. -#' -#' If edge weights are given, then these are considered as the element of the -#' \eqn{A} adjacency matrix, and \eqn{k_i}{ki} is the sum of weights of -#' adjacent edges for vertex \eqn{i}. -#' -#' `modularity_matrix()` calculates the modularity matrix. This is a dense matrix, -#' and it is defined as the difference of the adjacency matrix and the -#' configuration model null model matrix. In other words element -#' \eqn{M_{ij}}{M[i,j]} is given as \eqn{A_{ij}-d_i +#' The resolution parameter \eqn{\gamma}{gamma} allows weighting the random null model, +#' which might be useful when finding partitions with a high modularity. +#' Maximizing modularity with higher values of the resolution parameter typically results in more, +#' smaller clusters when finding partitions with a high modularity. +#' Lower values typically results in fewer, larger clusters. +#' The original definition of modularity is retrieved when setting \eqn{\gamma}{gamma} to 1. +#' +#' If edge weights are given, then these are considered as the element of the \eqn{A} adjacency matrix, +#' and \eqn{k_i}{ki} is the sum of weights of adjacent edges for vertex \eqn{i}. +#' +#' `modularity_matrix()` calculates the modularity matrix. +#' This is a dense matrix, and it is defined as the difference of the adjacency matrix and the configuration model null model matrix. +#' In other words element \eqn{M_{ij}}{M[i,j]} is given as \eqn{A_{ij}-d_i #' d_j/(2m)}{A[i,j]-d[i]d[j]/(2m)}, where \eqn{A_{ij}}{A[i,j]} is the (possibly #' weighted) adjacency matrix, \eqn{d_i}{d[i]} is the degree of vertex \eqn{i}, -#' and \eqn{m} is the number of edges (or the total weights in the graph, if it -#' is weighed). +#' and \eqn{m} is the number of edges (or the total weights in the graph, if it is weighed). #' #' @aliases modularity #' @param x,graph The input graph. -#' @param membership Numeric vector, one value for each vertex, the membership -#' vector of the community structure. -#' @param weights Numeric vector giving edge weights. Default: `NULL`. -#' @param resolution The resolution parameter. Must be greater than or equal to +#' @param membership Numeric vector, one value for each vertex, the membership vector of the community structure. +#' @param weights Numeric vector giving edge weights. +#' Default: `NULL`. +#' @param resolution The resolution parameter. +#' Must be greater than or equal to #' 0. Set it to 1 to use the classical definition of modularity. -#' @param directed Whether to use the directed or undirected version of -#' modularity. Ignored for undirected graphs. -#' @param \dots For `modularity_matrix()`, these dots must be empty. For -#' `modularity()`, unused, present for S3 method consistency but may be -#' used by other methods that implement it. -#' @return For `modularity()` a numeric scalar, the modularity score of the -#' given configuration. -#' -#' For `modularity_matrix()` a numeric square matrix, its order is the number of -#' vertices in the graph. +#' @param directed Whether to use the directed or undirected version of modularity. +#' Ignored for undirected graphs. +#' @param \dots For `modularity_matrix()`, these dots must be empty. +#' For `modularity()`, unused, present for S3 method consistency but may be used by other methods that implement it. +#' @return For `modularity()` a numeric scalar, the modularity score of the given configuration. +#' +#' For `modularity_matrix()` a numeric square matrix, its order is the number of vertices in the graph. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso [cluster_walktrap()], -#' [cluster_edge_betweenness()], -#' [cluster_fast_greedy()], [cluster_spinglass()], -#' [cluster_louvain()] and [cluster_leiden()] for -#' various community detection methods. +#' @seealso [cluster_walktrap()], [cluster_edge_betweenness()], [cluster_fast_greedy()], [cluster_spinglass()], +#' [cluster_louvain()] and [cluster_leiden()] for various community detection methods. #' @references Clauset, A.; Newman, M. E. J. & Moore, C. Finding community #' structure in very large networks, *Physical Review E* 2004, 70, 066111 #' @method modularity igraph @@ -1441,86 +1371,71 @@ community.to.membership2 <- function(merges, vcount, steps) { #' Finding communities in graphs based on statistical meachanics #' -#' This function tries to find communities in graphs via a spin-glass model and -#' simulated annealing. +#' This function tries to find communities in graphs via a spin-glass model and simulated annealing. #' -#' This function tries to find communities in a graph. A community is a set of -#' nodes with many edges inside the community and few edges between outside it -#' (i.e. between the community itself and the rest of the graph.) +#' This function tries to find communities in a graph. +#' A community is a set of nodes with many edges inside the community and few edges between outside it (i.e. between the community itself and the rest of the graph.) #' -#' This idea is reversed for edges having a negative weight, i.e. few negative -#' edges inside a community and many negative edges between communities. Note -#' that only the \sQuote{neg} implementation supports negative edge weights. +#' This idea is reversed for edges having a negative weight, +#' i.e. few negative edges inside a community and many negative edges between communities. +#' Note that only the \sQuote{neg} implementation supports negative edge weights. #' -#' The `spinglass.cummunity` function can solve two problems related to -#' community detection. If the `vertex` argument is not given (or it is -#' `NULL`), then the regular community detection problem is solved -#' (approximately), i.e. partitioning the vertices into communities, by -#' optimizing the an energy function. +#' The `spinglass.cummunity` function can solve two problems related to community detection. +#' If the `vertex` argument is not given (or it is `NULL`), then the regular community detection problem is solved (approximately), +#' i.e. partitioning the vertices into communities, by optimizing the an energy function. #' -#' If the `vertex` argument is given and it is not `NULL`, then it -#' must be a vertex ID, and the same energy function is used to find the -#' community of the the given vertex. See also the examples below. +#' If the `vertex` argument is given and it is not `NULL`, then it must be a vertex ID, +#' and the same energy function is used to find the community of the the given vertex. +#' See also the examples below. #' -#' @param graph The input graph. Edge directions are ignored in directed graphs. +#' @param graph The input graph. +#' Edge directions are ignored in directed graphs. #' @inheritParams rlang::args_dots_empty -#' @param weights The weights of the edges. It must be a positive numeric vector, -#' `NULL` or `NA`. If it is `NULL` and the input graph has a -#' \sQuote{weight} edge attribute, then that attribute will be used. If -#' `NULL` and no such attribute is present, then the edges will have equal -#' weights. Set this to `NA` if the graph was a \sQuote{weight} edge -#' attribute, but you don't want to use it for community detection. A larger -#' edge weight means a stronger connection for this function. -#' @param vertex This parameter can be used to calculate the community of a -#' given vertex without calculating all communities. Note that if this argument -#' is present then some other arguments are ignored. -#' @param spins Integer constant, the number of spins to use. This is the upper -#' limit for the number of communities. It is not a problem to supply a -#' (reasonably) big number here, in which case some spin states will be -#' unpopulated. -#' @param parupdate Logical, whether to update the spins of the -#' vertices in parallel (synchronously) or not. This argument is ignored if the -#' second form of the function is used (i.e. the \sQuote{`vertex`} argument -#' is present). It is also not implemented in the \dQuote{neg} implementation. -#' @param start.temp Real constant, the start temperature. This argument is -#' ignored if the second form of the function is used (i.e. the -#' \sQuote{`vertex`} argument is present). -#' @param stop.temp Real constant, the stop temperature. The simulation -#' terminates if the temperature lowers below this level. This argument is -#' ignored if the second form of the function is used (i.e. the -#' \sQuote{`vertex`} argument is present). -#' @param cool.fact Cooling factor for the simulated annealing. This argument -#' is ignored if the second form of the function is used (i.e. the -#' \sQuote{`vertex`} argument is present). -#' @param update.rule Character constant giving the \sQuote{null-model} of the -#' simulation. Possible values: \dQuote{simple} and \dQuote{config}. -#' \dQuote{simple} uses a random graph with the same number of edges as the -#' baseline probability and \dQuote{config} uses a random graph with the same -#' vertex degrees as the input graph. -#' @param gamma Real constant, the gamma argument of the algorithm. This -#' specifies the balance between the importance of present and non-present -#' edges in a community. Roughly, a comunity is a set of vertices having many -#' edges inside the community and few edges outside the community. The default -#' 1.0 value makes existing and non-existing links equally important. Smaller -#' values make the existing links, greater values the missing links more -#' important. -#' @param implementation Character scalar. Currently igraph contains two -#' implementations for the Spin-glass community finding algorithm. The faster -#' original implementation is the default. The other implementation, that takes -#' into account negative weights, can be chosen by supplying \sQuote{neg} here. -#' @param gamma.minus Real constant, the gamma.minus parameter of the -#' algorithm. This specifies the balance between the importance of present and -#' non-present negative weighted edges in a community. Smaller values of -#' gamma.minus, leads to communities with lesser negative intra-connectivity. -#' If this argument is set to zero, the algorithm reduces to a graph coloring -#' algorithm, using the number of spins as the number of colors. This argument -#' is ignored if the \sQuote{orig} implementation is chosen. -#' @return If the `vertex` argument is not given, i.e. the first form is -#' used then a [cluster_spinglass()] returns a -#' [communities()] object. -#' -#' If the `vertex` argument is present, i.e. the second form is used then a -#' named list is returned with the following components: +#' @param weights The weights of the edges. +#' It must be a positive numeric vector, `NULL` or `NA`. +#' If it is `NULL` and the input graph has a \sQuote{weight} edge attribute, then that attribute will be used. +#' If `NULL` and no such attribute is present, then the edges will have equal weights. +#' Set this to `NA` if the graph was a \sQuote{weight} edge attribute, but you don't want to use it for community detection. +#' A larger edge weight means a stronger connection for this function. +#' @param vertex This parameter can be used to calculate the community of a given vertex without calculating all communities. +#' Note that if this argument is present then some other arguments are ignored. +#' @param spins Integer constant, the number of spins to use. +#' This is the upper limit for the number of communities. +#' It is not a problem to supply a (reasonably) big number here, in which case some spin states will be unpopulated. +#' @param parupdate Logical, whether to update the spins of the vertices in parallel (synchronously) or not. +#' This argument is ignored if the second form of the function is used (i.e. the \sQuote{`vertex`} argument is present). +#' It is also not implemented in the \dQuote{neg} implementation. +#' @param start.temp Real constant, +#' the start temperature. +#' This argument is ignored if the second form of the function is used (i.e. the \sQuote{`vertex`} argument is present). +#' @param stop.temp Real constant, the stop temperature. +#' The simulation terminates if the temperature lowers below this level. +#' This argument is ignored if the second form of the function is used (i.e. the \sQuote{`vertex`} argument is present). +#' @param cool.fact Cooling factor for the simulated annealing. +#' This argument is ignored +#' if the second form of the function is used (i.e. the \sQuote{`vertex`} argument is present). +#' @param update.rule Character constant giving the \sQuote{null-model} of the simulation. +#' Possible values: \dQuote{simple} and \dQuote{config}. +#' \dQuote{simple} uses a random graph with the same number of edges as the baseline probability and \dQuote{config} uses a random graph with the same vertex degrees as the input graph. +#' @param gamma Real constant, the gamma argument of the algorithm. +#' This specifies the balance between the importance of present and non-present edges in a community. +#' Roughly, a comunity is a set of vertices having many edges inside the community and few edges outside the community. +#' The default 1.0 value makes existing and non-existing links equally important. +#' Smaller values make the existing links, greater values the missing links more important. +#' @param implementation Character scalar. +#' Currently igraph contains two implementations for the Spin-glass community finding algorithm. +#' The faster original implementation is the default. +#' The other implementation, that takes into account negative weights, can be chosen by supplying \sQuote{neg} here. +#' @param gamma.minus Real constant, the gamma.minus parameter of the algorithm. +#' This specifies the balance between the importance of present and non-present negative weighted edges in a community. +#' Smaller values of gamma.minus, leads to communities with lesser negative intra-connectivity. +#' If this argument is set to zero, the algorithm reduces to a graph coloring algorithm, +#' using the number of spins as the number of colors. +#' This argument is ignored if the \sQuote{orig} implementation is chosen. +#' @return If the `vertex` argument is not given, +#' i.e. the first form is used then a [cluster_spinglass()] returns a [communities()] object. +#' +#' If the `vertex` argument is present, i.e. the second form is used then a named list is returned with the following components: #' \describe{ #' \item{community}{ #' Numeric vector giving the IDs of the vertices in the same community as `vertex`. @@ -1698,93 +1613,72 @@ cluster_spinglass <- function( #' Finding community structure of a graph using the Leiden algorithm of Traag, #' van Eck & Waltman. #' -#' The Leiden algorithm is similar to the Louvain algorithm, -#' [cluster_louvain()], but it is faster and yields higher quality -#' solutions. It can optimize both modularity and the Constant Potts Model, -#' which does not suffer from the resolution-limit (see preprint -#' ). +#' The Leiden algorithm is similar to the Louvain algorithm, [cluster_louvain()], but it is faster and yields higher quality solutions. +#' It can optimize both modularity and the Constant Potts Model, +#' which does not suffer from the resolution-limit (see preprint ). #' #' The Leiden algorithm consists of three phases: (1) local moving of nodes, -#' (2) refinement of the partition and (3) aggregation of the network based on -#' the refined partition, using the non-refined partition to create an initial -#' partition for the aggregate network. In the local move procedure in the -#' Leiden algorithm, only nodes whose neighborhood has changed are visited. The -#' refinement is done by restarting from a singleton partition within each -#' cluster and gradually merging the subclusters. When aggregating, a single -#' cluster may then be represented by several nodes (which are the subclusters -#' identified in the refinement). -#' -#' The Leiden algorithm provides several guarantees. The Leiden algorithm is -#' typically iterated: the output of one iteration is used as the input for the -#' next iteration. At each iteration all clusters are guaranteed to be -#' connected and well-separated. After an iteration in which nothing has -#' changed, all nodes and some parts are guaranteed to be locally optimally -#' assigned. Finally, asymptotically, all subsets of all clusters are -#' guaranteed to be locally optimally assigned. For more details, please see -#' Traag, Waltman & van Eck (2019). +#' (2) refinement of the partition and (3) aggregation of the network based on the refined partition, +#' using the non-refined partition to create an initial partition for the aggregate network. +#' In the local move procedure in the Leiden algorithm, only nodes whose neighborhood has changed are visited. +#' The refinement is done by restarting from a singleton partition within each cluster and gradually merging the subclusters. +#' When aggregating, a single cluster may then be represented by several nodes (which are the subclusters identified in the refinement). +#' +#' The Leiden algorithm provides several guarantees. +#' The Leiden algorithm is typically iterated: the output of one iteration is used as the input for the next iteration. +#' At each iteration all clusters are guaranteed to be connected and well-separated. +#' After an iteration in which nothing has changed, all nodes and some parts are guaranteed to be locally optimally assigned. +#' Finally, asymptotically, all subsets of all clusters are guaranteed to be locally optimally assigned. +#' For more details, please see Traag, Waltman & van Eck (2019). #' #' The objective function being optimized is #' #' \deqn{\frac{1}{2m} \sum_{ij} (A_{ij} - \gamma n_i n_j)\delta(\sigma_i, \sigma_j)}{1 / 2m sum_ij (A_ij - gamma n_i n_j)d(s_i, s_j)} #' -#' where \eqn{m}{m} is the total edge weight, \eqn{A_{ij}}{A_ij} is the weight -#' of edge \eqn{(i, j)}, \eqn{\gamma}{gamma} is the so-called resolution -#' parameter, \eqn{n_i} is the node weight of node \eqn{i}, \eqn{\sigma_i}{s_i} -#' is the cluster of node \eqn{i} and \eqn{\delta(x, y) = 1}{d(x, y) = 1} if and -#' only if \eqn{x = y} and \eqn{0} otherwise. By setting \eqn{n_i = k_i}, the -#' degree of node \eqn{i}, and dividing \eqn{\gamma}{gamma} by \eqn{2m}, you -#' effectively obtain an expression for modularity. -#' -#' Hence, the standard modularity will be optimized when you supply the degrees -#' as `vertex_weights` and by supplying as a resolution parameter -#' \eqn{\frac{1}{2m}}{1/(2m)}, with \eqn{m} the number of edges. If you do not -#' specify any `vertex_weights`, the correct vertex weights and scaling of -#' \eqn{\gamma}{gamma} is determined automatically by the -#' `objective_function` argument. -#' -#' @param graph The input graph. It must be undirected. -#' @param objective_function Whether to use the Constant Potts Model (CPM) or -#' modularity. Must be either `"CPM"` or `"modularity"`. -#' @param weights The weights of the edges. It must be a positive numeric vector, -#' `NULL` or `NA`. If it is `NULL` and the input graph has a -#' \sQuote{weight} edge attribute, then that attribute will be used. If -#' `NULL` and no such attribute is present, then the edges will have equal -#' weights. Set this to `NA` if the graph was a \sQuote{weight} edge -#' attribute, but you don't want to use it for community detection. A larger -#' edge weight means a stronger connection for this function. -#' @param resolution The resolution parameter to use. Higher -#' resolutions lead to more smaller communities, while lower resolutions lead -#' to fewer larger communities. +#' where \eqn{m}{m} is the total edge weight, \eqn{A_{ij}}{A_ij} is the weight of edge \eqn{(i, j)}, +#' \eqn{\gamma}{gamma} is the so-called resolution parameter, \eqn{n_i} is the node weight of node \eqn{i}, +#' \eqn{\sigma_i}{s_i} is the cluster of node \eqn{i} and \eqn{\delta(x, y) = 1}{d(x, y) = 1} if and only +#' if \eqn{x = y} and \eqn{0} otherwise. +#' By setting \eqn{n_i = k_i}, the degree of node \eqn{i}, and dividing \eqn{\gamma}{gamma} by \eqn{2m}, +#' you effectively obtain an expression for modularity. +#' +#' Hence, the standard modularity will be optimized +#' when you supply the degrees as `vertex_weights` and by supplying as a resolution parameter \eqn{\frac{1}{2m}}{1/(2m)}, +#' with \eqn{m} the number of edges. +#' If you do not specify any `vertex_weights`, +#' the correct vertex weights and scaling of \eqn{\gamma}{gamma} is determined automatically by the `objective_function` argument. +#' +#' @param graph The input graph. +#' It must be undirected. +#' @param objective_function Whether to use the Constant Potts Model (CPM) or modularity. +#' Must be either `"CPM"` or `"modularity"`. +#' @param weights The weights of the edges. +#' It must be a positive numeric vector, `NULL` or `NA`. +#' If it is `NULL` and the input graph has a \sQuote{weight} edge attribute, then that attribute will be used. +#' If `NULL` and no such attribute is present, then the edges will have equal weights. +#' Set this to `NA` if the graph was a \sQuote{weight} edge attribute, but you don't want to use it for community detection. +#' A larger edge weight means a stronger connection for this function. +#' @param resolution The resolution parameter to use. +#' Higher resolutions lead to more smaller communities, while lower resolutions lead to fewer larger communities. #' @param resolution_parameter `r lifecycle::badge("superseded")` Use `resolution` instead. #' @param beta Parameter affecting the randomness in the Leiden algorithm. #' This affects only the refinement step of the algorithm. -#' @param initial_membership If provided, the Leiden algorithm -#' will try to improve this provided membership. If no argument is -#' provided, the aglorithm simply starts from the singleton partition. -#' @param n_iterations the number of iterations to iterate the Leiden -#' algorithm. Each iteration may improve the partition further. +#' @param initial_membership If provided, the Leiden algorithm will try to improve this provided membership. +#' If no argument is provided, the aglorithm simply starts from the singleton partition. +#' @param n_iterations the number of iterations to iterate the Leiden algorithm. +#' Each iteration may improve the partition further. #' @param vertex_weights the vertex weights used in the Leiden algorithm. -#' If this is not provided, it will be automatically determined on the basis -#' of the `objective_function`. Please see the details of this function -#' how to interpret the vertex weights. +#' If this is not provided, it will be automatically determined on the basis of the `objective_function`. +#' Please see the details of this function how to interpret the vertex weights. #' @inheritParams rlang::args_dots_empty -#' @return `cluster_leiden()` returns a [communities()] -#' object, please see the [communities()] manual page for details. +#' @return `cluster_leiden()` returns a [communities()] object, please see the [communities()] manual page for details. #' @author Vincent Traag #' @seealso See [communities()] for extracting the membership, #' modularity scores, etc. from the results. #' -#' Other community detection algorithms: [cluster_walktrap()], -#' [cluster_spinglass()], -#' [cluster_leading_eigen()], -#' [cluster_edge_betweenness()], -#' [cluster_fast_greedy()], -#' [cluster_label_prop()] -#' [cluster_louvain()] -#' [cluster_fluid_communities()] -#' [cluster_infomap()] -#' [cluster_optimal()] -#' [cluster_walktrap()] +#' Other community detection algorithms: [cluster_walktrap()], [cluster_spinglass()], [cluster_leading_eigen()], +#' [cluster_edge_betweenness()], [cluster_fast_greedy()], +#' [cluster_label_prop()] [cluster_louvain()] [cluster_fluid_communities()] [cluster_infomap()] [cluster_optimal()] [cluster_walktrap()] #' @references Traag, V. A., Waltman, L., & van Eck, N. J. (2019). From Louvain #' to Leiden: guaranteeing well-connected communities. Scientific #' reports, 9(1), 5233. doi: 10.1038/s41598-019-41695-z, arXiv:1810.08473v3 \[cs.SI\] @@ -1909,30 +1803,23 @@ cluster_leiden <- function( #' Community detection algorithm based on interacting fluids #' -#' The algorithm detects communities based on the simple idea of -#' several fluids interacting in a non-homogeneous environment -#' (the graph topology), expanding and contracting based on their -#' interaction and density. +#' The algorithm detects communities based on the simple idea of several fluids interacting in a non-homogeneous environment (the graph topology), +#' expanding and contracting based on their interaction and density. #' -#' @param graph The input graph. The graph must be simple and connected. +#' @param graph The input graph. +#' The graph must be simple and connected. #' Empty graphs are not supported as well as single vertex graphs. -#' Edge directions are ignored. Weights are not considered. -#' @param no.of.communities The number of communities to be found. Must be -#' greater than 0 and fewer than number of vertices in the graph. -#' @return `cluster_fluid_communities()` returns a [communities()] -#' object, please see the [communities()] manual page for details. +#' Edge directions are ignored. +#' Weights are not considered. +#' @param no.of.communities The number of communities to be found. +#' Must be greater than 0 and fewer than number of vertices in the graph. +#' @return `cluster_fluid_communities()` returns a [communities()] object, please see the [communities()] manual page for details. #' @author Ferran Parés #' @seealso See [communities()] for extracting the membership, #' modularity scores, etc. from the results. #' -#' Other community detection algorithms: [cluster_walktrap()], -#' [cluster_spinglass()], -#' [cluster_leading_eigen()], -#' [cluster_edge_betweenness()], -#' [cluster_fast_greedy()], -#' [cluster_label_prop()] -#' [cluster_louvain()], -#' [cluster_leiden()] +#' Other community detection algorithms: [cluster_walktrap()], [cluster_spinglass()], [cluster_leading_eigen()], +#' [cluster_edge_betweenness()], [cluster_fast_greedy()], [cluster_label_prop()] [cluster_louvain()], [cluster_leiden()] #' @references Parés F, Gasulla DG, et. al. (2018) Fluid Communities: A Competitive, #' Scalable and Diverse Community Detection Algorithm. In: Complex Networks #' & Their Applications VI: Proceedings of Complex Networks 2017 (The Sixth @@ -1963,46 +1850,34 @@ cluster_fluid_communities <- function(graph, no.of.communities) { #' Community structure via short random walks #' -#' This function tries to find densely connected subgraphs, also called -#' communities in a graph via random walks. The idea is that short random walks -#' tend to stay in the same community. +#' This function tries to find densely connected subgraphs, also called communities in a graph via random walks. +#' The idea is that short random walks tend to stay in the same community. #' -#' This function is the implementation of the Walktrap community finding -#' algorithm, see Pascal Pons, Matthieu Latapy: Computing communities in large -#' networks using random walks, https://arxiv.org/abs/physics/0512106 +#' This function is the implementation of the Walktrap community finding algorithm, see Pascal Pons, Matthieu Latapy: +#' Computing communities in large networks using random walks, https://arxiv.org/abs/physics/0512106 #' -#' @param graph The input graph. Edge directions are ignored in directed -#' graphs. +#' @param graph The input graph. +#' Edge directions are ignored in directed graphs. #' @inheritParams rlang::args_dots_empty -#' @param weights The weights of the edges. It must be a positive numeric vector, -#' `NULL` or `NA`. If it is `NULL` and the input graph has a -#' \sQuote{weight} edge attribute, then that attribute will be used. If -#' `NULL` and no such attribute is present, then the edges will have equal -#' weights. Set this to `NA` if the graph was a \sQuote{weight} edge -#' attribute, but you don't want to use it for community detection. Larger edge -#' weights increase the probability that an edge is selected by the random -#' walker. In other words, larger edge weights correspond to stronger connections. +#' @param weights The weights of the edges. +#' It must be a positive numeric vector, `NULL` or `NA`. +#' If it is `NULL` and the input graph has a \sQuote{weight} edge attribute, then that attribute will be used. +#' If `NULL` and no such attribute is present, then the edges will have equal weights. +#' Set this to `NA` if the graph was a \sQuote{weight} edge attribute, but you don't want to use it for community detection. +#' Larger edge weights increase the probability that an edge is selected by the random walker. +#' In other words, larger edge weights correspond to stronger connections. #' @param steps The length of the random walks to perform. -#' @param merges Logical, whether to include the merge matrix in the -#' result. -#' @param modularity Logical, whether to include the vector of the -#' modularity scores in the result. If the `membership` argument is true, -#' then it will always be calculated. -#' @param membership Logical, whether to calculate the membership vector -#' for the split corresponding to the highest modularity value. -#' @return `cluster_walktrap()` returns a [communities()] -#' object, please see the [communities()] manual page for details. +#' @param merges Logical, whether to include the merge matrix in the result. +#' @param modularity Logical, whether to include the vector of the modularity scores in the result. +#' If the `membership` argument is true, then it will always be calculated. +#' @param membership Logical, whether to calculate the membership vector for the split corresponding to the highest modularity value. +#' @return `cluster_walktrap()` returns a [communities()] object, please see the [communities()] manual page for details. #' @author Pascal Pons () and Gabor Csardi #' \email{csardi.gabor@@gmail.com} for the R and igraph interface -#' @seealso See [communities()] on getting the actual membership -#' vector, merge matrix, modularity score, etc. -#' -#' [modularity()] and [cluster_fast_greedy()], -#' [cluster_spinglass()], -#' [cluster_leading_eigen()], -#' [cluster_edge_betweenness()], [cluster_louvain()], -#' and [cluster_leiden()] for other community detection -#' methods. +#' @seealso See [communities()] on getting the actual membership vector, merge matrix, modularity score, etc. +#' +#' [modularity()] and [cluster_fast_greedy()], [cluster_spinglass()], [cluster_leading_eigen()], [cluster_edge_betweenness()], +#' [cluster_louvain()], and [cluster_leiden()] for other community detection methods. #' @references Pascal Pons, Matthieu Latapy: Computing communities in large #' networks using random walks, https://arxiv.org/abs/physics/0512106 #' @family community @@ -2112,70 +1987,53 @@ cluster_walktrap <- function( #' Community structure detection based on edge betweenness #' -#' Community structure detection based on the betweenness of the edges -#' in the network. This method is also known as the Girvan-Newman -#' algorithm. -#' -#' The idea behind this method is that the betweenness of the edges connecting -#' two communities is typically high, as many of the shortest paths between -#' vertices in separate communities pass through them. The algorithm -#' successively removes edges with the highest betweenness, recalculating -#' betweenness values after each removal. This way eventually the network splits -#' into two components, then one of these components splits again, and so on, -#' until all edges are removed. The resulting hierarhical partitioning of the -#' vertices can be encoded as a dendrogram. -#' -#' `cluster_edge_betweenness()` returns various information collected -#' through the run of the algorithm. Specifically, `removed.edges` contains -#' the edge IDs in order of the edges' removal; `edge.betweenness` contains -#' the betweenness of each of these at the time of their removal; and -#' `bridges` contains the IDs of edges whose removal caused a split. +#' Community structure detection based on the betweenness of the edges in the network. +#' This method is also known as the Girvan-Newman algorithm. +#' +#' The idea behind this method is that the betweenness of the edges connecting two communities is typically high, +#' as many of the shortest paths between vertices in separate communities pass through them. +#' The algorithm successively removes edges with the highest betweenness, recalculating betweenness values after each removal. +#' This way eventually the network splits into two components, then one of these components splits again, and so on, +#' until all edges are removed. +#' The resulting hierarhical partitioning of the vertices can be encoded as a dendrogram. +#' +#' `cluster_edge_betweenness()` returns various information collected through the run of the algorithm. +#' Specifically, `removed.edges` contains the edge IDs in order of the edges' removal; +#' `edge.betweenness` contains the betweenness of each of these at the time of their removal; +#' and `bridges` contains the IDs of edges whose removal caused a split. #' #' @param graph The graph to analyze. #' @inheritParams rlang::args_dots_empty -#' @param weights The weights of the edges. It must be a positive numeric vector, -#' `NULL` or `NA`. If it is `NULL` and the input graph has a -#' \sQuote{weight} edge attribute, then that attribute will be used. If -#' `NULL` and no such attribute is present, then the edges will have equal -#' weights. Set this to `NA` if the graph was a \sQuote{weight} edge -#' attribute, but you don't want to use it for community detection. Edge weights -#' are used to calculate weighted edge betweenness. This means that edges are -#' interpreted as distances, not as connection strengths. -#' @param directed Logical, whether to calculate directed edge -#' betweenness for directed graphs. It is ignored for undirected graphs. -#' @param edge.betweenness Logical, whether to return the edge -#' betweenness of the edges at the time of their removal. -#' @param merges Logical, whether to return the merge matrix -#' representing the hierarchical community structure of the network. This -#' argument is called `merges`, even if the community structure algorithm -#' itself is divisive and not agglomerative: it builds the tree from top to -#' bottom. There is one line for each merge (i.e. split) in matrix, the first -#' line is the first merge (last split). The communities are identified by -#' integer number starting from one. Community IDs smaller than or equal to -#' \eqn{N}, the number of vertices in the graph, belong to singleton -#' communities, i.e. individual vertices. Before the first merge we have \eqn{N} -#' communities numbered from one to \eqn{N}. The first merge, the first line of -#' the matrix creates community \eqn{N+1}, the second merge creates community -#' \eqn{N+2}, etc. -#' @param bridges Logical, whether to return a list the edge removals -#' which actually splitted a component of the graph. -#' @param modularity Logical, whether to calculate the maximum -#' modularity score, considering all possibly community structures along the -#' edge-betweenness based edge removals. -#' @param membership Logical, whether to calculate the membership -#' vector corresponding to the highest possible modularity score. -#' @return `cluster_edge_betweenness()` returns a -#' [communities()] object, please see the [communities()] -#' manual page for details. +#' @param weights The weights of the edges. +#' It must be a positive numeric vector, `NULL` or `NA`. +#' If it is `NULL` and the input graph has a \sQuote{weight} edge attribute, then that attribute will be used. +#' If `NULL` and no such attribute is present, then the edges will have equal weights. +#' Set this to `NA` if the graph was a \sQuote{weight} edge attribute, but you don't want to use it for community detection. +#' Edge weights are used to calculate weighted edge betweenness. +#' This means that edges are interpreted as distances, not as connection strengths. +#' @param directed Logical, whether to calculate directed edge betweenness for directed graphs. +#' It is ignored for undirected graphs. +#' @param edge.betweenness Logical, whether to return the edge betweenness of the edges at the time of their removal. +#' @param merges Logical, +#' whether to return the merge matrix representing the hierarchical community structure of the network. +#' This argument is called `merges`, even if the community structure algorithm itself is divisive and not agglomerative: +#' it builds the tree from top to bottom. +#' There is one line for each merge (i.e. split) in matrix, the first line is the first merge (last split). +#' The communities are identified by integer number starting from one. +#' Community IDs smaller than or equal to \eqn{N}, the number of vertices in the graph, belong to singleton communities, +#' i.e. individual vertices. +#' Before the first merge we have \eqn{N} communities numbered from one to \eqn{N}. +#' The first merge, the first line of the matrix creates community \eqn{N+1}, the second merge creates community \eqn{N+2}, etc. +#' @param bridges Logical, whether to return a list the edge removals which actually splitted a component of the graph. +#' @param modularity Logical, whether to calculate the maximum modularity score, +#' considering all possibly community structures along the edge-betweenness based edge removals. +#' @param membership Logical, whether to calculate the membership vector corresponding to the highest possible modularity score. +#' @return `cluster_edge_betweenness()` returns a [communities()] object, please see the [communities()] manual page for details. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso [edge_betweenness()] for the definition and calculation -#' of the edge betweenness, [cluster_walktrap()], -#' [cluster_fast_greedy()], -#' [cluster_leading_eigen()] for other community detection -#' methods. -#' -#' See [communities()] for extracting the results of the community -#' detection. +#' @seealso [edge_betweenness()] for the definition and calculation of the edge betweenness, [cluster_walktrap()], [cluster_fast_greedy()], +#' [cluster_leading_eigen()] for other community detection methods. +#' +#' See [communities()] for extracting the results of the community detection. #' @references M Newman and M Girvan: Finding and evaluating community #' structure in networks, *Physical Review E* 69, 026113 (2004) #' @family community @@ -2289,41 +2147,31 @@ cluster_edge_betweenness <- function( #' Community structure via greedy optimization of modularity #' -#' This function tries to find dense subgraph, also called communities in -#' graphs via directly optimizing a modularity score. +#' This function tries to find dense subgraph, also called communities in graphs via directly optimizing a modularity score. #' -#' This function implements the fast greedy modularity optimization algorithm -#' for finding community structure, see A Clauset, MEJ Newman, C Moore: Finding -#' community structure in very large networks, -#' http://www.arxiv.org/abs/cond-mat/0408187 for the details. +#' This function implements the fast greedy modularity optimization algorithm for finding community structure, see A Clauset, MEJ Newman, +#' C Moore: Finding community structure in very large networks, http://www.arxiv.org/abs/cond-mat/0408187 for the details. #' -#' @param graph The input graph. It must be undirected and must not have -#' multi-edges. +#' @param graph The input graph. +#' It must be undirected and must not have multi-edges. #' @inheritParams rlang::args_dots_empty #' @param merges Logical, whether to return the merge matrix. -#' @param modularity Logical, whether to return a vector containing the -#' modularity after each merge. -#' @param membership Logical, whether to calculate the membership vector -#' corresponding to the maximum modularity score, considering all possible -#' community structures along the merges. -#' @param weights The weights of the edges. It must be a positive numeric vector, -#' `NULL` or `NA`. If it is `NULL` and the input graph has a -#' \sQuote{weight} edge attribute, then that attribute will be used. If -#' `NULL` and no such attribute is present, then the edges will have equal -#' weights. Set this to `NA` if the graph was a \sQuote{weight} edge -#' attribute, but you don't want to use it for community detection. A larger -#' edge weight means a stronger connection for this function. -#' @return `cluster_fast_greedy()` returns a [communities()] -#' object, please see the [communities()] manual page for details. +#' @param modularity Logical, whether to return a vector containing the modularity after each merge. +#' @param membership Logical, whether to calculate the membership vector corresponding to the maximum modularity score, +#' considering all possible community structures along the merges. +#' @param weights The weights of the edges. +#' It must be a positive numeric vector, `NULL` or `NA`. +#' If it is `NULL` and the input graph has a \sQuote{weight} edge attribute, then that attribute will be used. +#' If `NULL` and no such attribute is present, then the edges will have equal weights. +#' Set this to `NA` if the graph was a \sQuote{weight} edge attribute, but you don't want to use it for community detection. +#' A larger edge weight means a stronger connection for this function. +#' @return `cluster_fast_greedy()` returns a [communities()] object, please see the [communities()] manual page for details. #' @author Tamas Nepusz \email{ntamas@@gmail.com} and Gabor Csardi #' \email{csardi.gabor@@gmail.com} for the R interface. #' @seealso [communities()] for extracting the results. #' -#' See also [cluster_walktrap()], -#' [cluster_spinglass()], -#' [cluster_leading_eigen()] and -#' [cluster_edge_betweenness()], [cluster_louvain()] -#' [cluster_leiden()] for other methods. +#' See also [cluster_walktrap()], [cluster_spinglass()], [cluster_leading_eigen()] and [cluster_edge_betweenness()], +#' [cluster_louvain()] [cluster_leiden()] for other methods. #' @references A Clauset, MEJ Newman, C Moore: Finding community structure in #' very large networks, http://www.arxiv.org/abs/cond-mat/0408187 #' @family community @@ -2428,53 +2276,42 @@ igraph.i.levc.arp <- function(externalP, externalE) { } -#' Community structure detecting based on the leading eigenvector of the -#' community matrix +#' Community structure detecting based on the leading eigenvector of the community matrix #' -#' This function tries to find densely connected subgraphs in a graph by -#' calculating the leading non-negative eigenvector of the modularity matrix of -#' the graph. +#' This function tries to find densely connected subgraphs in a graph by calculating the leading non-negative eigenvector of the modularity matrix of the graph. #' #' The function documented in these section implements the \sQuote{leading #' eigenvector} method developed by Mark Newman, see the reference below. #' -#' The heart of the method is the definition of the modularity matrix, -#' `B`, which is `B=A-P`, `A` being the adjacency matrix of the -#' (undirected) network, and `P` contains the probability that certain -#' edges are present according to the \sQuote{configuration model}. In other -#' words, a `P[i,j]` element of `P` is the probability that there is -#' an edge between vertices `i` and `j` in a random network in which -#' the degrees of all vertices are the same as in the input graph. -#' -#' The leading eigenvector method works by calculating the eigenvector of the -#' modularity matrix for the largest positive eigenvalue and then separating -#' vertices into two community based on the sign of the corresponding element -#' in the eigenvector. If all elements in the eigenvector are of the same sign -#' that means that the network has no underlying comuunity structure. Check -#' Newman's paper to understand why this is a good method for detecting -#' community structure. -#' -#' @param graph The input graph. Should be undirected as the method needs a -#' symmetric matrix. -#' @param steps The number of steps to take, this is actually the number of -#' tries to make a step. It is not a particularly useful parameter. -#' @param weights The weights of the edges. It must be a positive numeric vector, -#' `NULL` or `NA`. If it is `NULL` and the input graph has a -#' \sQuote{weight} edge attribute, then that attribute will be used. If -#' `NULL` and no such attribute is present, then the edges will have equal -#' weights. Set this to `NA` if the graph was a \sQuote{weight} edge -#' attribute, but you don't want to use it for community detection. A larger -#' edge weight means a stronger connection for this function. -#' @param start `NULL`, or a numeric membership vector, giving the start -#' configuration of the algorithm. +#' The heart of the method is the definition of the modularity matrix, `B`, which is `B=A-P`, +#' `A` being the adjacency matrix of the (undirected) network, +#' and `P` contains the probability that certain edges are present according to the \sQuote{configuration model}. +#' In other words, +#' a `P[i,j]` element of `P` is the probability that there is an edge between vertices `i` and `j` in a random network in which the degrees of all vertices are the same as in the input graph. +#' +#' The leading eigenvector method works by calculating the eigenvector of the modularity matrix for the largest positive eigenvalue and then separating vertices into two community based on the sign of the corresponding element in the eigenvector. +#' If all elements in the eigenvector are of the same sign that means that the network has no underlying comuunity structure. +#' Check Newman's paper to understand why this is a good method for detecting community structure. +#' +#' @param graph The input graph. +#' Should be undirected as the method needs a symmetric matrix. +#' @param steps The number of steps to take, this is actually the number of tries to make a step. +#' It is not a particularly useful parameter. +#' @param weights The weights of the edges. +#' It must be a positive numeric vector, `NULL` or `NA`. +#' If it is `NULL` and the input graph has a \sQuote{weight} edge attribute, then that attribute will be used. +#' If `NULL` and no such attribute is present, then the edges will have equal weights. +#' Set this to `NA` if the graph was a \sQuote{weight} edge attribute, but you don't want to use it for community detection. +#' A larger edge weight means a stronger connection for this function. +#' @param start `NULL`, or a numeric membership vector, giving the start configuration of the algorithm. #' @param options A named list to override some ARPACK options. -#' @param callback Callback function. This -#' is called after each iteration, after calculating the leading eigenvector of -#' the modularity matrix. See details below. Default: `NULL`. +#' @param callback Callback function. +#' This is called after each iteration, after calculating the leading eigenvector of the modularity matrix. +#' See details below. +#' Default: `NULL`. #' @param extra Additional argument to supply to the callback function. #' @param env The environment in which the callback function is evaluated. -#' @return `cluster_leading_eigen()` returns a named list with the -#' following members: +#' @return `cluster_leading_eigen()` returns a named list with the following members: #' \describe{ #' \item{membership}{ #' The membership vector at the end of the algorithm, @@ -2493,8 +2330,8 @@ igraph.i.levc.arp <- function(externalP, externalE) { #' } #' } #' @section Callback functions: The `callback` argument can be used to -#' supply a function that is called after each eigenvector calculation. The -#' following arguments are supplied to this function: +#' supply a function that is called after each eigenvector calculation. +#' The following arguments are supplied to this function: #' #' \describe{ #' \item{membership}{ @@ -2520,8 +2357,8 @@ igraph.i.levc.arp <- function(externalP, externalE) { #' } #' } #' -#' The callback function should return a scalar number. If this number -#' is non-zero, then the clustering is terminated. +#' The callback function should return a scalar number. +#' If this number is non-zero, then the clustering is terminated. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @seealso [modularity()], [cluster_walktrap()], #' [cluster_edge_betweenness()], @@ -2608,16 +2445,13 @@ cluster_leading_eigen <- function( #' Finding communities based on propagating labels #' -#' This is a fast, nearly linear time algorithm for detecting community -#' structure in networks. In works by labeling the vertices with unique labels -#' and then updating the labels by majority voting in the neighborhood of the -#' vertex. +#' This is a fast, nearly linear time algorithm for detecting community structure in networks. +#' In works by labeling the vertices with unique labels and then updating the labels by majority voting in the neighborhood of the vertex. #' -#' This function implements the community detection method described in: -#' Raghavan, U.N. and Albert, R. and Kumara, S.: Near linear time algorithm to -#' detect community structures in large-scale networks. Phys Rev E 76, 036106. -#' (2007). This version extends the original method by the ability to take edge -#' weights into consideration and also by allowing some labels to be fixed. +#' This function implements the community detection method described in: Raghavan, U.N. and Albert, R. and Kumara, S.: +#' Near linear time algorithm to detect community structures in large-scale networks. +#' Phys Rev E 76, 036106. (2007). +#' This version extends the original method by the ability to take edge weights into consideration and also by allowing some labels to be fixed. #' #' From the abstract of the paper: \dQuote{In our algorithm every node is #' initialized with a unique label and at every step each node adopts the label @@ -2625,40 +2459,36 @@ cluster_leading_eigen <- function( #' connected groups of nodes form a consensus on a unique label to form #' communities.} #' -#' @param graph The input graph. Note that the algorithm was originally -#' defined for undirected graphs. You are advised to set \sQuote{mode} to -#' `all` if you pass a directed graph here to treat it as -#' undirected. -#' @param weights The weights of the edges. It must be a positive numeric vector, -#' `NULL` or `NA`. If it is `NULL` and the input graph has a -#' \sQuote{weight} edge attribute, then that attribute will be used. If -#' `NULL` and no such attribute is present, then the edges will have equal -#' weights. Set this to `NA` if the graph was a \sQuote{weight} edge -#' attribute, but you don't want to use it for community detection. A larger -#' edge weight means a stronger connection for this function. +#' @param graph The input graph. +#' Note that the algorithm was originally defined for undirected graphs. +#' You are advised to set \sQuote{mode} to `all` if you pass a directed graph here to treat it as undirected. +#' @param weights The weights of the edges. +#' It must be a positive numeric vector, `NULL` or `NA`. +#' If it is `NULL` and the input graph has a \sQuote{weight} edge attribute, then that attribute will be used. +#' If `NULL` and no such attribute is present, then the edges will have equal weights. +#' Set this to `NA` if the graph was a \sQuote{weight} edge attribute, but you don't want to use it for community detection. +#' A larger edge weight means a stronger connection for this function. #' @inheritParams rlang::args_dots_empty -#' @param mode Logical, whether to consider edge directions for the label propagation, -#' and if so, in which direction the labels should propagate. Ignored for undirected graphs. +#' @param mode Logical, whether to consider edge directions for the label propagation, and if so, +#' in which direction the labels should propagate. +#' Ignored for undirected graphs. #' "all" means to ignore edge directions (even in directed graphs). #' "out" means to propagate labels along the natural direction of the edges. #' "in" means to propagate labels backwards (i.e. from head to tail). -#' @param initial The initial state. If `NULL`, every vertex will have a -#' different label at the beginning. Otherwise it must be a vector with an -#' entry for each vertex. Non-negative values denote different labels, negative -#' entries denote vertices without labels. -#' @param fixed Logical vector denoting which labels are fixed. Of course this -#' makes sense only if you provided an initial state, otherwise this element -#' will be ignored. Also note that vertices without labels cannot be fixed. -#' @return `cluster_label_prop()` returns a -#' [communities()] object, please see the [communities()] -#' manual page for details. +#' @param initial The initial state. +#' If `NULL`, every vertex will have a different label at the beginning. +#' Otherwise it must be a vector with an entry for each vertex. +#' Non-negative values denote different labels, negative entries denote vertices without labels. +#' @param fixed Logical vector denoting which labels are fixed. +#' Of course this makes sense only if you provided an initial state, otherwise this element will be ignored. +#' Also note that vertices without labels cannot be fixed. +#' @return `cluster_label_prop()` returns a [communities()] object, please see the [communities()] manual page for details. #' @author Tamas Nepusz \email{ntamas@@gmail.com} for the C implementation, #' Gabor Csardi \email{csardi.gabor@@gmail.com} for this manual page. #' @seealso [communities()] for extracting the actual results. #' -#' [cluster_fast_greedy()], [cluster_walktrap()], -#' [cluster_spinglass()], [cluster_louvain()] and -#' [cluster_leiden()] for other community detection methods. +#' [cluster_fast_greedy()], [cluster_walktrap()], [cluster_spinglass()], +#' [cluster_louvain()] and [cluster_leiden()] for other community detection methods. #' @references Raghavan, U.N. and Albert, R. and Kumara, S.: Near linear time #' algorithm to detect community structures in large-scale networks. *Phys #' Rev E* 76, 036106. (2007) @@ -2746,54 +2576,43 @@ cluster_label_prop0 <- function( #' Finding community structure by multi-level optimization of modularity #' -#' This function implements the multi-level modularity optimization algorithm -#' for finding community structure, see references below. It is based on the -#' modularity measure and a hierarchical approach. +#' This function implements the multi-level modularity optimization algorithm for finding community structure, see references below. +#' It is based on the modularity measure and a hierarchical approach. #' -#' This function implements the multi-level modularity optimization algorithm -#' for finding community structure, see VD Blondel, J-L Guillaume, R Lambiotte -#' and E Lefebvre: Fast unfolding of community hierarchies in large networks, +#' This function implements the multi-level modularity optimization algorithm for finding community structure, see VD Blondel, +#' J-L Guillaume, R Lambiotte and E Lefebvre: Fast unfolding of community hierarchies in large networks, #' for the details. #' #' It is based on the modularity measure and a hierarchical approach. -#' Initially, each vertex is assigned to a community on its own. In every step, -#' vertices are re-assigned to communities in a local, greedy way: each vertex -#' is moved to the community with which it achieves the highest contribution to -#' modularity. When no vertices can be reassigned, each community is considered -#' a vertex on its own, and the process starts again with the merged -#' communities. The process stops when there is only a single vertex left or -#' when the modularity cannot be increased any more in a step. Since igraph 1.3, -#' vertices are processed in a random order. +#' Initially, each vertex is assigned to a community on its own. +#' In every step, vertices are re-assigned to communities in a local, greedy way: +#' each vertex is moved to the community with which it achieves the highest contribution to modularity. +#' When no vertices can be reassigned, each community is considered a vertex on its own, +#' and the process starts again with the merged communities. +#' The process stops when there is only a single vertex left or when the modularity cannot be increased any more in a step. +#' Since igraph 1.3, vertices are processed in a random order. #' #' This function was contributed by Tom Gregorovic. #' -#' @param graph The input graph. It must be undirected. +#' @param graph The input graph. +#' It must be undirected. #' @inheritParams rlang::args_dots_empty -#' @param weights The weights of the edges. It must be a positive numeric vector, -#' `NULL` or `NA`. If it is `NULL` and the input graph has a -#' \sQuote{weight} edge attribute, then that attribute will be used. If -#' `NULL` and no such attribute is present, then the edges will have equal -#' weights. Set this to `NA` if the graph was a \sQuote{weight} edge -#' attribute, but you don't want to use it for community detection. A larger -#' edge weight means a stronger connection for this function. -#' @param resolution Optional resolution parameter that allows the user to -#' adjust the resolution parameter of the modularity function that the algorithm -#' uses internally. Lower values typically yield fewer, larger clusters. The -#' original definition of modularity is recovered when the resolution parameter -#' is set to 1. -#' @return `cluster_louvain()` returns a [communities()] -#' object, please see the [communities()] manual page for details. +#' @param weights The weights of the edges. +#' It must be a positive numeric vector, `NULL` or `NA`. +#' If it is `NULL` and the input graph has a \sQuote{weight} edge attribute, then that attribute will be used. +#' If `NULL` and no such attribute is present, then the edges will have equal weights. +#' Set this to `NA` if the graph was a \sQuote{weight} edge attribute, but you don't want to use it for community detection. +#' A larger edge weight means a stronger connection for this function. +#' @param resolution Optional resolution parameter that allows the user to adjust the resolution parameter of the modularity function that the algorithm uses internally. +#' Lower values typically yield fewer, larger clusters. +#' The original definition of modularity is recovered when the resolution parameter is set to 1. +#' @return `cluster_louvain()` returns a [communities()] object, please see the [communities()] manual page for details. #' @author Tom Gregorovic, Tamas Nepusz \email{ntamas@@gmail.com} #' @seealso See [communities()] for extracting the membership, #' modularity scores, etc. from the results. #' -#' Other community detection algorithms: [cluster_walktrap()], -#' [cluster_spinglass()], -#' [cluster_leading_eigen()], -#' [cluster_edge_betweenness()], -#' [cluster_fast_greedy()], -#' [cluster_label_prop()] -#' [cluster_leiden()] +#' Other community detection algorithms: [cluster_walktrap()], [cluster_spinglass()], [cluster_leading_eigen()], +#' [cluster_edge_betweenness()], [cluster_fast_greedy()], [cluster_label_prop()] [cluster_leiden()] #' @references Vincent D. Blondel, Jean-Loup Guillaume, Renaud Lambiotte, #' Etienne Lefebvre: Fast unfolding of communities in large networks. J. Stat. #' Mech. (2008) P10008 @@ -2883,21 +2702,17 @@ cluster_louvain <- function( #' Optimal community structure #' -#' This function calculates the optimal community structure of a graph, by -#' maximizing the modularity measure over all possible partitions. +#' This function calculates the optimal community structure of a graph, by maximizing the modularity measure over all possible partitions. #' -#' This function calculates the optimal community structure for a graph, in -#' terms of maximal modularity score. +#' This function calculates the optimal community structure for a graph, in terms of maximal modularity score. #' -#' The calculation is done by transforming the modularity maximization into an -#' integer programming problem, and then calling the GLPK library to solve -#' that. Please the reference below for details. +#' The calculation is done by transforming the modularity maximization into an integer programming problem, +#' and then calling the GLPK library to solve that. +#' Please the reference below for details. #' -#' Note that modularity optimization is an NP-complete problem, and all known -#' algorithms for it have exponential time complexity. This means that you -#' probably don't want to run this function on larger graphs. Graphs with up to -#' fifty vertices should be fine, graphs with a couple of hundred vertices -#' might be possible. +#' Note that modularity optimization is an NP-complete problem, and all known algorithms for it have exponential time complexity. +#' This means that you probably don't want to run this function on larger graphs. +#' Graphs with up to fifty vertices should be fine, graphs with a couple of hundred vertices might be possible. #' #' @section Examples: #' \preformatted{ @@ -2920,21 +2735,20 @@ cluster_louvain <- function( #' print(modularity(fc)) #' } #' -#' @param graph The input graph. It may be undirected or directed. +#' @param graph The input graph. +#' It may be undirected or directed. #' @inheritParams rlang::args_dots_empty -#' @param weights The weights of the edges. It must be a positive numeric -#' vector, `NULL` or `NA`. If it is `NULL` and the input graph has a -#' \sQuote{weight} edge attribute, then that attribute will be used. If -#' `NULL` and no such attribute is present, then the edges will have equal -#' weights. Set this to `NA` if the graph was a \sQuote{weight} edge -#' attribute, but you don't want to use it for community detection. A larger -#' edge weight means a stronger connection for this function. +#' @param weights The weights of the edges. +#' It must be a positive numeric vector, `NULL` or `NA`. +#' If it is `NULL` and the input graph has a \sQuote{weight} edge attribute, then that attribute will be used. +#' If `NULL` and no such attribute is present, then the edges will have equal weights. +#' Set this to `NA` if the graph was a \sQuote{weight} edge attribute, but you don't want to use it for community detection. +#' A larger edge weight means a stronger connection for this function. #' @return `cluster_optimal()` returns a [communities()] object, #' please see the [communities()] manual page for details. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso [communities()] for the documentation of the result, -#' [modularity()]. See also [cluster_fast_greedy()] for a -#' fast greedy optimizer. +#' @seealso [communities()] for the documentation of the result, [modularity()]. +#' See also [cluster_fast_greedy()] for a fast greedy optimizer. #' @references Ulrik Brandes, Daniel Delling, Marco Gaertler, Robert Gorke, #' Martin Hoefer, Zoran Nikoloski, Dorothea Wagner: On Modularity Clustering, #' *IEEE Transactions on Knowledge and Data Engineering* 20(2):172-188, @@ -3013,34 +2827,31 @@ cluster_optimal <- function( #' Infomap community finding #' -#' Find community structure that minimizes the expected description length of a -#' random walker trajectory. If the graph is directed, edge directions will -#' be taken into account. +#' Find community structure that minimizes the expected description length of a random walker trajectory. +#' If the graph is directed, edge directions will be taken into account. #' #' Please see the details of this method in the references given below. #' -#' @param graph The input graph. Edge directions will be taken into account. +#' @param graph The input graph. +#' Edge directions will be taken into account. #' @inheritParams rlang::args_dots_empty #' @param e.weights Numeric vector of edge weights. -#' The length must match the number of edges in the graph. By default (`NULL`) the -#' \sQuote{`weight`} edge attribute is used as weights. If it is not -#' present, then all edges are considered to have the same weight. +#' The length must match the number of edges in the graph. +#' By default (`NULL`) the \sQuote{`weight`} edge attribute is used as weights. +#' If it is not present, then all edges are considered to have the same weight. #' Larger edge weights correspond to stronger connections. -#' @param v.weights Numeric vector of vertex -#' weights. The length must match the number of vertices in the graph. By -#' default (`NULL`) the \sQuote{`weight`} vertex attribute is used as weights. If -#' it is not present, then all vertices are considered to have the same weight. -#' A larger vertex weight means a larger probability that the random surfer -#' jumps to that vertex. -#' @param nb.trials The number of attempts to partition the network (can be any -#' integer value equal or larger than 1). -#' @param modularity Logical, whether to calculate the modularity score -#' of the detected community structure. +#' @param v.weights Numeric vector of vertex weights. +#' The length must match the number of vertices in the graph. +#' By default (`NULL`) the \sQuote{`weight`} vertex attribute is used as weights. +#' If it is not present, then all vertices are considered to have the same weight. +#' A larger vertex weight means a larger probability that the random surfer jumps to that vertex. +#' @param nb.trials The number of attempts to partition the network (can be any integer value equal or larger than 1). +#' @param modularity Logical, whether to calculate the modularity score of the detected community structure. #' @return `cluster_infomap()` returns a [communities()] object, #' please see the [communities()] manual page for details. #' @author Martin Rosvall wrote the original C++ code. This was ported to -#' be more igraph-like by Emmanuel Navarro. The R interface and -#' some cosmetics was done by Gabor Csardi \email{csardi.gabor@@gmail.com}. +#' be more igraph-like by Emmanuel Navarro. +#' The R interface and some cosmetics was done by Gabor Csardi \email{csardi.gabor@@gmail.com}. #' @seealso Other community finding methods and [communities()]. #' @references The original paper: M. Rosvall and C. T. Bergstrom, Maps of #' information flow reveal community structure in complex networks, *PNAS* @@ -3163,19 +2974,18 @@ plot_dendrogram <- function(x, mode = NULL, ...) { #' #' Plot a hierarchical community structure as a dendrogram. #' -#' `plot_dendrogram()` supports three different plotting functions, selected via -#' the `mode` argument. By default the plotting function is taken from the -#' `dend.plot.type` igraph option, and it has for possible values: +#' `plot_dendrogram()` supports three different plotting functions, selected via the `mode` argument. +#' By default the plotting function is taken from the `dend.plot.type` igraph option, and it has for possible values: #' \itemize{ \item `auto` Choose automatically between the plotting -#' functions. As `plot.phylo` is the most sophisticated, that is choosen, -#' whenever the `ape` package is available. Otherwise `plot.hclust` -#' is used. \item `phylo` Use `plot.phylo` from the `ape` -#' package. \item `hclust` Use `plot.hclust` from the `stats` -#' package. \item `dendrogram` Use `plot.dendrogram` from the -#' `stats` package. } -#' -#' The different plotting functions take different sets of arguments. When -#' using `plot.phylo` (`mode="phylo"`), we have the following syntax: +#' functions. +#' As `plot.phylo` is the most sophisticated, that is choosen, whenever the `ape` package is available. +#' Otherwise `plot.hclust` is used. +#' \item `phylo` Use `plot.phylo` from the `ape` package. +#' \item `hclust` Use `plot.hclust` from the `stats` package. +#' \item `dendrogram` Use `plot.dendrogram` from the `stats` package. } +#' +#' The different plotting functions take different sets of arguments. +#' When using `plot.phylo` (`mode="phylo"`), we have the following syntax: #' \preformatted{ #' plot_dendrogram(x, mode="phylo", colbar = palette(), #' edge.color = NULL, use.edge.length = FALSE, \dots) @@ -3192,24 +3002,16 @@ plot_dendrogram <- function(x, mode = NULL, ...) { #' hang = 0.01, ann = FALSE, main = "", sub = "", xlab = "", #' ylab = "", \dots) #' } The extra arguments not documented above: \itemize{ -#' \item `rect` A numeric scalar, the number of groups to mark on -#' the dendrogram. The dendrogram is cut into exactly `rect` -#' groups and they are marked via the `rect.hclust` command. Set -#' this to zero if you don't want to mark any groups. -#' \item `colbar` The colors of the rectangles that mark the -#' vertex groups via the `rect` argument. -#' \item `hang` Where to put the leaf nodes, this corresponds to the -#' `hang` argument of `plot.hclust`. -#' \item `ann` Whether to annotate the plot, the `ann` -#' argument of `plot.hclust`. -#' \item `main` The main title of the plot, the `main` argument -#' of `plot.hclust`. -#' \item `sub` The sub-title of the plot, the `sub` argument of -#' `plot.hclust`. -#' \item `xlab` The label on the horizontal axis, passed to -#' `plot.hclust`. -#' \item `ylab` The label on the vertical axis, passed to -#' `plot.hclust`. +#' \item `rect` A numeric scalar, the number of groups to mark on the dendrogram. +#' The dendrogram is cut into exactly `rect` groups and they are marked via the `rect.hclust` command. +#' Set this to zero if you don't want to mark any groups. +#' \item `colbar` The colors of the rectangles that mark the vertex groups via the `rect` argument. +#' \item `hang` Where to put the leaf nodes, this corresponds to the `hang` argument of `plot.hclust`. +#' \item `ann` Whether to annotate the plot, the `ann` argument of `plot.hclust`. +#' \item `main` The main title of the plot, the `main` argument of `plot.hclust`. +#' \item `sub` The sub-title of the plot, the `sub` argument of `plot.hclust`. +#' \item `xlab` The label on the horizontal axis, passed to `plot.hclust`. +#' \item `ylab` The label on the vertical axis, passed to `plot.hclust`. #' \item `dots` Attitional arguments to pass to `plot.hclust`. #' } #' @@ -3218,14 +3020,13 @@ plot_dendrogram <- function(x, mode = NULL, ...) { #' plot_dendrogram(x, \dots) #' } The extra arguments are simply passed to [as.dendrogram()]. #' -#' @param x An object containing the community structure of a graph. See -#' [communities()] for details. -#' @param mode Which dendrogram plotting function to use. See details below. +#' @param x An object containing the community structure of a graph. +#' See [communities()] for details. +#' @param mode Which dendrogram plotting function to use. +#' See details below. #' The default `NULL` uses the `dend.plot.type` igraph option. -#' @param \dots Additional arguments to supply to the dendrogram plotting -#' function. -#' @param use.modularity Logical, whether to use the modularity values -#' to define the height of the branches. +#' @param \dots Additional arguments to supply to the dendrogram plotting function. +#' @param use.modularity Logical, whether to use the modularity values to define the height of the branches. #' @param palette The color palette to use for colored plots. #' @return Returns whatever the return value was from the plotting function, #' `plot.phylo`, `plot.dendrogram` or `plot.hclust`. @@ -3365,20 +3166,16 @@ dendPlotPhylo <- function( #' #' #' @aliases compare.communities compare.membership -#' @param comm1 A [communities()] object containing a community -#' structure; or a numeric vector, the membership vector of the first community -#' structure. The membership vector should contain the community ID of each -#' vertex, the numbering of the communities starts with one. -#' @param comm2 A [communities()] object containing a community -#' structure; or a numeric vector, the membership vector of the second -#' community structure, in the same format as for the previous argument. -#' @param method Character scalar, the comparison method to use. Possible -#' values: \sQuote{vi} is the variation of information (VI) metric of Meila -#' (2003), \sQuote{nmi} is the normalized mutual information measure proposed -#' by Danon et al. (2005), \sQuote{split.join} is the split-join distance of -#' can Dongen (2000), \sQuote{rand} is the Rand index of Rand (1971), -#' \sQuote{adjusted.rand} is the adjusted Rand index by Hubert and Arabie -#' (1985). +#' @param comm1 A [communities()] object containing a community structure; or a numeric vector, +#' the membership vector of the first community structure. +#' The membership vector should contain the community ID of each vertex, the numbering of the communities starts with one. +#' @param comm2 A [communities()] object containing a community structure; or a numeric vector, +#' the membership vector of the second community structure, in the same format as for the previous argument. +#' @param method Character scalar, the comparison method to use. +#' Possible values: \sQuote{vi} is the variation of information (VI) metric of Meila (2003), +#' \sQuote{nmi} is the normalized mutual information measure proposed by Danon et al. (2005), +#' \sQuote{split.join} is the split-join distance of can Dongen (2000), \sQuote{rand} is the Rand index of Rand (1971), +#' \sQuote{adjusted.rand} is the adjusted Rand index by Hubert and Arabie (1985). #' @return A real number. #' @author Tamas Nepusz \email{ntamas@@gmail.com} #' @references Meila M: Comparing clusterings by the variation of information. @@ -3495,24 +3292,17 @@ i_compare <- function( #' Split-join distance of two community structures #' -#' The split-join distance between partitions A and B is the sum of the -#' projection distance of A from B and the projection distance of B from -#' A. The projection distance is an asymmetric measure and it is defined as -#' follows: -#' -#' First, each set in partition A is evaluated against all sets in -#' partition B. For each set in partition A, the best matching set in -#' partition B is found and the overlap size is calculated. (Matching is -#' quantified by the size of the overlap between the two sets). Then, the -#' maximal overlap sizes for each set in A are summed together and -#' subtracted from the number of elements in A. -#' -#' The split-join distance will be returned as two numbers, the first is -#' the projection distance of the first partition from the -#' second, while the second number is the projection distance of the second -#' partition from the first. This makes it easier to detect whether a -#' partition is a subpartition of the other, since in this case, the -#' corresponding distance will be zero. +#' The split-join distance between partitions A and B is the sum of the projection distance of A from B and the projection distance of B from A. The projection distance is an asymmetric measure and it is defined as follows: +#' +#' First, each set in partition A is evaluated against all sets in partition B. +#' For each set in partition A, the best matching set in partition B is found and the overlap size is calculated. +#' (Matching is quantified by the size of the overlap between the two sets). +#' Then, the maximal overlap sizes for each set in A are summed together and subtracted from the number of elements in A. +#' +#' The split-join distance will be returned as two numbers, the first is the projection distance of the first partition from the second, +#' while the second number is the projection distance of the second partition from the first. +#' This makes it easier to detect whether a partition is a subpartition of the other, since in this case, +#' the corresponding distance will be zero. #' #' @param comm1 The first community structure. #' @param comm2 The second community structure. @@ -3546,23 +3336,21 @@ split_join_distance <- function(comm1, comm2) { #' Groups of a vertex partitioning #' -#' Create a list of vertex groups from some graph clustering or community -#' structure. +#' Create a list of vertex groups from some graph clustering or community structure. #' -#' Currently two methods are defined for this function. The default method -#' works on the output of [components()]. (In fact it works on any -#' object that is a list with an entry called `membership`.) +#' Currently two methods are defined for this function. +#' The default method works on the output of [components()]. +#' (In fact it works on any object that is a list with an entry called `membership`.) #' #' The second method works on [communities()] objects. #' #' @aliases groups.default groups.communities -#' @param x Some object that represents a grouping of the vertices. See details -#' below. -#' @return A named list of numeric or character vectors. The names are just -#' numbers that refer to the groups. The vectors themselves are numeric or -#' symbolic vertex IDs. -#' @seealso [components()] and the various community finding -#' functions. +#' @param x Some object that represents a grouping of the vertices. +#' See details below. +#' @return A named list of numeric or character vectors. +#' The names are just numbers that refer to the groups. +#' The vectors themselves are numeric or symbolic vertex IDs. +#' @seealso [components()] and the various community finding functions. #' @examples #' g <- make_graph("Zachary") #' fgc <- cluster_fast_greedy(g) @@ -3616,20 +3404,18 @@ communities <- groups.communities #' Contract several vertices into a single one #' -#' This function creates a new graph, by merging several vertices into one. The -#' vertices in the new graph correspond to sets of vertices in the input graph. +#' This function creates a new graph, by merging several vertices into one. +#' The vertices in the new graph correspond to sets of vertices in the input graph. #' -#' The attributes of the graph are kept. Graph and edge attributes are -#' unchanged, vertex attributes are combined, according to the -#' `vertex.attr.comb` parameter. +#' The attributes of the graph are kept. +#' Graph and edge attributes are unchanged, vertex attributes are combined, according to the `vertex.attr.comb` 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 -#' the new graph. Please see [attribute.combination()] for details. The -#' default `NULL` uses the `vertex.attr.comb` igraph option. +#' @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 the new graph. +#' Please see [attribute.combination()] for details. +#' The default `NULL` uses the `vertex.attr.comb` igraph option. #' @return A new graph object. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @keywords graphs @@ -3672,22 +3458,19 @@ contract <- function( #' @description #' `r lifecycle::badge("experimental")` #' -#' This function partitions the vertices of a graph based on a set of generator -#' vertices. Each vertex is assigned to the generator vertex from (or to) which -#' it is closest. +#' This function partitions the vertices of a graph based on a set of generator vertices. +#' Each vertex is assigned to the generator vertex from (or to) which it is closest. #' #' [groups()] may be used on the output of this function. #' #' @param graph The graph to partition into Voronoi cells. #' @param generators The generator vertices of the Voronoi cells. -#' @param mode Character string. In directed graphs, whether to compute -#' distances from generator vertices to other vertices (`"out"`), to -#' generator vertices from other vertices (`"in"`), or ignore edge -#' directions entirely (`"all"`). Ignored in undirected graphs. -#' @param tiebreaker Character string that specifies what to do when a vertex -#' is at the same distance from multiple generators. `"random"` assigns -#' a minimal-distance generator randomly, `"first"` takes the first one, -#' and `"last"` takes the last one. +#' @param mode Character string. +#' In directed graphs, whether to compute distances from generator vertices to other vertices (`"out"`), +#' to generator vertices from other vertices (`"in"`), or ignore edge directions entirely (`"all"`). +#' Ignored in undirected graphs. +#' @param tiebreaker Character string that specifies what to do when a vertex is at the same distance from multiple generators. +#' `"random"` assigns a minimal-distance generator randomly, `"first"` takes the first one, and `"last"` takes the last one. #' @inheritParams distances #' @inheritParams rlang::args_dots_empty #' @return A named list with two components: diff --git a/R/components.R b/R/components.R index bd11a592761..c8c2e99350c 100644 --- a/R/components.R +++ b/R/components.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `no.clusters()` was renamed to [count_components()] to create a more -#' consistent API. +#' `no.clusters()` was renamed to [count_components()] to create a more consistent API. #' @inheritParams count_components #' @keywords internal #' @export @@ -19,8 +18,7 @@ no.clusters <- function(graph, mode = c("weak", "strong")) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `decompose.graph()` was renamed to [decompose()] to create a more -#' consistent API. +#' `decompose.graph()` was renamed to [decompose()] to create a more consistent API. #' @inheritParams decompose #' @keywords internal #' @export @@ -45,8 +43,7 @@ decompose.graph <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `cluster.distribution()` was renamed to [component_distribution()] to create a more -#' consistent API. +#' `cluster.distribution()` was renamed to [component_distribution()] to create a more consistent API. #' @inheritParams component_distribution #' @keywords internal #' @export @@ -75,8 +72,7 @@ cluster.distribution <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `biconnected.components()` was renamed to [biconnected_components()] to create a more -#' consistent API. +#' `biconnected.components()` was renamed to [biconnected_components()] to create a more consistent API. #' @inheritParams biconnected_components #' @keywords internal #' @export @@ -95,8 +91,7 @@ biconnected.components <- function(graph) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `articulation.points()` was renamed to [articulation_points()] to create a more -#' consistent API. +#' `articulation.points()` was renamed to [articulation_points()] to create a more consistent API. #' @inheritParams articulation_points #' @keywords internal #' @export @@ -135,10 +130,9 @@ articulation.points <- function(graph) { ################################################################### #' @rdname components -#' @param cumulative Logical, if TRUE the cumulative distirubution (relative -#' frequency) is calculated. -#' @param mul.size Logical. If TRUE the relative frequencies will be multiplied -#' by the cluster sizes. +#' @param cumulative Logical, if TRUE the cumulative distirubution (relative frequency) is calculated. +#' @param mul.size Logical. +#' If TRUE the relative frequencies will be multiplied by the cluster sizes. #' @family components #' @export #' @importFrom graphics hist @@ -172,17 +166,14 @@ component_distribution <- function( #' #' @param graph The original graph. #' @inheritParams rlang::args_dots_empty -#' @param mode Character constant giving the type of the components, wither -#' `weak` for weakly connected components or `strong` for strongly -#' connected components. -#' @param max.comps The maximum number of components to return. The first -#' `max.comps` components will be returned (which hold at least -#' `min.vertices` vertices, see the next parameter), the others will be -#' ignored. Supply `NA` here if you don't want to limit the number of -#' components. -#' @param min.vertices The minimum number of vertices a component should -#' contain in order to place it in the result list. E.g. supply 2 here to ignore -#' isolate vertices. +#' @param mode Character constant giving the type of the components, +#' wither `weak` for weakly connected components or `strong` for strongly connected components. +#' @param max.comps The maximum number of components to return. +#' The first `max.comps` components will be returned (which hold at least `min.vertices` vertices, see the next parameter), +#' the others will be ignored. +#' Supply `NA` here if you don't want to limit the number of components. +#' @param min.vertices The minimum number of vertices a component should contain in order to place it in the result list. +#' E.g. supply 2 here to ignore isolate vertices. #' @return A list of graph objects. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @seealso [is_connected()] to decide whether a graph is connected, @@ -265,20 +256,17 @@ decompose <- function( #' `articulation_points()` finds the articulation points (or cut vertices) # " of a graph, while \code{bridges()} finds the bridges (or cut-edges) of a graph. #' -#' Articulation points or cut vertices are vertices whose removal increases the -#' number of connected components in a graph. Similarly, bridges or cut-edges -#' are edges whose removal increases the number of connected components in a -#' graph. If the original graph was connected, then the removal of a single -#' articulation point or a single bridge makes it disconnected. If a graph -#' contains no articulation points, then its vertex connectivity is at least +#' Articulation points or cut vertices are vertices whose removal increases the number of connected components in a graph. +#' Similarly, bridges or cut-edges are edges whose removal increases the number of connected components in a graph. +#' If the original graph was connected, then the removal of a single articulation point or a single bridge makes it disconnected. +#' If a graph contains no articulation points, then its vertex connectivity is at least # " two. If a graph contains no bridges, then its edge connectivity is at least #' two. #' -#' @param graph The input graph. It is treated as an undirected graph, even if -#' it is directed. -#' @return For `articulation_points()`, a numeric vector giving the vertex -#' IDs of the articulation points of the input graph. For `bridges()`, a -#' numeric vector giving the edge IDs of the bridges of the input graph. +#' @param graph The input graph. +#' It is treated as an undirected graph, even if it is directed. +#' @return For `articulation_points()`, a numeric vector giving the vertex IDs of the articulation points of the input graph. +#' For `bridges()`, a numeric vector giving the edge IDs of the bridges of the input graph. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @seealso [biconnected_components()], [components()], #' [is_connected()], [vertex_connectivity()], @@ -315,17 +303,15 @@ bridges <- function(graph) { #' #' Finding the biconnected components of a graph #' -#' A graph is biconnected if the removal of any single vertex (and its adjacent -#' edges) does not disconnect it. +#' A graph is biconnected if the removal of any single vertex (and its adjacent edges) does not disconnect it. #' #' A biconnected component of a graph is a maximal biconnected subgraph of it. -#' The biconnected components of a graph can be given by the partition of its -#' edges: every edge is a member of exactly one biconnected component. Note -#' that this is not true for vertices: the same vertex can be part of many -#' biconnected components. +#' The biconnected components of a graph can be given by the partition of its edges: +#' every edge is a member of exactly one biconnected component. +#' Note that this is not true for vertices: the same vertex can be part of many biconnected components. #' -#' @param graph The input graph. It is treated as an undirected graph, even if -#' it is directed. +#' @param graph The input graph. +#' It is treated as an undirected graph, even if it is directed. #' @return A named list with three components: #' \describe{ #' \item{no}{ @@ -409,15 +395,14 @@ biconnected_components <- function(graph) { #' Tests whether a graph is biconnected. #' #' @details -#' A graph is biconnected if the removal of any single vertex (and its adjacent -#' edges) does not disconnect it. +#' A graph is biconnected if the removal of any single vertex (and its adjacent edges) does not disconnect it. #' #' igraph does not consider single-vertex graphs biconnected. #' -#' Note that some authors do not consider the graph consisting of -#' two connected vertices as biconnected, however, igraph does. +#' Note that some authors do not consider the graph consisting of two connected vertices as biconnected, however, igraph does. #' -#' @param graph The input graph. Edge directions are ignored. +#' @param graph The input graph. +#' Edge directions are ignored. #' @return Logical, `TRUE` if the graph is biconnected. #' @seealso [articulation_points()], [biconnected_components()], #' [is_connected()], [vertex_connectivity()] diff --git a/R/console.R b/R/console.R index 6c8f6bb208e..595baeb2c7d 100644 --- a/R/console.R +++ b/R/console.R @@ -4,8 +4,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `igraph.console()` was renamed to [console()] to create a more -#' consistent API. +#' `igraph.console()` was renamed to [console()] to create a more consistent API. #' #' @keywords internal #' @export @@ -38,16 +37,13 @@ igraph.console <- function() { #' The igraph console #' -#' The igraph console is a GUI window that shows what the currently running -#' igraph function is doing. +#' The igraph console is a GUI window that shows what the currently running igraph function is doing. #' #' The console can be started by calling the `console()` function. #' Then it stays open, until the user closes it. #' -#' Another way to start it to set the `verbose` igraph option to -#' \dQuote{tkconsole} via `igraph_options()`. Then the console (re)opens -#' each time an igraph function supporting it starts; to close it, set the -#' `verbose` option to another value. +#' Another way to start it to set the `verbose` igraph option to \dQuote{tkconsole} via `igraph_options()`. +#' Then the console (re)opens each time an igraph function supporting it starts; to close it, set the `verbose` option to another value. #' #' The console is written in Tcl/Tk and required the `tcltk` package. #' diff --git a/R/conversion.R b/R/conversion.R index b5d16a311ab..3b33b5f9c2f 100644 --- a/R/conversion.R +++ b/R/conversion.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `igraph.to.graphNEL()` was renamed to [as_graphnel()] to create a more -#' consistent API. +#' `igraph.to.graphNEL()` was renamed to [as_graphnel()] to create a more consistent API. #' @inheritParams as_graphnel #' @keywords internal #' @export @@ -19,8 +18,7 @@ igraph.to.graphNEL <- function(graph) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `igraph.from.graphNEL()` was renamed to [graph_from_graphnel()] to create a more -#' consistent API. +#' `igraph.from.graphNEL()` was renamed to [graph_from_graphnel()] to create a more consistent API. #' @inheritParams graph_from_graphnel #' @keywords internal #' @export @@ -49,8 +47,7 @@ igraph.from.graphNEL <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.adjlist()` was renamed to [graph_from_adj_list()] to create a more -#' consistent API. +#' `graph.adjlist()` was renamed to [graph_from_adj_list()] to create a more consistent API. #' @inheritParams graph_from_adj_list #' @keywords internal #' @export @@ -69,8 +66,7 @@ graph.adjlist <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `get.incidence()` was renamed to [as_biadjacency_matrix()] to create a more -#' consistent API. +#' `get.incidence()` was renamed to [as_biadjacency_matrix()] to create a more consistent API. #' @inheritParams as_biadjacency_matrix #' @keywords internal #' @export @@ -101,8 +97,7 @@ get.incidence <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `get.edgelist()` was renamed to [as_edgelist()] to create a more -#' consistent API. +#' `get.edgelist()` was renamed to [as_edgelist()] to create a more consistent API. #' @inheritParams as_edgelist #' @keywords internal #' @export @@ -117,8 +112,7 @@ get.edgelist <- function(graph, names = TRUE) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `get.data.frame()` was renamed to [as_data_frame()] to create a more -#' consistent API. +#' `get.data.frame()` was renamed to [as_data_frame()] to create a more consistent API. #' @inheritParams as_data_frame #' @keywords internal #' @export @@ -133,8 +127,7 @@ get.data.frame <- function(x, what = c("edges", "vertices", "both")) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `get.adjacency()` was renamed to [as_adjacency_matrix()] to create a more -#' consistent API. +#' `get.adjacency()` was renamed to [as_adjacency_matrix()] to create a more consistent API. #' @inheritParams as_adjacency_matrix #' @keywords internal #' @export @@ -163,8 +156,7 @@ get.adjacency <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `get.adjlist()` was renamed to [as_adj_list()] to create a more -#' consistent API. +#' `get.adjlist()` was renamed to [as_adj_list()] to create a more consistent API. #' @inheritParams as_adj_list #' @keywords internal #' @export @@ -184,8 +176,7 @@ get.adjlist <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `get.adjedgelist()` was renamed to [as_adj_edge_list()] to create a more -#' consistent API. +#' `get.adjedgelist()` was renamed to [as_adj_edge_list()] to create a more consistent API. #' @inheritParams as_adj_edge_list #' @keywords internal #' @export @@ -248,14 +239,12 @@ resolve_edge_weights <- function( }, user_env = user_env ) - # `attr` and `weights` spell "unweighted" differently, so the two cannot - # simply be assigned across. `attr = NULL` was the documented way to ask - # for a plain 0/1 matrix -- "If `NULL` a traditional adjacency matrix is - # returned" -- while `weights = NULL` means the opposite: use the `weight` - # edge attribute if the graph has one. Passing it straight through - # therefore inverts what the caller asked for, silently and without a - # warning, for every call that spelled it out. `NA` is how the new - # vocabulary says "unweighted". + # `attr` and `weights` spell "unweighted" differently, so the two cannot simply be assigned across. + # `attr = NULL` was the documented way to ask for a plain 0/1 matrix -- "If `NULL` a traditional adjacency matrix is returned" -- + # while `weights = NULL` means the opposite: use the `weight` edge attribute if the graph has one. + # Passing it straight through therefore inverts what the caller asked for, silently and without a warning, for every call + # that spelled it out. + # `NA` is how the new vocabulary says "unweighted". # # `lifecycle::is_present()` is true for an explicit `NULL` -- only the # `deprecated()` sentinel counts as absent -- so this branch really does @@ -400,47 +389,38 @@ get.adjacency.sparse <- function( #' Convert a graph to an adjacency matrix #' -#' Sometimes it is useful to work with a standard representation of a -#' graph, like an adjacency matrix. +#' Sometimes it is useful to work with a standard representation of a graph, like an adjacency matrix. #' -#' `as_adjacency_matrix()` returns the adjacency matrix of a graph, a -#' regular matrix if `sparse` is `FALSE`, or a sparse matrix, as -#' defined in the \sQuote{`Matrix`} package, if `sparse` if -#' `TRUE`. +#' `as_adjacency_matrix()` returns the adjacency matrix of a graph, a regular matrix if `sparse` is `FALSE`, or a sparse matrix, +#' as defined in the \sQuote{`Matrix`} package, if `sparse` if `TRUE`. #' #' @param graph The graph to convert. #' @param type Gives how to create the adjacency matrix for undirected graphs. -#' It is ignored for directed graphs. Possible values: `upper`: the upper -#' right triangle of the matrix is used, `lower`: the lower left triangle -#' of the matrix is used. `both`: the whole matrix is used, a symmetric -#' matrix is returned. +#' It is ignored for directed graphs. +#' Possible values: `upper`: the upper right triangle of the matrix is used, `lower`: the lower left triangle of the matrix is used. +#' `both`: the whole matrix is used, a symmetric matrix is returned. #' @inheritParams rlang::args_dots_empty #' @param weights One of the following: #' \itemize{ -#' \item `NULL` (default): use the `weight` edge attribute if the graph has -#' one, otherwise return a traditional (unweighted) adjacency matrix. +#' \item `NULL` (default): use the `weight` edge attribute if the graph has one, +#' otherwise return a traditional (unweighted) adjacency matrix. #' \item `NA`: explicitly unweighted, ignoring any `weight` edge attribute. -#' \item A numeric or logical vector of length [ecount()]: use these values -#' directly as edge weights. -#' \item A character scalar: the name of an edge attribute whose values are -#' used as weights. The attribute must be numeric or logical. +#' \item A numeric or logical vector of length [ecount()]: use these values directly as edge weights. +#' \item A character scalar: the name of an edge attribute whose values are used as weights. +#' The attribute must be numeric or logical. #' } -#' If multiple edges share endpoints, the value of an arbitrarily chosen edge -#' is included in the matrix. -#' @param attr `r lifecycle::badge("deprecated")` Use `weights` instead. A -#' character edge attribute name is forwarded to `weights` unchanged; `NULL` -#' becomes `weights = NA`, since `attr = NULL` asked for a traditional -#' unweighted matrix while `weights = NULL` picks the `weight` attribute up. +#' If multiple edges share endpoints, the value of an arbitrarily chosen edge is included in the matrix. +#' @param attr `r lifecycle::badge("deprecated")` Use `weights` instead. +#' A character edge attribute name is forwarded to `weights` unchanged; `NULL` becomes `weights = NA`, +#' since `attr = NULL` asked for a traditional unweighted matrix while `weights = NULL` picks the `weight` attribute up. #' @param edges `r lifecycle::badge("deprecated")` Logical, whether to return the edge IDs in the matrix. #' For non-existant edges zero is returned. -#' @param names Logical, whether to assign row and column names -#' to the matrix. These are only assigned if the `name` vertex attribute -#' is present in the graph. -#' @param sparse Logical, whether to create a sparse matrix. The -#' \sQuote{`Matrix`} package must be installed for creating sparse -#' matrices. The default `NULL` uses the `sparsematrices` igraph option. -#' @return A `vcount(graph)` by `vcount(graph)` (usually) numeric -#' matrix. +#' @param names Logical, whether to assign row and column names to the matrix. +#' These are only assigned if the `name` vertex attribute is present in the graph. +#' @param sparse Logical, whether to create a sparse matrix. +#' The \sQuote{`Matrix`} package must be installed for creating sparse matrices. +#' The default `NULL` uses the `sparsematrices` igraph option. +#' @return A `vcount(graph)` by `vcount(graph)` (usually) numeric matrix. #' #' @seealso [graph_from_adjacency_matrix()], [read_graph()] #' @examples @@ -539,9 +519,7 @@ as_adjacency_matrix <- function( #' Convert a graph to an adjacency matrix #' -#' `r lifecycle::badge("deprecated")` -#' We plan to remove `as_adj()` in favor of the more explicitly named -#' `as_adjacency_matrix()` so please use `as_adjacency_matrix()` instead. +#' `r lifecycle::badge("deprecated")` We plan to remove `as_adj()` in favor of the more explicitly named `as_adjacency_matrix()` so please use `as_adjacency_matrix()` instead. #' #' @export #' @inheritParams as_adjacency_matrix @@ -569,16 +547,14 @@ as_adj <- function( } #' Convert a graph to an edge list #' -#' Sometimes it is useful to work with a standard representation of a -#' graph, like an edge list. +#' Sometimes it is useful to work with a standard representation of a graph, like an edge list. #' #' `as_edgelist()` returns the list of edges in a graph. #' #' @param graph The graph to convert. #' @inheritParams rlang::args_dots_empty -#' @param names Whether to return a character matrix containing vertex -#' names (i.e. the `name` vertex attribute) if they exist or numeric -#' vertex IDs. +#' @param names Whether to return a character matrix containing vertex names (i.e. the `name` vertex attribute) +#' if they exist or numeric vertex IDs. #' @return A `ecount(graph)` by 2 numeric matrix. #' @seealso [graph_from_adjacency_matrix()], [read_graph()] #' @keywords graphs @@ -645,9 +621,8 @@ as_edgelist <- function( #' Convert between directed and undirected graphs #' -#' `as_directed()` converts an undirected graph to directed, -#' `as_undirected()` does the opposite, it converts a directed graph to -#' undirected. +#' `as_directed()` converts an undirected graph to directed, `as_undirected()` does the opposite, +#' it converts a directed graph to undirected. #' #' Conversion algorithms for `as_directed()`: #' \describe{ @@ -662,18 +637,13 @@ as_edgelist <- function( #' edge, one in each direction. #' } #' \item{"random"}{ -#' The number of edges in the graph stays the same, and -#' a randomly directed edge is created for each undirected edge. You -#' will get different results if you call the function multiple times -#' with the same graph. +#' The number of edges in the graph stays the same, and a randomly directed edge is created for each undirected edge. +#' You will get different results if you call the function multiple times with the same graph. #' } #' \item{"acyclic"}{ -#' The number of edges in the graph stays the same, and -#' a directed edge is created for each undirected edge such that the -#' resulting graph is guaranteed to be acyclic. This is achieved by ensuring -#' that edges always point from a lower index vertex to a higher index. -#' Note that the graph may include cycles of length 1 if the original -#' graph contained loop edges. +#' The number of edges in the graph stays the same, and a directed edge is created for each undirected edge such that the resulting graph is guaranteed to be acyclic. +#' This is achieved by ensuring that edges always point from a lower index vertex to a higher index. +#' Note that the graph may include cycles of length 1 if the original graph contained loop edges. #' } #' } #' @@ -690,23 +660,21 @@ as_edgelist <- function( #' edge, no multiple edges will be created. #' } #' \item{"mutual"}{ -#' One -#' undirected edge will be created for each pair of mutual edges. Non-mutual -#' edges are ignored. This mode might create multiple edges if there are more -#' than one mutual edge pairs between the same pair of vertices. +#' One undirected edge will be created for each pair of mutual edges. +#' Non-mutual edges are ignored. +#' This mode might create multiple edges if there are more than one mutual edge pairs between the same pair of vertices. #' } #' } #' #' @aliases as_directed as_undirected #' @param graph The graph to convert. -#' @param mode Character constant, defines the conversion algorithm. For -#' `as_directed()` it can be `mutual` or `arbitrary`. For -#' `as_undirected()` it can be `each`, `collapse` or -#' `mutual`. See details below. +#' @param mode Character constant, defines the conversion algorithm. +#' For `as_directed()` it can be `mutual` or `arbitrary`. +#' For `as_undirected()` it can be `each`, `collapse` or `mutual`. +#' See details below. #' @return A new graph object. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso [simplify()] for removing multiple and/or loop edges from -#' a graph. +#' @seealso [simplify()] for removing multiple and/or loop edges from a graph. #' @family conversion #' @export #' @keywords graphs @@ -791,11 +759,11 @@ as_directed <- function( } #' @rdname as_directed -#' @param edge.attr.comb 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 -#' this. The default `NULL` uses the `edge.attr.comb` igraph option. +#' @param edge.attr.comb 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 this. +#' The default `NULL` uses the `edge.attr.comb` igraph option. #' @export as_undirected <- function( graph, @@ -823,34 +791,27 @@ as_undirected <- function( #' Adjacency lists #' -#' Create adjacency lists from a graph, either for adjacent edges or for -#' neighboring vertices +#' Create adjacency lists from a graph, either for adjacent edges or for neighboring vertices #' -#' `as_adj_list()` returns a list of numeric vectors, which include the IDs -#' of neighbor vertices (according to the `mode` argument) of all -#' vertices. +#' `as_adj_list()` returns a list of numeric vectors, +#' which include the IDs of neighbor vertices (according to the `mode` argument) of all vertices. #' -#' `as_adj_edge_list()` returns a list of numeric vectors, which include the -#' IDs of adjacent edges (according to the `mode` argument) of all -#' vertices. +#' `as_adj_edge_list()` returns a list of numeric vectors, +#' which include the IDs of adjacent edges (according to the `mode` argument) of all vertices. #' #' @param graph The input graph. #' @inheritParams rlang::args_dots_empty -#' @param mode Character scalar, it gives what kind of adjacent edges/vertices -#' to include in the lists. \sQuote{`out`} is for outgoing edges/vertices, -#' \sQuote{`in`} is for incoming edges/vertices, \sQuote{`all`} is -#' for both. This argument is ignored for undirected graphs. -#' @param loops Character scalar, one of `"ignore"` (to omit loops), `"twice"` -#' (to include loop edges twice) and `"once"` (to include them once). `"twice"` -#' is not allowed for directed graphs and will be replaced with `"once"`. -#' @param multiple Logical, set to `FALSE` to use only one representative -#' of each set of parallel edges. -#' @return A list of `igraph.vs` or a list of numeric vectors depending on -#' the value of `igraph_opt("return.vs.es")`, see details for performance -#' characteristics. -#' @details If `igraph_opt("return.vs.es")` is true (default), the numeric -#' vectors of the adjacency lists are coerced to `igraph.vs`, this can be -#' a very expensive operation on large graphs. +#' @param mode Character scalar, it gives what kind of adjacent edges/vertices to include in the lists. +#' \sQuote{`out`} is for outgoing edges/vertices, \sQuote{`in`} is for incoming edges/vertices, \sQuote{`all`} is for both. +#' This argument is ignored for undirected graphs. +#' @param loops Character scalar, one of `"ignore"` (to omit loops), +#' `"twice"` (to include loop edges twice) and `"once"` (to include them once). +#' `"twice"` is not allowed for directed graphs and will be replaced with `"once"`. +#' @param multiple Logical, set to `FALSE` to use only one representative of each set of parallel edges. +#' @return A list of `igraph.vs` or a list of numeric vectors depending on the value of `igraph_opt("return.vs.es")`, +#' see details for performance characteristics. +#' @details If `igraph_opt("return.vs.es")` is true (default), the numeric vectors of the adjacency lists are coerced to `igraph.vs`, +#' this can be a very expensive operation on large graphs. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @seealso [as_edgelist()], [as_adjacency_matrix()] #' @family conversion @@ -1002,34 +963,25 @@ as_adj_edge_list <- function( #' Convert graphNEL objects from the graph package to igraph #' -#' The graphNEL class is defined in the `graph` package, it is another -#' way to represent graphs. `graph_from_graphnel()` takes a graphNEL -#' graph and converts it to an igraph graph. It handles all -#' graph/vertex/edge attributes. If the graphNEL graph has a vertex -#' attribute called \sQuote{`name`} it will be used as igraph vertex -#' attribute \sQuote{`name`} and the graphNEL vertex names will be -#' ignored. +#' The graphNEL class is defined in the `graph` package, it is another way to represent graphs. +#' `graph_from_graphnel()` takes a graphNEL graph and converts it to an igraph graph. +#' It handles all graph/vertex/edge attributes. +#' If the graphNEL graph has a vertex attribute called \sQuote{`name`} it will be used as igraph vertex attribute \sQuote{`name`} and the graphNEL vertex names will be ignored. #' -#' Because graphNEL graphs poorly support multiple edges, the edge -#' attributes of the multiple edges are lost: they are all replaced by the -#' attributes of the first of the multiple edges. +#' Because graphNEL graphs poorly support multiple edges, the edge attributes of the multiple edges are lost: +#' they are all replaced by the attributes of the first of the multiple edges. #' #' @param graphNEL The graphNEL graph. #' @inheritParams rlang::args_dots_empty -#' @param name Logical, whether to add graphNEL vertex names as an -#' igraph vertex attribute called \sQuote{`name`}. -#' @param weight Logical, whether to add graphNEL edge weights as an -#' igraph edge attribute called \sQuote{`weight`}. (graphNEL graphs are -#' always weighted.) -#' @param unlist.attrs Logical. graphNEL attribute query functions -#' return the values of the attributes in R lists, if this argument is -#' `TRUE` (the default) these will be converted to atomic vectors, -#' whenever possible, before adding them to the igraph graph. +#' @param name Logical, whether to add graphNEL vertex names as an igraph vertex attribute called \sQuote{`name`}. +#' @param weight Logical, whether to add graphNEL edge weights as an igraph edge attribute called \sQuote{`weight`}. +#' (graphNEL graphs are always weighted.) +#' @param unlist.attrs Logical. graphNEL attribute query functions return the values of the attributes in R lists, +#' if this argument is `TRUE` (the default) these will be converted to atomic vectors, whenever possible, +#' before adding them to the igraph graph. #' @return `graph_from_graphnel()` returns an igraph graph object. -#' @seealso [as_graphnel()] for the other direction, -#' [as_adjacency_matrix()], [graph_from_adjacency_matrix()], -#' [as_adj_list()] and [graph_from_adj_list()] for other -#' graph representations. +#' @seealso [as_graphnel()] for the other direction, [as_adjacency_matrix()], [graph_from_adjacency_matrix()], +#' [as_adj_list()] and [graph_from_adj_list()] for other graph representations. #' @examplesIf rlang::is_installed("graph") #' ## Undirected #' g <- make_ring(10) @@ -1149,22 +1101,18 @@ graph_from_graphnel <- function( #' Convert igraph graphs to graphNEL objects from the graph package #' -#' The graphNEL class is defined in the `graph` package, it is another -#' way to represent graphs. These functions are provided to convert between -#' the igraph and the graphNEL objects. +#' The graphNEL class is defined in the `graph` package, it is another way to represent graphs. +#' These functions are provided to convert between the igraph and the graphNEL objects. #' -#' `as_graphnel()` converts an igraph graph to a graphNEL graph. It -#' converts all graph/vertex/edge attributes. If the igraph graph has a -#' vertex attribute \sQuote{`name`}, then it will be used to assign -#' vertex names in the graphNEL graph. Otherwise numeric igraph vertex IDs -#' will be used for this purpose. +#' `as_graphnel()` converts an igraph graph to a graphNEL graph. +#' It converts all graph/vertex/edge attributes. +#' If the igraph graph has a vertex attribute \sQuote{`name`}, then it will be used to assign vertex names in the graphNEL graph. +#' Otherwise numeric igraph vertex IDs will be used for this purpose. #' #' @param graph An igraph graph object. #' @return `as_graphnel()` returns a graphNEL graph object. -#' @seealso [graph_from_graphnel()] for the other direction, -#' [as_adjacency_matrix()], [graph_from_adjacency_matrix()], -#' [as_adj_list()] and [graph_from_adj_list()] for -#' other graph representations. +#' @seealso [graph_from_graphnel()] for the other direction, [as_adjacency_matrix()], [graph_from_adjacency_matrix()], +#' [as_adj_list()] and [graph_from_adj_list()] for other graph representations. #' #' @examplesIf rlang::is_installed("graph") #' ## Undirected @@ -1372,26 +1320,21 @@ get.incidence.sparse <- function( #' Bipartite adjacency matrix of a bipartite graph #' -#' This function can return a sparse or dense bipartite adjacency matrix of a bipartite -#' network. The bipartite adjacency matrix is an \eqn{n} times \eqn{m} matrix, \eqn{n} -#' and \eqn{m} are the number of vertices of the two kinds. +#' This function can return a sparse or dense bipartite adjacency matrix of a bipartite network. +#' The bipartite adjacency matrix is an \eqn{n} times \eqn{m} matrix, \eqn{n} and \eqn{m} are the number of vertices of the two kinds. #' -#' Bipartite graphs have a `type` vertex attribute in igraph, this is -#' boolean and `FALSE` for the vertices of the first kind and `TRUE` -#' for vertices of the second kind. +#' Bipartite graphs have a `type` vertex attribute in igraph, +#' this is boolean and `FALSE` for the vertices of the first kind and `TRUE` for vertices of the second kind. #' -#' @param graph The input graph. The direction of the edges is ignored in -#' directed graphs. -#' @param types An optional vertex type vector to use instead of the -#' `type` vertex attribute. You must supply this argument if the graph has -#' no `type` vertex attribute. +#' @param graph The input graph. +#' The direction of the edges is ignored in directed graphs. +#' @param types An optional vertex type vector to use instead of the `type` vertex attribute. +#' You must supply this argument if the graph has no `type` vertex attribute. #' @inheritParams as_adjacency_matrix -#' @param names Logical, if `TRUE` and the vertices in the graph -#' are named (i.e. the graph has a vertex attribute called `name`), then -#' vertex names will be added to the result as row and column names. Otherwise -#' the IDs of the vertices are used as row and column names. -#' @param sparse Logical, if it is `TRUE` then a sparse matrix is -#' created, you will need the `Matrix` package for this. +#' @param names Logical, if `TRUE` and the vertices in the graph are named (i.e. the graph has a vertex attribute called `name`), +#' then vertex names will be added to the result as row and column names. +#' Otherwise the IDs of the vertices are used as row and column names. +#' @param sparse Logical, if it is `TRUE` then a sparse matrix is created, you will need the `Matrix` package for this. #' @return A sparse or dense matrix. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @seealso [graph_from_biadjacency_matrix()] for the opposite operation. @@ -1399,9 +1342,7 @@ get.incidence.sparse <- function( #' @export #' @keywords graphs #' @details -#' Some authors refer to the bipartite adjacency matrix as the -#' "bipartite incidence matrix". igraph 1.6.0 and later does not use -#' this naming to avoid confusion with the edge-vertex incidence matrix. +#' Some authors refer to the bipartite adjacency matrix as the "bipartite incidence matrix". igraph 1.6.0 and later does not use this naming to avoid confusion with the edge-vertex incidence matrix. #' @examples #' #' g <- make_bipartite_graph(c(0, 1, 0, 1, 0, 0), c(1, 2, 2, 3, 3, 4)) @@ -1487,14 +1428,11 @@ as_biadjacency_matrix <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `as_incidence_matrix()` was renamed to [as_biadjacency_matrix()] to create a more -#' consistent API. +#' `as_incidence_matrix()` was renamed to [as_biadjacency_matrix()] to create a more consistent API. #' @inheritParams as_biadjacency_matrix #' @keywords internal #' @details -#' Some authors refer to the bipartite adjacency matrix as the -#' "bipartite incidence matrix". igraph 1.6.0 and later does not use -#' this naming to avoid confusion with the edge-vertex incidence matrix. +#' Some authors refer to the bipartite adjacency matrix as the "bipartite incidence matrix". igraph 1.6.0 and later does not use this naming to avoid confusion with the edge-vertex incidence matrix. #' @export as_incidence_matrix <- function(...) { # nocov start @@ -1507,8 +1445,8 @@ as_incidence_matrix <- function(...) { } # nocov end #' @rdname graph_from_data_frame #' @param x An igraph object. -#' @param what Character constant, whether to return info about vertices, -#' edges, or both. The default is \sQuote{edges}. +#' @param what Character constant, whether to return info about vertices, edges, or both. +#' The default is \sQuote{edges}. #' @family conversion #' @family biadjacency #' @export @@ -1554,30 +1492,24 @@ as_data_frame <- function(x, what = c("edges", "vertices", "both")) { #' Create graphs from adjacency lists #' -#' An adjacency list is a list of numeric vectors, containing the neighbor -#' vertices for each vertex. This function creates an igraph graph object from -#' such a list. +#' An adjacency list is a list of numeric vectors, containing the neighbor vertices for each vertex. +#' This function creates an igraph graph object from such a list. #' -#' Adjacency lists are handy if you intend to do many (small) modifications to -#' a graph. In this case adjacency lists are more efficient than igraph graphs. +#' Adjacency lists are handy if you intend to do many (small) modifications to a graph. +#' In this case adjacency lists are more efficient than igraph graphs. #' -#' The idea is that you convert your graph to an adjacency list by -#' [as_adj_list()], do your modifications to the graphs and finally -#' create again an igraph graph by calling `graph_from_adj_list()`. +#' The idea is that you convert your graph to an adjacency list by [as_adj_list()], +#' do your modifications to the graphs and finally create again an igraph graph by calling `graph_from_adj_list()`. #' -#' @param adjlist The adjacency list. It should be consistent, i.e. the maximum -#' throughout all vectors in the list must be less than the number of vectors -#' (=the number of vertices in the graph). +#' @param adjlist The adjacency list. +#' It should be consistent, +#' i.e. the maximum throughout all vectors in the list must be less than the number of vectors (=the number of vertices in the graph). #' @inheritParams rlang::args_dots_empty -#' @param mode Character scalar, it specifies whether the graph to create is -#' undirected (\sQuote{all} or \sQuote{total}) or directed; and in the latter -#' case, whether it contains the outgoing (\sQuote{out}) or the incoming -#' (\sQuote{in}) neighbors of the vertices. -#' @param duplicate Logical. For undirected graphs it gives whether -#' edges are included in the list twice. E.g. if it is `TRUE` then for an -#' undirected \code{{A,B}} edge `graph_from_adj_list()` expects `A` -#' included in the neighbors of `B` and `B` to be included in the -#' neighbors of `A`. +#' @param mode Character scalar, it specifies whether the graph to create is undirected (\sQuote{all} or \sQuote{total}) or directed; +#' and in the latter case, whether it contains the outgoing (\sQuote{out}) or the incoming (\sQuote{in}) neighbors of the vertices. +#' @param duplicate Logical. +#' For undirected graphs it gives whether edges are included in the list twice. +#' E.g. if it is `TRUE` then for an undirected \code{{A,B}} edge `graph_from_adj_list()` expects `A` included in the neighbors of `B` and `B` to be included in the neighbors of `A`. #' #' This argument is ignored if `mode` is `out` or `in`. #' @return An igraph graph object. @@ -1656,14 +1588,11 @@ graph_from_adj_list <- function( #' Convert a graph to a long data frame #' -#' A long data frame contains all metadata about both the vertices -#' and edges of the graph. It contains one row for each edge, and -#' all metadata about that edge and its incident vertices are included -#' in that row. The names of the columns that contain the metadata -#' of the incident vertices are prefixed with `from_` and `to_`. -#' The first two columns are always named `from` and `to` and -#' they contain the numeric IDs of the incident vertices. The rows are -#' listed in the order of numeric vertex IDs. +#' A long data frame contains all metadata about both the vertices and edges of the graph. +#' It contains one row for each edge, and all metadata about that edge and its incident vertices are included in that row. +#' The names of the columns that contain the metadata of the incident vertices are prefixed with `from_` and `to_`. +#' The first two columns are always named `from` and `to` and they contain the numeric IDs of the incident vertices. +#' The rows are listed in the order of numeric vertex IDs. #' #' @param graph Input graph #' @return A long data frame. @@ -1719,27 +1648,21 @@ as_long_data_frame <- function(graph) { #' Convert igraph objects to adjacency or edge list matrices #' -#' Get adjacency or edgelist representation of the network stored as an -#' `igraph` object. +#' Get adjacency or edgelist representation of the network stored as an `igraph` object. #' -#' If `matrix.type` is `"edgelist"`, then a two-column numeric edge list -#' matrix is returned. The value of `attrname` is ignored. +#' If `matrix.type` is `"edgelist"`, then a two-column numeric edge list matrix is returned. +#' The value of `attrname` is ignored. #' -#' If `matrix.type` is `"adjacency"`, then a square adjacency matrix is -#' returned. For adjacency matrices, you can use the `attr` keyword argument -#' to use the values of an edge attribute in the matrix cells. See the -#' documentation of [as_adjacency_matrix] for more details. +#' If `matrix.type` is `"adjacency"`, then a square adjacency matrix is returned. +#' For adjacency matrices, you can use the `attr` keyword argument to use the values of an edge attribute in the matrix cells. +#' See the documentation of [as_adjacency_matrix] for more details. #' -#' Other arguments passed through `...` are passed to either -#' [as_adjacency_matrix()] or [as_edgelist()] -#' depending on the value of `matrix.type`. +#' Other arguments passed through `...` are passed to either [as_adjacency_matrix()] or [as_edgelist()] depending on the value of `matrix.type`. #' #' @param x object of class `igraph`, the network -#' @param matrix.type character, type of matrix to return, currently "adjacency" -#' or "edgelist" are supported +#' @param matrix.type character, type of matrix to return, currently "adjacency" or "edgelist" are supported #' @param \dots other arguments to/from other methods -#' @return Depending on the value of `matrix.type` either a square -#' adjacency matrix or a two-column numeric matrix representing the edgelist. +#' @return Depending on the value of `matrix.type` either a square adjacency matrix or a two-column numeric matrix representing the edgelist. #' @author Michal Bojanowski, originally from the `intergraph` package #' @family conversion #' @export @@ -1766,8 +1689,7 @@ as.matrix.igraph <- function(x, matrix.type = c("adjacency", "edgelist"), ...) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `as.directed()` was renamed to [as_directed()] to create a more -#' consistent API. +#' `as.directed()` was renamed to [as_directed()] to create a more consistent API. #' @inheritParams as_directed #' @keywords internal #' @export @@ -1784,8 +1706,7 @@ as.directed <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `as.undirected()` was renamed to [as_undirected()] to create a more -#' consistent API. +#' `as.undirected()` was renamed to [as_undirected()] to create a more consistent API. #' @inheritParams as_undirected #' @keywords internal #' @export @@ -1803,8 +1724,7 @@ as.undirected <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.edgelist()` was renamed to [graph_from_edgelist()] to create a more -#' consistent API. +#' `graph.edgelist()` was renamed to [graph_from_edgelist()] to create a more consistent API. #' @inheritParams graph_from_edgelist #' @keywords internal #' @export @@ -1823,8 +1743,7 @@ graph.edgelist <- function(el, directed = TRUE) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.data.frame()` was renamed to [graph_from_data_frame()] to create a more -#' consistent API. +#' `graph.data.frame()` was renamed to [graph_from_data_frame()] to create a more consistent API. #' @inheritParams graph_from_data_frame #' @keywords internal #' @export @@ -1863,77 +1782,59 @@ graph.data.frame <- function(d, directed = TRUE, vertices = NULL) { #' Creating igraph graphs from data frames or vice-versa #' -#' This function creates an igraph graph from one or two data frames containing -#' the (symbolic) edge list and edge/vertex attributes. +#' This function creates an igraph graph from one or two data frames containing the (symbolic) edge list and edge/vertex attributes. #' #' `graph_from_data_frame()` creates igraph graphs from one or two data frames. -#' It has two modes of operation, depending whether the `vertices` -#' argument is `NULL` or not. +#' It has two modes of operation, depending whether the `vertices` argument is `NULL` or not. #' -#' If `vertices` is `NULL`, then the first two columns of `d` -#' are used as a symbolic edge list and additional columns as edge attributes. +#' If `vertices` is `NULL`, then the first two columns of `d` are used as a symbolic edge list and additional columns as edge attributes. #' The names of the attributes are taken from the names of the columns. #' -#' If `vertices` is not `NULL`, then it must be a data frame giving -#' vertex metadata. The first column of `vertices` is assumed to contain -#' symbolic vertex names, this will be added to the graphs as the -#' \sQuote{`name`} vertex attribute. Other columns will be added as -#' additional vertex attributes. If `vertices` is not `NULL` then the -#' symbolic edge list given in `d` is checked to contain only vertex names -#' listed in `vertices`. +#' If `vertices` is not `NULL`, then it must be a data frame giving vertex metadata. +#' The first column of `vertices` is assumed to contain symbolic vertex names, +#' this will be added to the graphs as the \sQuote{`name`} vertex attribute. +#' Other columns will be added as additional vertex attributes. +#' If `vertices` is not `NULL` then the symbolic edge list given in `d` is checked to contain only vertex names listed in `vertices`. #' -#' Typically, the data frames are exported from some spreadsheet software like -#' Excel and are imported into R via [read.table()], +#' Typically, the data frames are exported from some spreadsheet software like Excel and are imported into R via [read.table()], #' [read.delim()] or [read.csv()]. #' -#' All edges in the data frame are included in the graph, which may include -#' multiple parallel edges and loops. +#' All edges in the data frame are included in the graph, which may include multiple parallel edges and loops. #' -#' `as_data_frame()` converts the igraph graph into one or more data -#' frames, depending on the `what` argument. +#' `as_data_frame()` converts the igraph graph into one or more data frames, depending on the `what` argument. #' -#' If the `what` argument is `edges` (the default), then the edges of -#' the graph and also the edge attributes are returned. The edges will be in -#' the first two columns, named `from` and `to`. (This also denotes -#' edge direction for directed graphs.) For named graphs, the vertex names -#' will be included in these columns, for other graphs, the numeric vertex IDs. -#' The edge attributes will be in the other columns. It is not a good idea to -#' have an edge attribute named `from` or `to`, because then the -#' column named in the data frame will not be unique. The edges are listed in -#' the order of their numeric IDs. +#' If the `what` argument is `edges` (the default), then the edges of the graph and also the edge attributes are returned. +#' The edges will be in the first two columns, named `from` and `to`. +#' (This also denotes edge direction for directed graphs.) +#' For named graphs, the vertex names will be included in these columns, for other graphs, the numeric vertex IDs. +#' The edge attributes will be in the other columns. +#' It is not a good idea to have an edge attribute named `from` or `to`, because then the column named in the data frame will not be unique. +#' The edges are listed in the order of their numeric IDs. #' -#' If the `what` argument is `vertices`, then vertex attributes are -#' returned. Vertices are listed in the order of their numeric vertex IDs. +#' If the `what` argument is `vertices`, then vertex attributes are returned. +#' Vertices are listed in the order of their numeric vertex IDs. #' -#' If the `what` argument is `both`, then both vertex and edge data -#' is returned, in a list with named entries `vertices` and `edges`. +#' If the `what` argument is `both`, then both vertex and edge data is returned, in a list with named entries `vertices` and `edges`. #' -#' @param d A data frame containing a symbolic edge list in the first two -#' columns. Additional columns are considered as edge attributes. Since -#' version 0.7 this argument is coerced to a data frame with -#' `as.data.frame`. +#' @param d A data frame containing a symbolic edge list in the first two columns. +#' Additional columns are considered as edge attributes. +#' Since version 0.7 this argument is coerced to a data frame with `as.data.frame`. #' @param directed Logical, whether or not to create a directed graph. #' @inheritParams rlang::args_dots_empty -#' @param vertices A data frame with vertex metadata, or `NULL`. See -#' details below. Since version 0.7 this argument is coerced to a data frame -#' with `as.data.frame`, if not `NULL`. -#' @return An igraph graph object for `graph_from_data_frame()`, and either a -#' data frame or a list of two data frames named `edges` and -#' `vertices` for `as.data.frame`. -#' @note For `graph_from_data_frame()` `NA` elements in the first two -#' columns \sQuote{d} are replaced by the string \dQuote{NA} before creating -#' the graph. This means that all `NA`s will correspond to a single -#' vertex. -#' -#' `NA` elements in the first column of \sQuote{vertices} are also -#' replaced by the string \dQuote{NA}, but the rest of \sQuote{vertices} is not -#' touched. In other words, vertex names (=the first column) cannot be -#' `NA`, but other vertex attributes can. +#' @param vertices A data frame with vertex metadata, or `NULL`. +#' See details below. +#' Since version 0.7 this argument is coerced to a data frame with `as.data.frame`, if not `NULL`. +#' @return An igraph graph object for `graph_from_data_frame()`, +#' and either a data frame or a list of two data frames named `edges` and `vertices` for `as.data.frame`. +#' @note For `graph_from_data_frame()` `NA` elements in the first two columns \sQuote{d} are replaced by the string \dQuote{NA} before creating the graph. +#' This means that all `NA`s will correspond to a single vertex. +#' +#' `NA` elements in the first column of \sQuote{vertices} are also replaced by the string \dQuote{NA}, +#' but the rest of \sQuote{vertices} is not touched. +#' In other words, vertex names (=the first column) cannot be `NA`, but other vertex attributes can. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso [graph_from_literal()] -#' for another way to create graphs, [read.table()] to read in tables -#' from files. See [from_data_frame()] to build a lazy constructor -#' specification for [make_()] or [sample_()]. +#' @seealso [graph_from_literal()] for another way to create graphs, [read.table()] to read in tables from files. +#' See [from_data_frame()] to build a lazy constructor specification for [make_()] or [sample_()]. #' @keywords graphs #' @examples #' @@ -2081,25 +1982,20 @@ graph_from_data_frame <- function( #' Constructor specifications for `graph_()`, `make_()` and `sample_()` #' #' @description -#' Each of these functions builds a lazy constructor specification for the -#' given graph constructor, to be used with [graph_()], [make_()] or -#' [sample_()]. The specification is only evaluated when the graph is actually -#' constructed, so it can be combined with constructor modifiers such as -#' [with_vertex_()] or [with_edge_()]. +#' Each of these functions builds a lazy constructor specification for the given graph constructor, to be used with [graph_()], +#' [make_()] or [sample_()]. +#' The specification is only evaluated when the graph is actually constructed, +#' so it can be combined with constructor modifiers such as [with_vertex_()] or [with_edge_()]. #' -#' `from_data_frame()`, `from_edgelist()`, `tree()` and `degseq()` wrap -#' [graph_from_data_frame()], [graph_from_edgelist()], [make_tree()] (or -#' [sample_tree()]) and [sample_degseq()] (or [realize_degseq()]), -#' respectively. +#' `from_data_frame()`, `from_edgelist()`, `tree()` and `degseq()` wrap [graph_from_data_frame()], [graph_from_edgelist()], +#' [make_tree()] (or [sample_tree()]) and [sample_degseq()] (or [realize_degseq()]), respectively. #' -#' The other constructors have specification functions as well; they are -#' documented together with the constructor they wrap, e.g. `ring()` on the -#' [make_ring()] page. +#' The other constructors have specification functions as well; they are documented together with the constructor they wrap, +#' e.g. `ring()` on the [make_ring()] page. #' #' @param ... Forwarded to the corresponding constructor function. #' @return An object of class `igraph_constructor_spec`. -#' @seealso [graph_()], [make_()] and [sample_()] to apply a constructor -#' specification. +#' @seealso [graph_()], [make_()] and [sample_()] to apply a constructor specification. #' @family constructor specifications #' @keywords graphs #' @rdname constructor_spec @@ -2119,20 +2015,18 @@ from_data_frame <- function(...) constructor_spec(graph_from_data_frame, ...) #' Create a graph from an edge list matrix #' -#' `graph_from_edgelist()` creates a graph from an edge list. Its argument -#' is a two-column matrix, each row defines one edge. If it is -#' a numeric matrix then its elements are interpreted as vertex IDs. If -#' it is a character matrix then it is interpreted as symbolic vertex -#' names and a vertex ID will be assigned to each name, and also a -#' `name` vertex attribute will be added. +#' `graph_from_edgelist()` creates a graph from an edge list. +#' Its argument is a two-column matrix, each row defines one edge. +#' If it is a numeric matrix then its elements are interpreted as vertex IDs. +#' If it is a character matrix then it is interpreted as symbolic vertex names and a vertex ID will be assigned to each name, +#' and also a `name` vertex attribute will be added. #' #' @concept Edge list #' @param el The edge list, a two column matrix, character or numeric. #' @inheritParams rlang::args_dots_empty #' @param directed Whether to create a directed graph. #' @return An igraph graph. -#' @seealso [from_edgelist()] to build a lazy constructor specification for -#' [make_()] or [sample_()]. +#' @seealso [from_edgelist()] to build a lazy constructor specification for [make_()] or [sample_()]. #' #' @family deterministic constructors #' @export diff --git a/R/cycles.R b/R/cycles.R index 6859cdf1f3f..de35abbba39 100644 --- a/R/cycles.R +++ b/R/cycles.R @@ -23,21 +23,18 @@ #' @description #' `r lifecycle::badge("experimental")` #' -#' This function returns a cycle of the graph, in terms of both its vertices -#' and edges. If the graph is acyclic, it returns empty vertex and edge -#' sequences. +#' This function returns a cycle of the graph, in terms of both its vertices and edges. +#' If the graph is acyclic, it returns empty vertex and edge sequences. #' -#' Use [is_acyclic()] to determine if a graph has cycles, without returning -#' a specific cycle. +#' Use [is_acyclic()] to determine if a graph has cycles, without returning 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. -#' @return A list of integer vectors, each integer vector is a path from -#' the source vertex to one of the target vertices. A path is given by its -#' vertex IDs. +#' `out` follows edge directions, `in` follows edges in the reverse direction, and `all` ignores edge directions. +#' Ignored in undirected graphs. +#' @return A list of integer vectors, each integer vector is a path from the source vertex to one of the target vertices. +#' A path is given by its vertex IDs. #' @keywords graphs #' @examples #' @@ -102,32 +99,31 @@ find_cycle <- function( #' @description #' `r lifecycle::badge("experimental")` #' -#' This function lists all simple cycles in a graph within a range of cycle -#' lengths. A cycle is called simple if it has no repeated vertices. +#' This function lists all simple cycles in a graph within a range of cycle lengths. +#' A cycle is called simple if it has no repeated vertices. #' -#' Multi-edges and self-loops are taken into account. Note that typical graphs -#' have exponentially many cycles and the presence of multi-edges exacerbates -#' this combinatorial explosion. +#' Multi-edges and self-loops are taken into account. +#' Note that typical graphs have exponentially many cycles and the presence of multi-edges exacerbates this combinatorial explosion. #' #' @inheritParams find_cycle -#' @param min Lower limit on cycle lengths to consider. `NULL` means no limit. -#' @param max Upper limit on cycle lengths to consider. `NULL` means no limit. +#' @param min Lower limit on cycle lengths to consider. +#' `NULL` means no limit. +#' @param max Upper limit on cycle lengths to consider. +#' `NULL` means no limit. #' @param ... These dots are for future extensions and must be empty. -#' @param callback Optional function to call for each cycle found. If provided, -#' the function should accept two arguments: `vertices` (integer vector of vertex -#' IDs in the cycle) and `edges` (integer vector of edge IDs -#' in the cycle). The function should return `FALSE` to continue -#' the search or `TRUE` to stop it. If `NULL` (the default), all cycles are -#' collected and returned as a list. +#' @param callback Optional function to call for each cycle found. +#' If provided, the function should accept two arguments: +#' `vertices` (integer vector of vertex IDs in the cycle) and `edges` (integer vector of edge IDs in the cycle). +#' The function should return `FALSE` to continue the search or `TRUE` to stop it. +#' If `NULL` (the default), all cycles are collected and returned as a list. #' -#' **Important limitation:** Callback functions must NOT call any igraph -#' functions (including simple queries like `vcount()` or `ecount()`). Doing -#' so will cause R to crash due to reentrancy issues. Extract -#' any needed graph information before calling the function with a callback, or -#' use collector mode (the default) and process results afterward. -#' @return If `callback` is `NULL`, returns a list with two elements: `vertices` -#' (list of integer vectors with vertex IDs) and `edges` (list of integer vectors -#' with edge IDs). If `callback` is provided, returns `NULL` invisibly. +#' **Important limitation:** Callback functions must NOT call any igraph functions (including simple queries like `vcount()` or `ecount()`). +#' Doing so will cause R to crash due to reentrancy issues. +#' Extract any needed graph information before calling the function with a callback, +#' or use collector mode (the default) and process results afterward. +#' @return If `callback` is `NULL`, returns a list with two elements: +#' `vertices` (list of integer vectors with vertex IDs) and `edges` (list of integer vectors with edge IDs). +#' If `callback` is provided, returns `NULL` invisibly. #' @keywords graphs #' @examples #' @@ -138,21 +134,19 @@ find_cycle <- function( #' #' @family cycles #' @param ... These dots are for future extensions and must be empty. -#' @param callback Optional function to call for each cycle found. If provided, -#' the function should accept two arguments: `vertices` (integer vector of vertex -#' IDs in the cycle) and `edges` (integer vector of edge IDs -#' in the cycle). The function should return `FALSE` to continue -#' the search or `TRUE` to stop it. If `NULL` (the default), all cycles are -#' collected and returned as a list. +#' @param callback Optional function to call for each cycle found. +#' If provided, the function should accept two arguments: +#' `vertices` (integer vector of vertex IDs in the cycle) and `edges` (integer vector of edge IDs in the cycle). +#' The function should return `FALSE` to continue the search or `TRUE` to stop it. +#' If `NULL` (the default), all cycles are collected and returned as a list. #' -#' **Important limitation:** Callback functions must NOT call any igraph -#' functions (including simple queries like `vcount()` or `ecount()`). Doing -#' so will cause R to crash due to nested `.Call()` state corruption. Extract -#' any needed graph information before calling the function with a callback, or -#' use collector mode (the default) and process results afterward. -#' @return If `callback` is `NULL`, returns a list with two elements: `vertices` -#' (list of integer vectors with vertex IDs) and `edges` (list of integer vectors -#' with edge IDs). If `callback` is provided, returns `NULL` invisibly. +#' **Important limitation:** Callback functions must NOT call any igraph functions (including simple queries like `vcount()` or `ecount()`). +#' Doing so will cause R to crash due to nested `.Call()` state corruption. +#' Extract any needed graph information before calling the function with a callback, +#' or use collector mode (the default) and process results afterward. +#' @return If `callback` is `NULL`, returns a list with two elements: +#' `vertices` (list of integer vectors with vertex IDs) and `edges` (list of integer vectors with edge IDs). +#' If `callback` is provided, returns `NULL` invisibly. #' @export simple_cycles <- function( diff --git a/R/decomposition.R b/R/decomposition.R index 80a1f1fef7f..10d4994cc8e 100644 --- a/R/decomposition.R +++ b/R/decomposition.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `is.chordal()` was renamed to [is_chordal()] to create a more -#' consistent API. +#' `is.chordal()` was renamed to [is_chordal()] to create a more consistent API. #' @inheritParams is_chordal #' @keywords internal #' @export @@ -52,29 +51,24 @@ is.chordal <- function( #' Chordality of a graph #' -#' A graph is chordal (or triangulated) if each of its cycles of four or more -#' nodes has a chord, which is an edge joining two nodes that are not adjacent -#' in the cycle. An equivalent definition is that any chordless cycles have at -#' most three nodes. +#' A graph is chordal (or triangulated) if each of its cycles of four or more nodes has a chord, +#' which is an edge joining two nodes that are not adjacent in the cycle. +#' An equivalent definition is that any chordless cycles have at most three nodes. #' -#' The chordality of the graph is decided by first performing maximum -#' cardinality search on it (if the `alpha` and `alpham1` arguments -#' are `NULL`), and then calculating the set of fill-in edges. +#' The chordality of the graph is decided by first performing maximum cardinality search on it (if the `alpha` and `alpham1` arguments are `NULL`), +#' and then calculating the set of fill-in edges. #' #' The set of fill-in edges is empty if and only if the graph is chordal. #' #' It is also true that adding the fill-in edges to the graph makes it chordal. #' -#' @param graph The input graph. It may be directed, but edge directions are -#' ignored, as the algorithm is defined for undirected graphs. +#' @param graph The input graph. +#' It may be directed, but edge directions are ignored, as the algorithm is defined for undirected graphs. #' @inheritParams rlang::args_dots_empty -#' @param alpha Numeric vector, the maximal chardinality ordering of the -#' vertices. If it is `NULL`, then it is automatically calculated by -#' calling [max_cardinality()], or from `alpham1` if -#' that is given.. -#' @param alpham1 Numeric vector, the inverse of `alpha`. If it is -#' `NULL`, then it is automatically calculated by calling -#' [max_cardinality()], or from `alpha`. +#' @param alpha Numeric vector, the maximal chardinality ordering of the vertices. +#' If it is `NULL`, then it is automatically calculated by calling [max_cardinality()], or from `alpham1` if that is given.. +#' @param alpham1 Numeric vector, the inverse of `alpha`. +#' If it is `NULL`, then it is automatically calculated by calling [max_cardinality()], or from `alpha`. #' @param fillin Logical, whether to calculate the fill-in edges. #' @param newgraph Logical, whether to calculate the triangulated graph. #' @return A list with three members: diff --git a/R/degseq.R b/R/degseq.R index fd41b0286d0..c66122c9bb8 100644 --- a/R/degseq.R +++ b/R/degseq.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `is.graphical.degree.sequence()` was renamed to [is_graphical()] to create a more -#' consistent API. +#' `is.graphical.degree.sequence()` was renamed to [is_graphical()] to create a more consistent API. #' @inheritParams is_graphical #' @keywords internal #' @export @@ -31,8 +30,7 @@ is.graphical.degree.sequence <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `is.degree.sequence()` was renamed to [is_degseq()] to create a more -#' consistent API. +#' `is.degree.sequence()` was renamed to [is_degseq()] to create a more consistent API. #' @inheritParams is_degseq #' @keywords internal #' @export @@ -67,19 +65,17 @@ is.degree.sequence <- function(out.deg, in.deg = NULL) { #' Check if a degree sequence is valid for a multi-graph #' -#' `is_degseq()` checks whether the given vertex degrees (in- and -#' out-degrees for directed graphs) can be realized by a graph. Note that the -#' graph does not have to be simple, it may contain loop and multiple edges. +#' `is_degseq()` checks whether the given vertex degrees (in- and out-degrees for directed graphs) can be realized by a graph. +#' Note that the graph does not have to be simple, it may contain loop and multiple edges. #' For undirected graphs, it also checks whether the sum of degrees is even. -#' For directed graphs, the function checks whether the lengths of the two -#' degree vectors are equal and whether their sums are also equal. These are -#' known sufficient and necessary conditions for a degree sequence to be valid. +#' For directed graphs, the function checks whether the lengths of the two degree vectors are equal and whether their sums are also equal. +#' These are known sufficient and necessary conditions for a degree sequence to be valid. #' #' @aliases is_degseq -#' @param out.deg Integer vector, the degree sequence for undirected graphs, or -#' the out-degree sequence for directed graphs. -#' @param in.deg `NULL` or an integer vector. For undirected graphs, it -#' should be `NULL`. For directed graphs it specifies the in-degrees. +#' @param out.deg Integer vector, the degree sequence for undirected graphs, or the out-degree sequence for directed graphs. +#' @param in.deg `NULL` or an integer vector. +#' For undirected graphs, it should be `NULL`. +#' For directed graphs it specifies the in-degrees. #' @return A logical scalar. #' @author Tamás Nepusz \email{ntamas@@gmail.com} and Szabolcs Horvát \email{szhorvat@gmail.com} #' @references Z Király, Recognizing graphic degree sequences and generating @@ -106,24 +102,21 @@ is_degseq <- function(out.deg, in.deg = NULL) { #' Is a degree sequence graphical? #' -#' Determine whether the given vertex degrees (in- and out-degrees for -#' directed graphs) can be realized by a graph. +#' Determine whether the given vertex degrees (in- and out-degrees for directed graphs) can be realized by a graph. #' -#' The classical concept of graphicality assumes simple graphs. This function -#' can perform the check also when self-loops, multi-edges, or both are allowed -#' in the graph. +#' The classical concept of graphicality assumes simple graphs. +#' This function can perform the check also when self-loops, multi-edges, or both are allowed in the graph. #' -#' @param out.deg Integer vector, the degree sequence for undirected graphs, or -#' the out-degree sequence for directed graphs. -#' @param in.deg `NULL` or an integer vector. For undirected graphs, it -#' should be `NULL`. For directed graphs it specifies the in-degrees. +#' @param out.deg Integer vector, the degree sequence for undirected graphs, or the out-degree sequence for directed graphs. +#' @param in.deg `NULL` or an integer vector. +#' For undirected graphs, it should be `NULL`. +#' For directed graphs it specifies the in-degrees. #' @inheritParams rlang::args_dots_empty -#' @param allowed.edge.types The allowed edge types in the graph. \sQuote{simple} -#' means that neither loop nor multiple edges are allowed (i.e. the graph must be -#' simple). \sQuote{loops} means that loop edges are allowed but mutiple edges -#' are not. \sQuote{multi} means that multiple edges are allowed but loop edges -#' are not. \sQuote{all} means that both loop edges and multiple edges are -#' allowed. +#' @param allowed.edge.types The allowed edge types in the graph. +#' \sQuote{simple} means that neither loop nor multiple edges are allowed (i.e. the graph must be simple). +#' \sQuote{loops} means that loop edges are allowed but mutiple edges are not. +#' \sQuote{multi} means that multiple edges are allowed but loop edges are not. +#' \sQuote{all} means that both loop edges and multiple edges are allowed. #' @return A logical scalar. #' @author Tamás Nepusz \email{ntamas@@gmail.com} #' @references Hakimi SL: On the realizability of a set of integers as degrees diff --git a/R/efficiency.R b/R/efficiency.R index c572f7f3aa8..66135068154 100644 --- a/R/efficiency.R +++ b/R/efficiency.R @@ -1,13 +1,11 @@ #' Efficiency of a graph #' -#' These functions calculate the global or average local efficiency of a network, -#' or the local efficiency of every vertex in the network. See below for -#' definitions. +#' These functions calculate the global or average local efficiency of a network, or the local efficiency of every vertex in the network. +#' See below for definitions. #' #' @section Global efficiency: #' -#' The global efficiency of a network is defined as the average of inverse -#' distances between all pairs of vertices. +#' The global efficiency of a network is defined as the average of inverse distances between all pairs of vertices. #' #' More precisely: #' @@ -16,43 +14,38 @@ #' #' where \eqn{n}{n} is the number of vertices. #' -#' The inverse distance between pairs that are not reachable from each other is -#' considered to be zero. For graphs with fewer than 2 vertices, NaN is returned. +#' The inverse distance between pairs that are not reachable from each other is considered to be zero. +#' For graphs with fewer than 2 vertices, NaN is returned. #' #' @section Local efficiency: #' -#' The local efficiency of a network around a vertex is defined as follows: We -#' remove the vertex and compute the distances (shortest path lengths) between -#' its neighbours through the rest of the network. The local efficiency around -#' the removed vertex is the average of the inverse of these distances. +#' The local efficiency of a network around a vertex is defined as follows: +#' We remove the vertex and compute the distances (shortest path lengths) between its neighbours through the rest of the network. +#' The local efficiency around the removed vertex is the average of the inverse of these distances. #' -#' The inverse distance between two vertices which are not reachable from each -#' other is considered to be zero. The local efficiency around a vertex with -#' fewer than two neighbours is taken to be zero by convention. +#' The inverse distance between two vertices which are not reachable from each other is considered to be zero. +#' The local efficiency around a vertex with fewer than two neighbours is taken to be zero by convention. #' #' @section Average local efficiency: #' -#' The average local efficiency of a network is simply the arithmetic mean of -#' the local efficiencies of all the vertices; see the definition for local -#' efficiency above. +#' The average local efficiency of a network is simply the arithmetic mean of the local efficiencies of all the vertices; +#' see the definition for local efficiency above. #' #' @param graph The graph to analyze. #' @inheritParams rlang::args_dots_empty -#' @param weights The edge weights. All edge weights must be non-negative; -#' additionally, no edge weight may be NaN. If it is `NULL` (the default) -#' and the graph has a `weight` edge attribute, then it is used automatically. +#' @param weights The edge weights. +#' All edge weights must be non-negative; additionally, no edge weight may be NaN. +#' If it is `NULL` (the default) and the graph has a `weight` edge attribute, then it is used automatically. #' @param vids The vertex IDs of the vertices for which the calculation will be done. -#' Applies to the local efficiency calculation only. The default `NULL` -#' selects all vertices. -#' @param directed Logical, whether to consider directed paths. Ignored -#' for undirected graphs. -#' @param mode Specifies how to define the local neighborhood of a vertex in -#' directed graphs. \dQuote{out} considers out-neighbors only, \dQuote{in} -#' considers in-neighbors only, \dQuote{all} considers both. -#' @return For `global_efficiency()`, the global efficiency of the graph as a -#' single number. For `average_local_efficiency()`, the average local -#' efficiency of the graph as a single number. For `local_efficiency()`, the -#' local efficiency of each vertex in a vector. +#' Applies to the local efficiency calculation only. +#' The default `NULL` selects all vertices. +#' @param directed Logical, whether to consider directed paths. +#' Ignored for undirected graphs. +#' @param mode Specifies how to define the local neighborhood of a vertex in directed graphs. +#' \dQuote{out} considers out-neighbors only, \dQuote{in} considers in-neighbors only, \dQuote{all} considers both. +#' @return For `global_efficiency()`, the global efficiency of the graph as a single number. +#' For `average_local_efficiency()`, the average local efficiency of the graph as a single number. +#' For `local_efficiency()`, the local efficiency of each vertex in a vector. #' #' @references V. Latora and M. Marchiori: Efficient Behavior of Small-World #' Networks, Phys. Rev. Lett. 87, 198701 (2001). diff --git a/R/embedding.R b/R/embedding.R index da95f723479..907a128dc99 100644 --- a/R/embedding.R +++ b/R/embedding.R @@ -25,49 +25,39 @@ #' #' Spectral decomposition of the adjacency matrices of graphs. #' -#' This function computes a `no`-dimensional Euclidean representation of -#' the graph based on its adjacency matrix, \eqn{A}. This representation is -#' computed via the singular value decomposition of the adjacency matrix, -#' \eqn{A=UDV^T}.In the case, where the graph is a random dot product graph -#' generated using latent position vectors in \eqn{R^{no}} for each vertex, the -#' embedding will provide an estimate of these latent vectors. -#' -#' For undirected graphs the latent positions are calculated as -#' \eqn{X=U^{no}D^{1/2}}{U[no] sqrt(D[no])}, where \eqn{U^{no}}{U[no]} equals -#' to the first `no` columns of \eqn{U}, and \eqn{D^{1/2}}{sqrt(D[no])} is -#' a diagonal matrix containing the top `no` singular values on the -#' diagonal. -#' -#' For directed graphs the embedding is defined as the pair -#' \eqn{X=U^{no}D^{1/2}}{U[no] sqrt(D[no])} and \eqn{Y=V^{no}D^{1/2}}{V[no] +#' This function computes a `no`-dimensional Euclidean representation of the graph based on its adjacency matrix, \eqn{A}. +#' This representation is computed via the singular value decomposition of the adjacency matrix, \eqn{A=UDV^T}.In the case, +#' where the graph is a random dot product graph generated using latent position vectors in \eqn{R^{no}} for each vertex, +#' the embedding will provide an estimate of these latent vectors. +#' +#' For undirected graphs the latent positions are calculated as \eqn{X=U^{no}D^{1/2}}{U[no] sqrt(D[no])}, +#' where \eqn{U^{no}}{U[no]} equals to the first `no` columns of \eqn{U}, +#' and \eqn{D^{1/2}}{sqrt(D[no])} is a diagonal matrix containing the top `no` singular values on the diagonal. +#' +#' For directed graphs the embedding is defined as the pair \eqn{X=U^{no}D^{1/2}}{U[no] sqrt(D[no])} and \eqn{Y=V^{no}D^{1/2}}{V[no] #' sqrt(D[no])}. (For undirected graphs \eqn{U=V}, so it is enough to keep one #' of them.) #' #' @param graph The input graph, directed or undirected. -#' @param no An integer scalar. This value is the embedding dimension of the -#' spectral embedding. Should be smaller than the number of vertices. The -#' largest `no`-dimensional non-zero singular values are used for the -#' spectral embedding. +#' @param no An integer scalar. +#' This value is the embedding dimension of the spectral embedding. +#' Should be smaller than the number of vertices. +#' The largest `no`-dimensional non-zero singular values are used for the spectral embedding. #' @inheritParams rlang::args_dots_empty -#' @param weights Optional positive weight vector for calculating a weighted -#' embedding. If the graph has a `weight` edge attribute, then this is -#' used by default. In a weighted embedding, the edge weights are used instead -#' of the binary adjacencny matrix. -#' @param which Which eigenvalues (or singular values, for directed graphs) to -#' use. \sQuote{lm} means the ones with the largest magnitude, \sQuote{la} is -#' the ones (algebraic) largest, and \sQuote{sa} is the (algebraic) smallest -#' eigenvalues. The default is \sQuote{lm}. Note that for directed graphs -#' \sQuote{la} and \sQuote{lm} are the equivalent, because the singular values -#' are used for the ordering. -#' @param scaled Logical, if `FALSE`, then \eqn{U} and \eqn{V} are -#' returned instead of \eqn{X} and \eqn{Y}. -#' @param cvec A numeric vector, its length is the number vertices in the -#' graph. This vector is added to the diagonal of the adjacency matrix. The -#' default `NULL` uses -#' `strength(graph, weights = weights) / (vcount(graph) - 1)`. -#' @param options A named list containing the parameters for the SVD -#' computation algorithm in ARPACK. The default `NULL` uses the values given -#' by [arpack_defaults()]. +#' @param weights Optional positive weight vector for calculating a weighted embedding. +#' If the graph has a `weight` edge attribute, then this is used by default. +#' In a weighted embedding, the edge weights are used instead of the binary adjacencny matrix. +#' @param which Which eigenvalues (or singular values, for directed graphs) to use. +#' \sQuote{lm} means the ones with the largest magnitude, \sQuote{la} is the ones (algebraic) largest, +#' and \sQuote{sa} is the (algebraic) smallest eigenvalues. +#' The default is \sQuote{lm}. +#' Note that for directed graphs \sQuote{la} and \sQuote{lm} are the equivalent, because the singular values are used for the ordering. +#' @param scaled Logical, if `FALSE`, then \eqn{U} and \eqn{V} are returned instead of \eqn{X} and \eqn{Y}. +#' @param cvec A numeric vector, its length is the number vertices in the graph. +#' This vector is added to the diagonal of the adjacency matrix. +#' The default `NULL` uses `strength(graph, weights = weights) / (vcount(graph) - 1)`. +#' @param options A named list containing the parameters for the SVD computation algorithm in ARPACK. +#' The default `NULL` uses the values given by [arpack_defaults()]. #' @return A list containing with entries: #' \describe{ #' \item{X}{ @@ -84,8 +74,8 @@ #' or the singular values (for directed graphs) calculated by the algorithm. #' } #' \item{options}{ -#' A named list, information about the underlying ARPACK -#' computation. See [arpack()] for the details. +#' A named list, information about the underlying ARPACK computation. +#' See [arpack()] for the details. #' } #' } #' @seealso [sample_dot_product()] @@ -180,24 +170,19 @@ embed_adjacency_matrix <- function( #' Dimensionality selection for singular values using profile likelihood. #' -#' Select the number of significant singular values, by finding the -#' \sQuote{elbow} of the scree plot, in a principled way. +#' Select the number of significant singular values, by finding the \sQuote{elbow} of the scree plot, in a principled way. #' -#' The input of the function is a numeric vector which contains the measure of -#' \sQuote{importance} for each dimension. +#' The input of the function is a numeric vector which contains the measure of \sQuote{importance} for each dimension. #' -#' For spectral embedding, these are the singular values of the adjacency -#' matrix. The singular values are assumed to be generated from a Gaussian -#' mixture distribution with two components that have different means and same -#' variance. The dimensionality \eqn{d} is chosen to maximize the likelihood -#' when the \eqn{d} largest singular values are assigned to one component of -#' the mixture and the rest of the singular values assigned to the other -#' component. +#' For spectral embedding, these are the singular values of the adjacency matrix. +#' The singular values are assumed to be generated from a Gaussian mixture distribution with two components that have different means and same variance. +#' The dimensionality \eqn{d} is chosen to maximize the likelihood +#' when the \eqn{d} largest singular values are assigned to one component of the mixture and the rest of the singular values assigned to the other component. #' -#' This function can also be used for the general separation problem, where we -#' assume that the left and the right of the vector are coming from two Normal -#' distributions, with different means, and we want to know their border. See -#' examples below. +#' This function can also be used for the general separation problem, +#' where we assume that the left and the right of the vector are coming from two Normal distributions, with different means, +#' and we want to know their border. +#' See examples below. #' #' @param sv A numeric vector, the ordered singular values. #' @return A numeric scalar, the estimate of \eqn{d}. @@ -247,53 +232,43 @@ dim_select <- function(sv) { #' #' Spectral decomposition of Laplacian matrices of graphs. #' -#' This function computes a `no`-dimensional Euclidean representation of -#' the graph based on its Laplacian matrix, \eqn{L}. This representation is -#' computed via the singular value decomposition of the Laplacian matrix. +#' This function computes a `no`-dimensional Euclidean representation of the graph based on its Laplacian matrix, \eqn{L}. +#' This representation is computed via the singular value decomposition of the Laplacian matrix. #' #' They are essentially doing the same as [embed_adjacency_matrix()], #' but work on the Laplacian matrix, instead of the adjacency matrix. #' #' @param graph The input graph, directed or undirected. -#' @param no An integer scalar. This value is the embedding dimension of the -#' spectral embedding. Should be smaller than the number of vertices. The -#' largest `no`-dimensional non-zero singular values are used for the -#' spectral embedding. +#' @param no An integer scalar. +#' This value is the embedding dimension of the spectral embedding. +#' Should be smaller than the number of vertices. +#' The largest `no`-dimensional non-zero singular values are used for the spectral embedding. #' @inheritParams rlang::args_dots_empty -#' @param weights Optional positive weight vector for calculating a weighted -#' embedding. If the graph has a `weight` edge attribute, then this is -#' used by default. For weighted embedding, edge weights are used instead -#' of the binary adjacency matrix, and vertex strength (see -#' [strength()]) is used instead of the degrees. -#' @param which Which eigenvalues (or singular values, for directed graphs) to -#' use. \sQuote{lm} means the ones with the largest magnitude, \sQuote{la} is -#' the ones (algebraic) largest, and \sQuote{sa} is the (algebraic) smallest -#' eigenvalues. The default is \sQuote{lm}. Note that for directed graphs -#' \sQuote{la} and \sQuote{lm} are the equivalent, because the singular values -#' are used for the ordering. -#' @param type The type of the Laplacian to use. Various definitions exist for -#' the Laplacian of a graph, and one can choose between them with this -#' argument. -#' -#' Possible values: `D-A` means \eqn{D-A} where \eqn{D} is the degree -#' matrix and \eqn{A} is the adjacency matrix; `DAD` means -#' \eqn{D^{1/2}}{D^1/2} times \eqn{A} times \eqn{D^{1/2}{D^1/2}}, -#' \eqn{D^{1/2}}{D^1/2} is the inverse of the square root of the degree matrix; -#' `I-DAD` means \eqn{I-D^{1/2}}{I-D^1/2}, where \eqn{I} is the identity -#' matrix. `OAP` is \eqn{O^{1/2}AP^{1/2}}{O^1/2 A P^1/2}, where -#' \eqn{O^{1/2}}{O^1/2} is the inverse of the square root of the out-degree -#' matrix and \eqn{P^{1/2}}{P^1/2} is the same for the in-degree matrix. -#' -#' `OAP` is not defined for undirected graphs, and is the only defined type -#' for directed graphs. -#' -#' The default (i.e. type `default`) is to use `D-A` for undirected -#' graphs and `OAP` for directed graphs. -#' @param scaled Logical, if `FALSE`, then \eqn{U} and \eqn{V} are -#' returned instead of \eqn{X} and \eqn{Y}. -#' @param options A named list containing the parameters for the SVD -#' computation algorithm in ARPACK. The default `NULL` uses the values given -#' by [arpack_defaults()]. +#' @param weights Optional positive weight vector for calculating a weighted embedding. +#' If the graph has a `weight` edge attribute, then this is used by default. +#' For weighted embedding, edge weights are used instead of the binary adjacency matrix, +#' and vertex strength (see [strength()]) is used instead of the degrees. +#' @param which Which eigenvalues (or singular values, for directed graphs) to use. +#' \sQuote{lm} means the ones with the largest magnitude, \sQuote{la} is the ones (algebraic) largest, +#' and \sQuote{sa} is the (algebraic) smallest eigenvalues. +#' The default is \sQuote{lm}. +#' Note that for directed graphs \sQuote{la} and \sQuote{lm} are the equivalent, because the singular values are used for the ordering. +#' @param type The type of the Laplacian to use. +#' Various definitions exist for the Laplacian of a graph, and one can choose between them with this argument. +#' +#' Possible values: `D-A` means \eqn{D-A} where \eqn{D} is the degree matrix and \eqn{A} is the adjacency matrix; +#' `DAD` means \eqn{D^{1/2}}{D^1/2} times \eqn{A} times \eqn{D^{1/2}{D^1/2}}, +#' \eqn{D^{1/2}}{D^1/2} is the inverse of the square root of the degree matrix; `I-DAD` means \eqn{I-D^{1/2}}{I-D^1/2}, +#' where \eqn{I} is the identity matrix. +#' `OAP` is \eqn{O^{1/2}AP^{1/2}}{O^1/2 A P^1/2}, +#' where \eqn{O^{1/2}}{O^1/2} is the inverse of the square root of the out-degree matrix and \eqn{P^{1/2}}{P^1/2} is the same for the in-degree matrix. +#' +#' `OAP` is not defined for undirected graphs, and is the only defined type for directed graphs. +#' +#' The default (i.e. type `default`) is to use `D-A` for undirected graphs and `OAP` for directed graphs. +#' @param scaled Logical, if `FALSE`, then \eqn{U} and \eqn{V} are returned instead of \eqn{X} and \eqn{Y}. +#' @param options A named list containing the parameters for the SVD computation algorithm in ARPACK. +#' The default `NULL` uses the values given by [arpack_defaults()]. #' @return A list containing with entries: #' \describe{ #' \item{X}{ @@ -310,8 +285,8 @@ dim_select <- function(sv) { #' or the singular values (for directed graphs) calculated by the algorithm. #' } #' \item{options}{ -#' A named list, information about the underlying ARPACK -#' computation. See [arpack()] for the details. +#' A named list, information about the underlying ARPACK computation. +#' See [arpack()] for the details. #' } #' } #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} @@ -405,22 +380,17 @@ embed_laplacian_matrix <- function( #' Sample vectors uniformly from the surface of a sphere #' -#' Sample finite-dimensional vectors to use as latent position vectors in -#' random dot product graphs +#' Sample finite-dimensional vectors to use as latent position vectors in random dot product graphs #' -#' `sample_sphere_surface()` generates uniform samples from \eqn{S^{dim-1}} -#' (the `(dim-1)`-sphere) with radius `radius`, i.e. the Euclidean -#' norm of the samples equal `radius`. +#' `sample_sphere_surface()` generates uniform samples from \eqn{S^{dim-1}} (the `(dim-1)`-sphere) with radius `radius`, +#' i.e. the Euclidean norm of the samples equal `radius`. #' #' @param dim Integer scalar, the dimension of the random vectors. #' @param n Integer scalar, the sample size. #' @inheritParams rlang::args_dots_empty #' @param radius Numeric scalar, the radius of the sphere to sample. -#' @param positive Logical, whether to sample from the positive orthant -#' of the sphere. -#' @return A `dim` (length of the `alpha` vector for -#' `sample_dirichlet()`) times `n` matrix, whose columns are the sample -#' vectors. +#' @param positive Logical, whether to sample from the positive orthant of the sphere. +#' @return A `dim` (length of the `alpha` vector for `sample_dirichlet()`) times `n` matrix, whose columns are the sample vectors. #' #' @family latent position vector samplers #' @@ -487,22 +457,16 @@ sample_sphere_surface <- function( #' Sample vectors uniformly from the volume of a sphere #' -#' Sample finite-dimensional vectors to use as latent position vectors in -#' random dot product graphs +#' Sample finite-dimensional vectors to use as latent position vectors in random dot product graphs #' -#' `sample_sphere_volume()` generates uniform samples from \eqn{S^{dim-1}} -#' (the `(dim-1)`-sphere) i.e. the Euclidean norm of the samples is -#' smaller or equal to `radius`. +#' `sample_sphere_volume()` generates uniform samples from \eqn{S^{dim-1}} (the `(dim-1)`-sphere) i.e. the Euclidean norm of the samples is smaller or equal to `radius`. #' #' @param dim Integer scalar, the dimension of the random vectors. #' @param n Integer scalar, the sample size. #' @inheritParams rlang::args_dots_empty #' @param radius Numeric scalar, the radius of the sphere to sample. -#' @param positive Logical, whether to sample from the positive orthant -#' of the sphere. -#' @return A `dim` (length of the `alpha` vector for -#' `sample_dirichlet()`) times `n` matrix, whose columns are the sample -#' vectors. +#' @param positive Logical, whether to sample from the positive orthant of the sphere. +#' @return A `dim` (length of the `alpha` vector for `sample_dirichlet()`) times `n` matrix, whose columns are the sample vectors. #' #' @family latent position vector samplers #' @@ -569,19 +533,14 @@ sample_sphere_volume <- function( #' Sample from a Dirichlet distribution #' -#' Sample finite-dimensional vectors to use as latent position vectors in -#' random dot product graphs +#' Sample finite-dimensional vectors to use as latent position vectors in random dot product graphs #' -#' `sample_dirichlet()` generates samples from the Dirichlet distribution -#' with given \eqn{\alpha}{alpha} parameter. The sample is drawn from -#' `length(alpha)-1`-simplex. +#' `sample_dirichlet()` generates samples from the Dirichlet distribution with given \eqn{\alpha}{alpha} parameter. +#' The sample is drawn from `length(alpha)-1`-simplex. #' #' @param n Integer scalar, the sample size. -#' @param alpha Numeric vector, the vector of \eqn{\alpha}{alpha} parameter for -#' the Dirichlet distribution. -#' @return A `dim` (length of the `alpha` vector for -#' `sample_dirichlet()`) times `n` matrix, whose columns are the sample -#' vectors. +#' @param alpha Numeric vector, the vector of \eqn{\alpha}{alpha} parameter for the Dirichlet distribution. +#' @return A `dim` (length of the `alpha` vector for `sample_dirichlet()`) times `n` matrix, whose columns are the sample vectors. #' #' @family latent position vector samplers #' diff --git a/R/env-and-data.R b/R/env-and-data.R index 305eb66cded..03d2a3ccf4c 100644 --- a/R/env-and-data.R +++ b/R/env-and-data.R @@ -2,24 +2,20 @@ #' #' @description #' -#' The `.data` and `.env` pronouns make it explicit where to look up attribute -#' names when indexing `V(g)` or `E(g)`, i.e. the vertex or edge sequence of a -#' graph. These pronouns are inspired by `.data` and `.env` in `rlang` - thanks -#' to Michał Bojanowski for bringing these to our attention. +#' The `.data` and `.env` pronouns make it explicit where to look up attribute names when indexing `V(g)` or `E(g)`, +#' i.e. the vertex or edge sequence of a graph. +#' These pronouns are inspired by `.data` and `.env` in `rlang` - thanks to Michał Bojanowski for bringing these to our attention. #' #' The rules are simple: #' -#' * `.data` retrieves attributes from the graph whose vertex or edge sequence -#' is being evaluated. +#' * `.data` retrieves attributes from the graph whose vertex or edge sequence is being evaluated. #' * `.env` retrieves variables from the calling environment. #' -#' Note that `.data` and `.env` are injected dynamically into the environment -#' where the indexing expressions are evaluated; you cannot get access to these -#' objects outside the context of an indexing expression. To avoid warnings -#' printed by `R CMD check` when code containing `.data` and `.env` is checked, -#' you can import `.data` and `.env` from `igraph` if needed. Alternatively, -#' you can declare them explicitly with `utils::globalVariables()` to silence -#' the warnings. +#' Note that `.data` and `.env` are injected dynamically into the environment where the indexing expressions are evaluated; +#' you cannot get access to these objects outside the context of an indexing expression. +#' To avoid warnings printed by `R CMD check` when code containing `.data` and `.env` is checked, +#' you can import `.data` and `.env` from `igraph` if needed. +#' Alternatively, you can declare them explicitly with `utils::globalVariables()` to silence the warnings. #' #' @name dot-data #' @aliases dot-env diff --git a/R/epi.R b/R/epi.R index 450d57aa50e..4174913ea98 100644 --- a/R/epi.R +++ b/R/epi.R @@ -134,34 +134,30 @@ quantile.sir <- function(x, comp = c("NI", "NS", "NR"), prob, ...) { #' Plotting the results on multiple SIR model runs #' -#' This function can conveniently plot the results of multiple SIR model -#' simulations. +#' This function can conveniently plot the results of multiple SIR model simulations. #' -#' The number of susceptible/infected/recovered individuals is plotted over -#' time, for multiple simulations. +#' The number of susceptible/infected/recovered individuals is plotted over time, for multiple simulations. #' -#' @param x The output of the SIR simulation, coming from the [sir()] -#' function. -#' @param comp Character scalar, which component to plot. Either \sQuote{NI} -#' (infected, default), \sQuote{NS} (susceptible) or \sQuote{NR} (recovered). +#' @param x The output of the SIR simulation, coming from the [sir()] function. +#' @param comp Character scalar, which component to plot. +#' Either \sQuote{NI} (infected, default), \sQuote{NS} (susceptible) or \sQuote{NR} (recovered). #' @param median Logical, whether to plot the (binned) median. #' @param quantiles A vector of (binned) quantiles to plot. #' @param color Color of the individual simulation curves. #' @param median_color Color of the median curve. -#' @param quantile_color Color(s) of the quantile curves. (It is recycled if -#' needed and non-needed entries are ignored if too long.) +#' @param quantile_color Color(s) of the quantile curves. +#' (It is recycled if needed and non-needed entries are ignored if too long.) #' @param lwd.median Line width of the median. #' @param lwd.quantile Line width of the quantile curves. #' @param lty.quantile Line type of the quantile curves. -#' @param xlim The x limits, a two-element numeric vector. If `NULL`, then -#' it is calculated from the data. -#' @param ylim The y limits, a two-element numeric vector. If `NULL`, then -#' it is calculated from the data. +#' @param xlim The x limits, a two-element numeric vector. +#' If `NULL`, then it is calculated from the data. +#' @param ylim The y limits, a two-element numeric vector. +#' If `NULL`, then it is calculated from the data. #' @param xlab The x label. -#' @param ylab The y label. If `NULL` then it is automatically added based -#' on the `comp` argument. -#' @param \dots Additional arguments are passed to [plot()], that is run -#' before any of the curves are added, to create the figure. +#' @param ylab The y label. +#' If `NULL` then it is automatically added based on the `comp` argument. +#' @param \dots Additional arguments are passed to [plot()], that is run before any of the curves are added, to create the figure. #' @return Nothing. #' @author Eric Kolaczyk () and Gabor #' Csardi \email{csardi.gabor@@gmail.com}. diff --git a/R/eulerian.R b/R/eulerian.R index a8bef007d75..0b23a6ade4b 100644 --- a/R/eulerian.R +++ b/R/eulerian.R @@ -22,28 +22,24 @@ #' Find Eulerian paths or cycles in a graph #' -#' `has_eulerian_path()` and `has_eulerian_cycle()` checks whether there -#' is an Eulerian path or cycle in the input graph. `eulerian_path()` and -#' `eulerian_cycle()` return such a path or cycle if it exists, and throws -#' an error otherwise. +#' `has_eulerian_path()` and `has_eulerian_cycle()` checks whether there is an Eulerian path or cycle in the input graph. +#' `eulerian_path()` and `eulerian_cycle()` return such a path or cycle if it exists, and throws an error otherwise. #' -#' `has_eulerian_path()` decides whether the input graph has an Eulerian -#' *path*, i.e. a path that passes through every edge of the graph exactly -#' once, and returns a logical value as a result. `eulerian_path()` returns -#' a possible Eulerian path, described with its edge and vertex sequence, or -#' throws an error if no such path exists. +#' `has_eulerian_path()` decides whether the input graph has an Eulerian *path*, +#' i.e. a path that passes through every edge of the graph exactly once, and returns a logical value as a result. +#' `eulerian_path()` returns a possible Eulerian path, described with its edge and vertex sequence, +#' or throws an error if no such path exists. #' -#' `has_eulerian_cycle()` decides whether the input graph has an Eulerian -#' *cycle*, i.e. a path that passes through every edge of the graph exactly -#' once and that returns to its starting point, and returns a logical value as -#' a result. `eulerian_cycle()` returns a possible Eulerian cycle, described -#' with its edge and vertex sequence, or throws an error if no such cycle exists. +#' `has_eulerian_cycle()` decides whether the input graph has an Eulerian *cycle*, +#' i.e. a path that passes through every edge of the graph exactly once and that returns to its starting point, +#' and returns a logical value as a result. +#' `eulerian_cycle()` returns a possible Eulerian cycle, described with its edge and vertex sequence, +#' or throws an error if no such cycle exists. #' #' @param graph An igraph graph object -#' @return For `has_eulerian_path()` and `has_eulerian_cycle()`, a logical -#' value that indicates whether the graph contains an Eulerian path or cycle. -#' For `eulerian_path()` and `eulerian_cycle()`, a named list with two -#' entries: +#' @return For `has_eulerian_path()` and `has_eulerian_cycle()`, +#' a logical value that indicates whether the graph contains an Eulerian path or cycle. +#' For `eulerian_path()` and `eulerian_cycle()`, a named list with two entries: #' \describe{ #' \item{epath}{ #' A vector containing the edge IDs along the Eulerian path or cycle. diff --git a/R/fit.R b/R/fit.R index 1fc974f4ee7..dff09539b74 100644 --- a/R/fit.R +++ b/R/fit.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `power.law.fit()` was renamed to [fit_power_law()] to create a more -#' consistent API. +#' `power.law.fit()` was renamed to [fit_power_law()] to create a more consistent API. #' @inheritParams fit_power_law #' @keywords internal #' @export @@ -57,77 +56,69 @@ power.law.fit <- function( #' #' `fit_power_law()` fits a power-law distribution to a data set. #' -#' This function fits a power-law distribution to a vector containing samples -#' from a distribution (that is assumed to follow a power-law of course). In a -#' power-law distribution, it is generally assumed that \eqn{P(X=x)} is -#' proportional to \eqn{x^{-\alpha}}{x^-alpha}, where \eqn{x} is a positive -#' number and \eqn{\alpha}{alpha} is greater than 1. In many real-world cases, -#' the power-law behaviour kicks in only above a threshold value -#' \eqn{x_\text{min}}{xmin}. The goal of this function is to determine -#' \eqn{\alpha}{alpha} if \eqn{x_\text{min}}{xmin} is given, or to determine -#' \eqn{x_\text{min}}{xmin} and the corresponding value of \eqn{\alpha}{alpha}. +#' This function fits a power-law distribution to a vector containing samples from a distribution (that is assumed to follow a power-law of course). +#' In a power-law distribution, it is generally assumed that \eqn{P(X=x)} is proportional to \eqn{x^{-\alpha}}{x^-alpha}, +#' where \eqn{x} is a positive number and \eqn{\alpha}{alpha} is greater than 1. In many real-world cases, +#' the power-law behaviour kicks in only above a threshold value \eqn{x_\text{min}}{xmin}. +#' The goal of this function is to determine \eqn{\alpha}{alpha} if \eqn{x_\text{min}}{xmin} is given, +#' or to determine \eqn{x_\text{min}}{xmin} and the corresponding value of \eqn{\alpha}{alpha}. #' -#' `fit_power_law()` provides two maximum likelihood implementations. If -#' the `implementation` argument is \sQuote{`R.mle`}, then the BFGS -#' optimization (see [stats4::mle()]) algorithm is applied. The additional -#' arguments are passed to the mle function, so it is possible to change the -#' optimization method and/or its parameters. This implementation can -#' *not* to fit the \eqn{x_\text{min}}{xmin} argument, so use the -#' \sQuote{`plfit`} implementation if you want to do that. +#' `fit_power_law()` provides two maximum likelihood implementations. +#' If the `implementation` argument is \sQuote{`R.mle`}, +#' then the BFGS optimization (see [stats4::mle()]) algorithm is applied. +#' The additional arguments are passed to the mle function, +#' so it is possible to change the optimization method and/or its parameters. +#' This implementation can *not* to fit the \eqn{x_\text{min}}{xmin} argument, +#' so use the \sQuote{`plfit`} implementation if you want to do that. #' -#' The \sQuote{`plfit`} implementation also uses the maximum likelihood -#' principle to determine \eqn{\alpha}{alpha} for a given \eqn{x_\text{min}}{xmin}; -#' When \eqn{x_\text{min}}{xmin} is not given in advance, the algorithm will attempt -#' to find its optimal value for which the \eqn{p}-value of a Kolmogorov-Smirnov -#' test between the fitted distribution and the original sample is the largest. -#' The function uses the method of Clauset, Shalizi and Newman to calculate the -#' parameters of the fitted distribution. See references below for the details. +#' The \sQuote{`plfit`} implementation also uses the maximum likelihood principle to determine \eqn{\alpha}{alpha} for a given \eqn{x_\text{min}}{xmin}; +#' When \eqn{x_\text{min}}{xmin} is not given in advance, +#' the algorithm will attempt to find its optimal value for which the \eqn{p}-value of a Kolmogorov-Smirnov test between the fitted distribution and the original sample is the largest. +#' The function uses the method of Clauset, Shalizi and Newman to calculate the parameters of the fitted distribution. +#' See references below for the details. #' #' `r lifecycle::badge("experimental")` #' #' Pass `p.value = TRUE` to include the p-value in the output. #' This is not returned by default because the computation may be slow. #' -#' @param x The data to fit, a numeric vector. For implementation -#' \sQuote{`R.mle`} the data must be integer values. For the -#' \sQuote{`plfit`} implementation non-integer values might be present and -#' then a continuous power-law distribution is fitted. -#' @param xmin Numeric scalar, or `NULL`. The lower bound for fitting the -#' power-law. If `NULL`, the smallest value in `x` will be used for -#' the \sQuote{`R.mle`} implementation, and its value will be -#' automatically determined for the \sQuote{`plfit`} implementation. This -#' argument makes it possible to fit only the tail of the distribution. -#' @param start Numeric scalar. The initial value of the exponent for the -#' minimizing function, for the \sQuote{`R.mle`} implementation. Usually -#' it is safe to leave this untouched. -#' @param force.continuous Logical. Whether to force a continuous -#' distribution for the \sQuote{`plfit`} implementation, even if the -#' sample vector contains integer values only (by chance). If this argument is -#' false, igraph will assume a continuous distribution if at least one sample -#' is non-integer and assume a discrete distribution otherwise. +#' @param x The data to fit, a numeric vector. +#' For implementation \sQuote{`R.mle`} the data must be integer values. +#' For the \sQuote{`plfit`} implementation non-integer values might be present and then a continuous power-law distribution is fitted. +#' @param xmin Numeric scalar, or `NULL`. +#' The lower bound for fitting the power-law. +#' If `NULL`, the smallest value in `x` will be used for the \sQuote{`R.mle`} implementation, +#' and its value will be automatically determined for the \sQuote{`plfit`} implementation. +#' This argument makes it possible to fit only the tail of the distribution. +#' @param start Numeric scalar. +#' The initial value of the exponent for the minimizing function, for the \sQuote{`R.mle`} implementation. +#' Usually it is safe to leave this untouched. +#' @param force.continuous Logical. +#' Whether to force a continuous distribution for the \sQuote{`plfit`} implementation, +#' even if the sample vector contains integer values only (by chance). +#' If this argument is false, +#' igraph will assume a continuous distribution if at least one sample is non-integer and assume a discrete distribution otherwise. #' @param p.value `r lifecycle::badge("experimental")` #' #' Set to `TRUE` to compute the p-value with `implementation = "plfit"`. #' @param p.precision `r lifecycle::badge("experimental")` #' -#' The desired precision of the p-value calculation. The -#' precision ultimately depends on the number of resampling attempts. The -#' number of resampling trials is determined by 0.25 divided by the square -#' of the required precision. For instance, a required precision of 0.01 -#' means that 2500 samples will be drawn. -#' @param implementation Character scalar. Which implementation to use. See -#' details below. -#' @param \dots Additional arguments, passed to the maximum likelihood -#' optimizing function, [stats4::mle()], if the \sQuote{`R.mle`} -#' implementation is chosen. It is ignored by the \sQuote{`plfit`} -#' implementation. -#' @return Depends on the `implementation` argument. If it is -#' \sQuote{`R.mle`}, then an object with class \sQuote{`mle`}. It can -#' be used to calculate confidence intervals and log-likelihood. See -#' [stats4::mle-class()] for details. +#' The desired precision of the p-value calculation. +#' The precision ultimately depends on the number of resampling attempts. +#' The number of resampling trials is determined by 0.25 divided by the square of the required precision. +#' For instance, a required precision of 0.01 means that 2500 samples will be drawn. +#' @param implementation Character scalar. +#' Which implementation to use. +#' See details below. +#' @param \dots Additional arguments, passed to the maximum likelihood optimizing function, [stats4::mle()], +#' if the \sQuote{`R.mle`} implementation is chosen. +#' It is ignored by the \sQuote{`plfit`} implementation. +#' @return Depends on the `implementation` argument. +#' If it is \sQuote{`R.mle`}, then an object with class \sQuote{`mle`}. +#' It can be used to calculate confidence intervals and log-likelihood. +#' See [stats4::mle-class()] for details. #' -#' If `implementation` is \sQuote{`plfit`}, then the result is a -#' named list with entries: +#' If `implementation` is \sQuote{`plfit`}, then the result is a named list with entries: #' \describe{ #' \item{continuous}{ #' Logical, whether the @@ -137,9 +128,8 @@ power.law.fit <- function( #' Numeric scalar, the exponent of the fitted power-law distribution. #' } #' \item{xmin}{ -#' Numeric scalar, the minimum value from which the -#' power-law distribution was fitted. In other words, only the values larger -#' than `xmin` were used from the input vector. +#' Numeric scalar, the minimum value from which the power-law distribution was fitted. +#' In other words, only the values larger than `xmin` were used from the input vector. #' } #' \item{logLik}{ #' Numeric scalar, the log-likelihood of the fitted parameters. @@ -150,10 +140,10 @@ power.law.fit <- function( #' Smaller scores denote better fit. #' } #' \item{KS.p}{ -#' Only for `p.value = TRUE`. Numeric scalar, the p-value of the Kolmogorov-Smirnov -#' test. Small p-values (less than 0.05) indicate that the test rejected the -#' hypothesis that the original data could have been drawn from the fitted -#' power-law distribution. +#' Only for `p.value = TRUE`. +#' Numeric scalar, the p-value of the Kolmogorov-Smirnov test. +#' Small p-values (less than 0.05) indicate that the test rejected the hypothesis +#' that the original data could have been drawn from the fitted power-law distribution. #' } #' } #' @author Tamas Nepusz \email{ntamas@@gmail.com} and Gabor Csardi diff --git a/R/flow.R b/R/flow.R index 6f185ca6b83..1bd7061e2ab 100644 --- a/R/flow.R +++ b/R/flow.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `vertex.disjoint.paths()` was renamed to [vertex_disjoint_paths()] to create a more -#' consistent API. +#' `vertex.disjoint.paths()` was renamed to [vertex_disjoint_paths()] to create a more consistent API. #' @inheritParams vertex_disjoint_paths #' @keywords internal #' @export @@ -23,8 +22,7 @@ vertex.disjoint.paths <- function(graph, source = NULL, target = NULL) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `vertex.connectivity()` was renamed to [vertex_connectivity()] to create a more -#' consistent API. +#' `vertex.connectivity()` was renamed to [vertex_connectivity()] to create a more consistent API. #' @inheritParams vertex_connectivity #' @keywords internal #' @export @@ -53,8 +51,7 @@ vertex.connectivity <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `stMincuts()` was renamed to [st_min_cuts()] to create a more -#' consistent API. +#' `stMincuts()` was renamed to [st_min_cuts()] to create a more consistent API. #' @inheritParams st_min_cuts #' @keywords internal #' @export @@ -74,8 +71,7 @@ stMincuts <- function(graph, source, target, capacity = NULL) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `stCuts()` was renamed to [st_cuts()] to create a more -#' consistent API. +#' `stCuts()` was renamed to [st_cuts()] to create a more consistent API. #' @inheritParams st_cuts #' @keywords internal #' @export @@ -90,8 +86,7 @@ stCuts <- function(graph, source, target) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `minimum.size.separators()` was renamed to [min_separators()] to create a more -#' consistent API. +#' `minimum.size.separators()` was renamed to [min_separators()] to create a more consistent API. #' @inheritParams min_separators #' @keywords internal #' @export @@ -110,8 +105,7 @@ minimum.size.separators <- function(graph) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `minimal.st.separators()` was renamed to [min_st_separators()] to create a more -#' consistent API. +#' `minimal.st.separators()` was renamed to [min_st_separators()] to create a more consistent API. #' @inheritParams min_st_separators #' @keywords internal #' @export @@ -130,8 +124,7 @@ minimal.st.separators <- function(graph) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `is.separator()` was renamed to [is_separator()] to create a more -#' consistent API. +#' `is.separator()` was renamed to [is_separator()] to create a more consistent API. #' @inheritParams is_separator #' @keywords internal #' @export @@ -146,8 +139,7 @@ is.separator <- function(graph, candidate) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `is.minimal.separator()` was renamed to [is_min_separator()] to create a more -#' consistent API. +#' `is.minimal.separator()` was renamed to [is_min_separator()] to create a more consistent API. #' @inheritParams is_min_separator #' @keywords internal #' @export @@ -166,8 +158,7 @@ is.minimal.separator <- function(graph, candidate) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.mincut()` was renamed to [min_cut()] to create a more -#' consistent API. +#' `graph.mincut()` was renamed to [min_cut()] to create a more consistent API. #' @inheritParams min_cut #' @keywords internal #' @export @@ -194,8 +185,7 @@ graph.mincut <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.maxflow()` was renamed to [max_flow()] to create a more -#' consistent API. +#' `graph.maxflow()` was renamed to [max_flow()] to create a more consistent API. #' @inheritParams max_flow #' @keywords internal #' @export @@ -210,8 +200,7 @@ graph.maxflow <- function(graph, source, target, capacity = NULL) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.adhesion()` was renamed to [adhesion()] to create a more -#' consistent API. +#' `graph.adhesion()` was renamed to [adhesion()] to create a more consistent API. #' @inheritParams adhesion #' @keywords internal #' @export @@ -226,8 +215,7 @@ graph.adhesion <- function(graph, checks = TRUE) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `edge.disjoint.paths()` was renamed to [edge_connectivity()] to create a more -#' consistent API. +#' `edge.disjoint.paths()` was renamed to [edge_connectivity()] to create a more consistent API. #' @inheritParams edge_connectivity #' @keywords internal #' @export @@ -256,8 +244,7 @@ edge.disjoint.paths <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `edge.connectivity()` was renamed to [edge_connectivity()] to create a more -#' consistent API. +#' `edge.connectivity()` was renamed to [edge_connectivity()] to create a more consistent API. #' @inheritParams edge_connectivity #' @keywords internal #' @export @@ -286,8 +273,7 @@ edge.connectivity <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `dominator.tree()` was renamed to [dominator_tree()] to create a more -#' consistent API. +#' `dominator.tree()` was renamed to [dominator_tree()] to create a more consistent API. #' @inheritParams dominator_tree #' @keywords internal #' @export @@ -319,39 +305,29 @@ dominator.tree <- function(graph, root, mode = c("out", "in", "all", "total")) { #' Minimum cut in a graph #' -#' `min_cut()` calculates the minimum st-cut between two vertices in a graph -#' (if the `source` and `target` arguments are given) or the minimum -#' cut of the graph (if both `source` and `target` are `NULL`). +#' `min_cut()` calculates the minimum st-cut between two vertices in a graph (if the `source` and `target` arguments are given) or the minimum cut of the graph (if both `source` and `target` are `NULL`). #' -#' The minimum st-cut between `source` and `target` is the minimum -#' total weight of edges needed to remove to eliminate all paths from -#' `source` to `target`. +#' The minimum st-cut between `source` and `target` is the minimum total weight of edges needed to remove to eliminate all paths from `source` to `target`. #' -#' The minimum cut of a graph is the minimum total weight of the edges needed -#' to remove to separate the graph into (at least) two components. (Which is to -#' make the graph *not* strongly connected in the directed case.) +#' The minimum cut of a graph is the minimum total weight of the edges needed to remove to separate the graph into (at least) two components. +#' (Which is to make the graph *not* strongly connected in the directed case.) #' -#' The maximum flow between two vertices in a graph is the same as the minimum -#' st-cut, so `max_flow()` and `min_cut()` essentially calculate the same -#' quantity, the only difference is that `min_cut()` can be invoked without -#' giving the `source` and `target` arguments and then minimum of all -#' possible minimum cuts is calculated. +#' The maximum flow between two vertices in a graph is the same as the minimum st-cut, +#' so `max_flow()` and `min_cut()` essentially calculate the same quantity, +#' the only difference is that `min_cut()` can be invoked without giving the `source` and `target` arguments and then minimum of all possible minimum cuts is calculated. #' -#' For undirected graphs the Stoer-Wagner algorithm (see reference below) is -#' used to calculate the minimum cut. +#' For undirected graphs the Stoer-Wagner algorithm (see reference below) is used to calculate the minimum cut. #' #' @param graph The input graph. #' @param source The ID of the source vertex. #' @param target The ID of the target vertex (sometimes also called sink). #' @inheritParams rlang::args_dots_empty -#' @param capacity Vector giving the capacity of the edges. If this is -#' `NULL` (the default) then the `capacity` edge attribute is used. -#' @param value.only Logical, if `TRUE` only the minimum cut value -#' is returned, if `FALSE` the edges in the cut and a the two (or more) -#' partitions are also returned. -#' @return For `min_cut()` a nuieric constant, the value of the minimum -#' cut, except if `value.only = FALSE`. In this case a named list with -#' components: +#' @param capacity Vector giving the capacity of the edges. +#' If this is `NULL` (the default) then the `capacity` edge attribute is used. +#' @param value.only Logical, if `TRUE` only the minimum cut value is returned, +#' if `FALSE` the edges in the cut and a the two (or more) partitions are also returned. +#' @return For `min_cut()` a nuieric constant, the value of the minimum cut, except if `value.only = FALSE`. +#' In this case a named list with components: #' \describe{ #' \item{value}{ #' Numeric scalar, the cut value. @@ -478,59 +454,41 @@ min_cut <- function( #' Vertex connectivity #' -#' The vertex connectivity of a graph or two vertices, this is recently also -#' called group cohesion. -#' -#' The vertex connectivity of two vertices (`source` and `target`) in -#' a graph is the minimum number of vertices that must be deleted to -#' eliminate all (directed) paths from `source` to `target`. -#' `vertex_connectivity()` calculates this quantity if both the -#' `source` and `target` arguments are given and they're not -#' `NULL`. -#' -#' The vertex connectivity of a pair is the same as the number -#' of different (i.e. node-independent) paths from source to -#' target, assuming no direct edges between them. -#' -#' The vertex connectivity of a graph is the minimum vertex connectivity of all -#' (ordered) pairs of vertices in the graph. In other words this is the minimum -#' number of vertices needed to remove to make the graph not strongly -#' connected. (If the graph is not strongly connected then this is zero.) -#' `vertex_connectivity()` calculates this quantity if neither the -#' `source` nor `target` arguments are given. (I.e. they are both -#' `NULL`.) -#' -#' A set of vertex disjoint directed paths from `source` to `vertex` -#' is a set of directed paths between them whose vertices do not contain common -#' vertices (apart from `source` and `target`). The maximum number of -#' vertex disjoint paths between two vertices is the same as their vertex -#' connectivity in most cases (if the two vertices are not connected by an -#' edge). -#' -#' The cohesion of a graph (as defined by White and Harary, see references), is -#' the vertex connectivity of the graph. This is calculated by -#' `cohesion()`. -#' -#' These three functions essentially calculate the same measure(s), more -#' precisely `vertex_connectivity()` is the most general, the other two are -#' included only for the ease of using more descriptive function names. +#' The vertex connectivity of a graph or two vertices, this is recently also called group cohesion. +#' +#' The vertex connectivity of two vertices (`source` and `target`) in a graph is the minimum number of vertices that must be deleted to eliminate all (directed) paths from `source` to `target`. +#' `vertex_connectivity()` calculates this quantity if both the `source` and `target` arguments are given and they're not `NULL`. +#' +#' The vertex connectivity of a pair is the same as the number of different (i.e. node-independent) paths from source to target, +#' assuming no direct edges between them. +#' +#' The vertex connectivity of a graph is the minimum vertex connectivity of all (ordered) pairs of vertices in the graph. +#' In other words this is the minimum number of vertices needed to remove to make the graph not strongly connected. +#' (If the graph is not strongly connected then this is zero.) +#' `vertex_connectivity()` calculates this quantity if neither the `source` nor `target` arguments are given. +#' (I.e. they are both `NULL`.) +#' +#' A set of vertex disjoint directed paths from `source` to `vertex` is a set of directed paths between them whose vertices do not contain common vertices (apart from `source` and `target`). +#' The maximum number of vertex disjoint paths between two vertices is the same as their vertex connectivity in most cases (if the two vertices are not connected by an edge). +#' +#' The cohesion of a graph (as defined by White and Harary, see references), is the vertex connectivity of the graph. +#' This is calculated by `cohesion()`. +#' +#' These three functions essentially calculate the same measure(s), more precisely `vertex_connectivity()` is the most general, +#' the other two are included only for the ease of using more descriptive function names. #' #' @aliases cohesion #' @param graph,x The input graph. -#' @param source The ID of the source vertex, for `vertex_connectivity()` it -#' can be `NULL`, see details below. -#' @param target The ID of the target vertex, for `vertex_connectivity()` it -#' can be `NULL`, see details below. -#' @param \dots For `vertex_connectivity()`, these dots must be empty. For -#' `cohesion()`, unused, present for S3 method consistency but may be used -#' by other methods that implement it. -#' @param checks Logical. Whether to check that the graph is connected -#' and also the degree of the vertices. If the graph is not (strongly) -#' connected then the connectivity is obviously zero. Otherwise if the minimum -#' degree is one then the vertex connectivity is also one. It is a good idea to -#' perform these checks, as they can be done quickly compared to the -#' connectivity calculation itself. They were suggested by Peter McMahan, -#' thanks Peter. +#' @param source The ID of the source vertex, for `vertex_connectivity()` it can be `NULL`, see details below. +#' @param target The ID of the target vertex, for `vertex_connectivity()` it can be `NULL`, see details below. +#' @param \dots For `vertex_connectivity()`, these dots must be empty. +#' For `cohesion()`, unused, present for S3 method consistency but may be used by other methods that implement it. +#' @param checks Logical. +#' Whether to check that the graph is connected and also the degree of the vertices. +#' If the graph is not (strongly) connected then the connectivity is obviously zero. +#' Otherwise if the minimum degree is one then the vertex connectivity is also one. +#' It is a good idea to perform these checks, as they can be done quickly compared to the connectivity calculation itself. +#' They were suggested by Peter McMahan, thanks Peter. #' @return A scalar real value. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @references White, Douglas R and Frank Harary 2001. The Cohesiveness of @@ -617,62 +575,48 @@ vertex_connectivity <- function( #' Edge connectivity #' -#' The edge connectivity of a graph or two vertices, this is recently also -#' called group adhesion. +#' The edge connectivity of a graph or two vertices, this is recently also called group adhesion. #' #' @section `edge_connectivity()` Edge connectivity: -#' The edge connectivity of a pair of vertices (`source` and -#' `target`) is the minimum number of edges needed to remove to eliminate -#' all (directed) paths from `source` to `target`. -#' `edge_connectivity()` calculates this quantity if both the `source` -#' and `target` arguments are given (and not `NULL`). +#' The edge connectivity of a pair of vertices (`source` and `target`) is the minimum number of edges needed to remove to eliminate all (directed) paths from `source` to `target`. +#' `edge_connectivity()` calculates this quantity if both the `source` and `target` arguments are given (and not `NULL`). #' -#' The edge connectivity of a graph is the minimum of the edge connectivity of -#' every (ordered) pair of vertices in the graph. `edge_connectivity()` -#' calculates this quantity if neither the `source` nor the `target` -#' arguments are given (i.e. they are both `NULL`). +#' The edge connectivity of a graph is the minimum of the edge connectivity of every (ordered) pair of vertices in the graph. +#' `edge_connectivity()` calculates this quantity if neither the `source` nor the `target` arguments are given (i.e. they are both `NULL`). #' #' @section `edge_disjoint_paths()` The maximum number of edge-disjoint paths between two vertices: -#' A set of paths between two vertices is called edge-disjoint if they do not -#' share any edges. The maximum number of edge-disjoint paths are calculated -#' by this function using maximum flow techniques. Directed paths are -#' considered in directed graphs. +#' A set of paths between two vertices is called edge-disjoint if they do not share any edges. +#' The maximum number of edge-disjoint paths are calculated by this function using maximum flow techniques. +#' Directed paths are considered in directed graphs. #' #' -#' A set of edge disjoint paths between two vertices is a set of paths between -#' them containing no common edges. The maximum number of edge disjoint paths -#' between two vertices is the same as their edge connectivity. +#' A set of edge disjoint paths between two vertices is a set of paths between them containing no common edges. +#' The maximum number of edge disjoint paths between two vertices is the same as their edge connectivity. #' -#' When there are no direct edges between the source and the target, the number -#' of vertex-disjoint paths is the same as the vertex connectivity of -#' the two vertices. When some edges are present, each one of them -#' contributes one extra path. +#' When there are no direct edges between the source and the target, +#' the number of vertex-disjoint paths is the same as the vertex connectivity of the two vertices. +#' When some edges are present, each one of them contributes one extra path. #' #' @section `adhesion()` Adhesion of a graph: -#' The adhesion of a graph is the minimum number of edges needed to remove to -#' obtain a graph which is not strongly connected. This is the same as the edge -#' connectivity of the graph. +#' The adhesion of a graph is the minimum number of edges needed to remove to obtain a graph which is not strongly connected. +#' This is the same as the edge connectivity of the graph. #' #' @section All three functions: -#' The three functions documented on this page calculate similar properties, -#' more precisely the most general is `edge_connectivity()`, the others are -#' included only for having more descriptive function names. +#' The three functions documented on this page calculate similar properties, more precisely the most general is `edge_connectivity()`, +#' the others are included only for having more descriptive function names. #' #' #' @param graph The input graph. -#' @param source The ID of the source vertex, for `edge_connectivity()` it -#' can be `NULL`, see details below. -#' @param target The ID of the target vertex, for `edge_connectivity()` it -#' can be `NULL`, see details below. +#' @param source The ID of the source vertex, for `edge_connectivity()` it can be `NULL`, see details below. +#' @param target The ID of the target vertex, for `edge_connectivity()` it can be `NULL`, see details below. #' @inheritParams rlang::args_dots_empty -#' @param checks Logical. Whether to check that the graph is connected -#' and also the degree of the vertices. If the graph is not (strongly) -#' connected then the connectivity is obviously zero. Otherwise if the minimum -#' degree is one then the edge connectivity is also one. It is a good idea to -#' perform these checks, as they can be done quickly compared to the -#' connectivity calculation itself. They were suggested by Peter McMahan, -#' thanks Peter. +#' @param checks Logical. +#' Whether to check that the graph is connected and also the degree of the vertices. +#' If the graph is not (strongly) connected then the connectivity is obviously zero. +#' Otherwise if the minimum degree is one then the edge connectivity is also one. +#' It is a good idea to perform these checks, as they can be done quickly compared to the connectivity calculation itself. +#' They were suggested by Peter McMahan, thanks Peter. #' @return A scalar real value. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @references Douglas R. White and Frank Harary (2001): The cohesiveness of blocks in @@ -846,12 +790,11 @@ cohesion.igraph <- function(x, checks = TRUE, ...) { #' #' List all (s,t)-cuts in a directed graph. #' -#' Given a \eqn{G} directed graph and two, different and non-ajacent vertices, -#' \eqn{s} and \eqn{t}, an \eqn{(s,t)}-cut is a set of edges, such that after -#' removing these edges from \eqn{G} there is no directed path from \eqn{s} to -#' \eqn{t}. +#' Given a \eqn{G} directed graph and two, different and non-ajacent vertices, \eqn{s} and \eqn{t}, an \eqn{(s,t)}-cut is a set of edges, +#' such that after removing these edges from \eqn{G} there is no directed path from \eqn{s} to \eqn{t}. #' -#' @param graph The input graph. It must be directed. +#' @param graph The input graph. +#' It must be directed. #' @param source The source vertex. #' @param target The target vertex. #' @return A list with entries: @@ -896,29 +839,24 @@ st_cuts <- function(graph, source, target) { #' List all minimum \eqn{(s,t)}-cuts of a graph #' -#' Listing all minimum \eqn{(s,t)}-cuts of a directed graph, for given \eqn{s} -#' and \eqn{t}. +#' Listing all minimum \eqn{(s,t)}-cuts of a directed graph, for given \eqn{s} and \eqn{t}. #' -#' Given a \eqn{G} directed graph and two, different and non-ajacent vertices, -#' \eqn{s} and \eqn{t}, an \eqn{(s,t)}-cut is a set of edges, such that after -#' removing these edges from \eqn{G} there is no directed path from \eqn{s} to -#' \eqn{t}. +#' Given a \eqn{G} directed graph and two, different and non-ajacent vertices, \eqn{s} and \eqn{t}, an \eqn{(s,t)}-cut is a set of edges, +#' such that after removing these edges from \eqn{G} there is no directed path from \eqn{s} to \eqn{t}. #' -#' The size of an \eqn{(s,t)}-cut is defined as the sum of the capacities (or -#' weights) in the cut. For unweighted (=equally weighted) graphs, this is -#' simply the number of edges. +#' The size of an \eqn{(s,t)}-cut is defined as the sum of the capacities (or weights) in the cut. +#' For unweighted (=equally weighted) graphs, this is simply the number of edges. #' #' An \eqn{(s,t)}-cut is minimum if it is of the smallest possible size. #' -#' @param graph The input graph. It must be directed. +#' @param graph The input graph. +#' It must be directed. #' @param source The ID of the source vertex. #' @param target The ID of the target vertex. #' @inheritParams rlang::args_dots_empty -#' @param capacity Numeric vector giving the edge capacities. If this is -#' `NULL` and the graph has a `weight` edge attribute, then this -#' attribute defines the edge capacities. For forcing unit edge capacities, -#' even for graphs that have a `weight` edge attribute, supply `NA` -#' here. +#' @param capacity Numeric vector giving the edge capacities. +#' If this is `NULL` and the graph has a `weight` edge attribute, then this attribute defines the edge capacities. +#' For forcing unit edge capacities, even for graphs that have a `weight` edge attribute, supply `NA` here. #' @return A list with entries: #' \describe{ #' \item{value}{ @@ -1004,30 +942,25 @@ st_min_cuts <- function( #' #' Dominator tree of a directed graph. #' -#' A flowgraph is a directed graph with a distinguished start (or root) vertex -#' \eqn{r}, such that for any vertex \eqn{v}, there is a path from \eqn{r} to -#' \eqn{v}. A vertex \eqn{v} dominates another vertex \eqn{w} (not equal to -#' \eqn{v}), if every path from \eqn{r} to \eqn{w} contains \eqn{v}. Vertex -#' \eqn{v} is the immediate dominator or \eqn{w}, -#' \eqn{v=\textrm{idom}(w)}{v=idom(w)}, if \eqn{v} dominates \eqn{w} and every -#' other dominator of \eqn{w} dominates \eqn{v}. The edges -#' \eqn{{(\textrm{idom}(w), w)| w \ne r}}{{(idom(w),w)| w is not r}} form a -#' directed tree, rooted at \eqn{r}, called the dominator tree of the graph. -#' Vertex \eqn{v} dominates vertex \eqn{w} if and only if \eqn{v} is an -#' ancestor of \eqn{w} in the dominator tree. -#' -#' This function implements the Lengauer-Tarjan algorithm to construct the -#' dominator tree of a directed graph. For details see the reference below. -#' -#' @param graph A directed graph. If it is not a flowgraph, and it contains -#' some vertices not reachable from the root vertex, then these vertices will -#' be collected and returned as part of the result. -#' @param root The ID of the root (or source) vertex, this will be the root of -#' the tree. +#' A flowgraph is a directed graph with a distinguished start (or root) vertex \eqn{r}, such that for any vertex \eqn{v}, +#' there is a path from \eqn{r} to \eqn{v}. +#' A vertex \eqn{v} dominates another vertex \eqn{w} (not equal to \eqn{v}), if every path from \eqn{r} to \eqn{w} contains \eqn{v}. +#' Vertex \eqn{v} is the immediate dominator or \eqn{w}, \eqn{v=\textrm{idom}(w)}{v=idom(w)}, +#' if \eqn{v} dominates \eqn{w} and every other dominator of \eqn{w} dominates \eqn{v}. +#' The edges \eqn{{(\textrm{idom}(w), w)| w \ne r}}{{(idom(w),w)| w is not r}} form a directed tree, rooted at \eqn{r}, +#' called the dominator tree of the graph. +#' Vertex \eqn{v} dominates vertex \eqn{w} if and only if \eqn{v} is an ancestor of \eqn{w} in the dominator tree. +#' +#' This function implements the Lengauer-Tarjan algorithm to construct the dominator tree of a directed graph. +#' For details see the reference below. +#' +#' @param graph A directed graph. +#' If it is not a flowgraph, and it contains some vertices not reachable from the root vertex, +#' then these vertices will be collected and returned as part of the result. +#' @param root The ID of the root (or source) vertex, this will be the root of the tree. #' @inheritParams rlang::args_dots_empty -#' @param mode Constant, must be \sQuote{`in`} or \sQuote{`out`}. If -#' it is \sQuote{`in`}, then all directions are considered as opposite to -#' the original one in the input graph. +#' @param mode Constant, must be \sQuote{`in`} or \sQuote{`out`}. +#' If it is \sQuote{`in`}, then all directions are considered as opposite to the original one in the input graph. #' @return A list with components: #' \describe{ #' \item{dom}{ @@ -1133,21 +1066,19 @@ dominator_tree <- function( #' Minimum size vertex separators #' -#' List all vertex sets that are minimal \eqn{(s,t)} separators for some -#' \eqn{s} and \eqn{t}, in an undirected graph. +#' List all vertex sets that are minimal \eqn{(s,t)} separators for some \eqn{s} and \eqn{t}, in an undirected graph. #' -#' A \eqn{(s,t)} vertex separator is a set of vertices, such that after their -#' removal from the graph, there is no path between \eqn{s} and \eqn{t} in the -#' graph. +#' A \eqn{(s,t)} vertex separator is a set of vertices, such that after their removal from the graph, +#' there is no path between \eqn{s} and \eqn{t} in the graph. #' -#' A \eqn{(s,t)} vertex separator is minimal if none of its proper subsets is -#' an \eqn{(s,t)} vertex separator for the same \eqn{s} and \eqn{t}. +#' A \eqn{(s,t)} vertex separator is minimal +#' if none of its proper subsets is an \eqn{(s,t)} vertex separator for the same \eqn{s} and \eqn{t}. #' -#' @param graph The input graph. It may be directed, but edge directions are -#' ignored. -#' @return A list of numeric vectors. Each vector contains a vertex set -#' (defined by vertex IDs), each vector is an (s,t) separator of the input -#' graph, for some \eqn{s} and \eqn{t}. +#' @param graph The input graph. +#' It may be directed, but edge directions are ignored. +#' @return A list of numeric vectors. +#' Each vector contains a vertex set (defined by vertex IDs), each vector is an (s,t) separator of the input graph, +#' for some \eqn{s} and \eqn{t}. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @references Anne Berry, Jean-Paul Bordat and Olivier Cogis: Generating All #' the Minimal Separators of a Graph, In: Peter Widmayer, Gabriele Neyer and @@ -1164,9 +1095,8 @@ dominator_tree <- function( #' min_st_separators(chvatal) #' # https://github.com/r-lib/roxygen2/issues/1092 #' @section Note: -#' Note that the code below returns `{1, 3}` despite its subset `{1}` being a -#' separator as well. This is because `{1, 3}` is minimal with respect to -#' separating vertices 2 and 4. +#' Note that the code below returns `{1, 3}` despite its subset `{1}` being a separator as well. +#' This is because `{1, 3}` is minimal with respect to separating vertices 2 and 4. #' #' ```{r, eval=FALSE} #' g <- make_graph(~ 0-1-2-3-4-1) @@ -1188,25 +1118,21 @@ min_st_separators <- function(graph) { #' Maximum flow in a graph #' -#' In a graph where each edge has a given flow capacity the maximal flow -#' between two vertices is calculated. +#' In a graph where each edge has a given flow capacity the maximal flow between two vertices is calculated. #' -#' `max_flow()` calculates the maximum flow between two vertices in a -#' weighted (i.e. valued) graph. A flow from `source` to `target` is -#' an assignment of non-negative real numbers to the edges of the graph, -#' satisfying two properties: (1) for each edge the flow (i.e. the assigned -#' number) is not more than the capacity of the edge (the `capacity` -#' parameter or edge attribute), (2) for every vertex, except the source and -#' the target the incoming flow is the same as the outgoing flow. The value of -#' the flow is the incoming flow of the `target` vertex. The maximum flow -#' is the flow of maximum value. +#' `max_flow()` calculates the maximum flow between two vertices in a weighted (i.e. valued) graph. +#' A flow from `source` to `target` is an assignment of non-negative real numbers to the edges of the graph, satisfying two properties: +#' (1) for each edge the flow (i.e. the assigned number) is not more than the capacity of the edge (the `capacity` parameter or edge attribute), +#' (2) for every vertex, except the source and the target the incoming flow is the same as the outgoing flow. +#' The value of the flow is the incoming flow of the `target` vertex. +#' The maximum flow is the flow of maximum value. #' #' @param graph The input graph. #' @param source The ID of the source vertex. #' @param target The ID of the target vertex (sometimes also called sink). #' @inheritParams rlang::args_dots_empty -#' @param capacity Vector giving the capacity of the edges. If this is -#' `NULL` (the default) then the `capacity` edge attribute is used. +#' @param capacity Vector giving the capacity of the edges. +#' If this is `NULL` (the default) then the `capacity` edge attribute is used. #' Note that the `weight` edge attribute is not used by this function. #' @return A named list with components: #' \describe{ @@ -1304,19 +1230,14 @@ max_flow <- function( #' Check whether removing this set of vertices would disconnect the graph. #' -#' `is_separator()` determines whether the supplied vertex set is a vertex -#' separator: -#' A vertex set \eqn{S} is a separator if there are vertices \eqn{u} and \eqn{v} -#' in the graph such that all paths between \eqn{u} and \eqn{v} pass -#' through some vertices in \eqn{S}. -#' -#' @param graph The input graph. It may be directed, but edge directions are -#' ignored. -#' @param candidate A numeric vector giving the vertex IDs of the candidate -#' separator. -#' @return A Logical, whether the supplied vertex set is a (minimal) -#' vertex separator or not. -#' lists all vertex separator of minimum size. +#' `is_separator()` determines whether the supplied vertex set is a vertex separator: +#' A vertex set \eqn{S} is a separator +#' if there are vertices \eqn{u} and \eqn{v} in the graph such that all paths between \eqn{u} and \eqn{v} pass through some vertices in \eqn{S}. +#' +#' @param graph The input graph. +#' It may be directed, but edge directions are ignored. +#' @param candidate A numeric vector giving the vertex IDs of the candidate separator. +#' @return A Logical, whether the supplied vertex set is a (minimal) vertex separator or not. lists all vertex separator of minimum size. #' @family flow #' @examples #' ring <- make_ring(4) @@ -1339,16 +1260,13 @@ is_separator <- function(graph, candidate) { #' #' Check whether a given set of vertices is a minimal vertex separator. #' -#' `is_min_separator()` decides whether the supplied vertex set is a minimal -#' vertex separator. A minimal vertex separator is a vertex separator, such -#' that none of its proper subsets are a vertex separator. +#' `is_min_separator()` decides whether the supplied vertex set is a minimal vertex separator. +#' A minimal vertex separator is a vertex separator, such that none of its proper subsets are a vertex separator. #' -#' @param graph The input graph. It may be directed, but edge directions are -#' ignored. -#' @param candidate A numeric vector giving the vertex IDs of the candidate -#' separator. -#' @return A Logical, whether the supplied vertex set is a (minimal) -#' vertex separator or not. +#' @param graph The input graph. +#' It may be directed, but edge directions are ignored. +#' @param candidate A numeric vector giving the vertex IDs of the candidate separator. +#' @return A Logical, whether the supplied vertex set is a (minimal) vertex separator or not. #' @examples #' # The graph from the Moody-White paper #' mw <- graph_from_literal( @@ -1390,20 +1308,18 @@ is_min_separator <- function(graph, candidate) { #' Minimum size vertex separators #' -#' Find all vertex sets of minimal size whose removal separates the graph into -#' more components +#' Find all vertex sets of minimal size whose removal separates the graph into more components #' -#' This function implements the Kanevsky algorithm for finding all minimal-size -#' vertex separators in an undirected graph. See the reference below for the -#' details. +#' This function implements the Kanevsky algorithm for finding all minimal-size vertex separators in an undirected graph. +#' See the reference below for the details. #' #' In the special case of a fully connected input graph with \eqn{n} vertices, #' all subsets of size \eqn{n-1} are listed as the result. #' -#' @param graph The input graph. It may be directed, but edge directions are -#' ignored. -#' @return A list of numeric vectors. Each numeric vector is a vertex -#' separator. +#' @param graph The input graph. +#' It may be directed, but edge directions are ignored. +#' @return A list of numeric vectors. +#' Each numeric vector is a vertex separator. #' @references Arkady Kanevsky: Finding all minimum-size separating vertex sets #' in a graph. *Networks* 23 533--541, 1993. #' diff --git a/R/foreign.R b/R/foreign.R index d0768024e41..af8fa640e38 100644 --- a/R/foreign.R +++ b/R/foreign.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `write.graph()` was renamed to [write_graph()] to create a more -#' consistent API. +#' `write.graph()` was renamed to [write_graph()] to create a more consistent API. #' @inheritParams write_graph #' @keywords internal #' @export @@ -34,8 +33,7 @@ write.graph <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `read.graph()` was renamed to [read_graph()] to create a more -#' consistent API. +#' `read.graph()` was renamed to [read_graph()] to create a more consistent API. #' @inheritParams read_graph #' @keywords internal #' @export @@ -64,8 +62,7 @@ read.graph <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.graphdb()` was renamed to [graph_from_graphdb()] to create a more -#' consistent API. +#' `graph.graphdb()` was renamed to [graph_from_graphdb()] to create a more consistent API. #' @inheritParams graph_from_graphdb #' @keywords internal #' @export @@ -163,48 +160,41 @@ write.graph.fromraw <- function(buffer, file) { #' Reading foreign file formats #' -#' The `read_graph()` function is able to read graphs in various -#' representations from a file, or from a http connection. Various formats -#' are supported. +#' The `read_graph()` function is able to read graphs in various representations from a file, or from a http connection. +#' Various formats are supported. #' -#' The `read_graph()` function may have additional arguments depending on -#' the file format (the `format` argument). See the details separately for -#' each file format, below. +#' The `read_graph()` function may have additional arguments depending on the file format (the `format` argument). +#' See the details separately for each file format, below. #' #' @aliases LGL Pajek GraphML GML DL UCINET -#' @param file The connection to read from. This can be a local file, or a -#' `http` or `ftp` connection. It can also be a character string with -#' the file name or URI. -#' @param format Character constant giving the file format. Right now -#' `edgelist`, `pajek`, `ncol`, `lgl`, `graphml`, -#' `dimacs`, `graphdb`, `gml` and `dl` are supported, -#' the default is `edgelist`. As of igraph 0.4 this argument is case -#' insensitive. +#' @param file The connection to read from. +#' This can be a local file, or a `http` or `ftp` connection. +#' It can also be a character string with the file name or URI. +#' @param format Character constant giving the file format. +#' Right now `edgelist`, `pajek`, `ncol`, `lgl`, `graphml`, `dimacs`, `graphdb`, `gml` and `dl` are supported, the default is `edgelist`. +#' As of igraph 0.4 this argument is case insensitive. #' @param \dots Additional arguments, see below. #' @return A graph object. #' @section Edge list format: -#' This format is a simple text file with numeric -#' vertex IDs defining the edges. There is no need to have newline characters -#' between the edges, a simple space will also do. Vertex IDs contained in -#' the file are assumed to start at zero. +#' This format is a simple text file with numeric vertex IDs defining the edges. +#' There is no need to have newline characters between the edges, a simple space will also do. +#' Vertex IDs contained in the file are assumed to start at zero. #' #' Additional arguments: #' \describe{ #' \item{n}{ -#' The number of vertices in the -#' graph. If it is smaller than or equal to the largest integer in the file, -#' then it is ignored; so it is safe to set it to zero (the default). +#' The number of vertices in the graph. +#' If it is smaller than or equal to the largest integer in the file, then it is ignored; +#' so it is safe to set it to zero (the default). #' } #' \item{directed}{ -#' Logical scalar, whether to create a directed graph. The -#' default value is `TRUE`. +#' Logical scalar, whether to create a directed graph. +#' The default value is `TRUE`. #' } #' } #' @section Pajek format: -#' Currently igraph only supports Pajek network -#' files, with a `.net` extension, but not Pajek project files with -#' a `.paj` extension. Only network data is supported; permutations, -#' hierarchies, clusters and vectors are not. +#' Currently igraph only supports Pajek network files, with a `.net` extension, but not Pajek project files with a `.paj` extension. +#' Only network data is supported; permutations, hierarchies, clusters and vectors are not. #' @section NCOL format: #' Additional arguments: #' \describe{ @@ -245,7 +235,8 @@ write.graph.fromraw <- function(buffer, file) { #' containing multiple graphs. Defaults to 0 for the first graph.} #' } #' @section LGL format: -#' The .lgl format is used by the Large Graph Layout visualization software (), it can describe undirected optionally weighted graphs +#' The .lgl format is used by the Large Graph Layout visualization software (), +#' it can describe undirected optionally weighted graphs #' \describe{ #' \item{names}{Logical, whether to add vertex names as a vertex attribute #' called "name". Default is TRUE.} @@ -265,15 +256,15 @@ write.graph.fromraw <- function(buffer, file) { #' This is a line-oriented text file (ASCII) format. #' The first character of each line defines the type of the line. #' If the first character is c the line is a comment line and it is ignored. -#' There is one problem line (p in the file), -#' it must appear before any node and arc descriptor lines. -#' The problem line has three fields separated by spaces: the problem type (max or edge), -#' the number of vertices, and number of edges in the graph. In MAX problems, -#' exactly two node identification lines are expected (n), one for the source, and one for the target vertex. +#' There is one problem line (p in the file), it must appear before any node and arc descriptor lines. +#' The problem line has three fields separated by spaces: the problem type (max or edge), the number of vertices, +#' and number of edges in the graph. +#' In MAX problems, exactly two node identification lines are expected (n), one for the source, and one for the target vertex. #' These have two fields: the ID of the vertex and the type of the vertex, either s ( = source) or t ( = target). #' Arc lines start with a and have three fields: the source vertex, the target vertex and the edge capacity. -#' In EDGE problems, there may be a node line (n) for each node. It specifies the node index and an -#' integer node label. Nodes for which no explicit label was specified will use their index as label. +#' In EDGE problems, there may be a node line (n) for each node. +#' It specifies the node index and an integer node label. +#' Nodes for which no explicit label was specified will use their index as label. #' In EDGE problems, each edge is specified as an edge line (e). #' \describe{ #' \item{directed}{Logical, whether to create a directed graph. Default is TRUE.} @@ -291,9 +282,11 @@ write.graph.fromraw <- function(buffer, file) { #' \item{directed}{Logical, whether to create a directed graph. Default is TRUE.} #' } #' @section GML format: -#' GML is a quite general textual format. For the specifics of the implementation, see the linked documentation of the cClibrary. +#' GML is a quite general textual format. +#' For the specifics of the implementation, see the linked documentation of the cClibrary. #' @section GraphDB format: -#' This is a binary format, used in the ARG Graph Database for isomorphism testing. For more information, see +#' This is a binary format, used in the ARG Graph Database for isomorphism testing. +#' For more information, see #' \describe{ #' \item{directed}{Logical, whether to create a directed graph. Default is TRUE.} #' } @@ -347,26 +340,25 @@ read_graph <- function( #' Writing the graph to a file in some format #' -#' `write_graph()` is a general function for exporting graphs to foreign -#' file formats. The recommended formats for data exchange are GraphML and GML. +#' `write_graph()` is a general function for exporting graphs to foreign file formats. +#' The recommended formats for data exchange are GraphML and GML. #' #' @param graph The graph to export. -#' @param file A connection or a string giving the file name to write the graph -#' to. -#' @param format Character string giving the file format. Right now -#' `pajek`, `graphml`, `dot`, `gml`, `edgelist`, -#' `lgl`, `ncol`, `leda` and `dimacs` are implemented. As of igraph 0.4 -#' this argument is case insensitive. +#' @param file A connection or a string giving the file name to write the graph to. +#' @param format Character string giving the file format. +#' Right now `pajek`, `graphml`, `dot`, `gml`, `edgelist`, `lgl`, `ncol`, `leda` and `dimacs` are implemented. +#' As of igraph 0.4 this argument is case insensitive. #' @param \dots Other, format specific arguments, see below. #' @return A `NULL``, invisibly. #' @section Edge list format: The `edgelist` format is a simple text file, -#' with one edge per line, the two zero-based numerical vertex IDs separated -#' by a space character. Note that vertices are indexed starting with zero. -#' The file is sorted by the first and the second column. This format has no -#' additional arguments. +#' with one edge per line, the two zero-based numerical vertex IDs separated by a space character. +#' Note that vertices are indexed starting with zero. +#' The file is sorted by the first and the second column. +#' This format has no additional arguments. #' @section NCOL format: This format is a plain text edge list in which vertices -#' are referred to by name rather than numerical ID. Edge weights may be -#' optionally written. Additional parameters: +#' are referred to by name rather than numerical ID. +#' Edge weights may be optionally written. +#' Additional parameters: #' \describe{ #' \item{names}{ #' The name of a vertex attribute to take vertex names from or @@ -378,10 +370,11 @@ read_graph <- function( #' } #' } #' @section Pajek format: The `pajek` format is provided for interoperability -#' with the Pajek software only. Since the format does not have a formal -#' specification, it is not recommended for general data exchange or archival. +#' with the Pajek software only. +#' Since the format does not have a formal specification, it is not recommended for general data exchange or archival. #' @section LGL format: -#' The .lgl format is used by the Large Graph Layout visualization software (), it can describe undirected optionally weighted graphs. +#' The .lgl format is used by the Large Graph Layout visualization software (), +#' it can describe undirected optionally weighted graphs. #' \describe{ #' \item{names}{The name of a vertex attribute to use for vertex names, or #' NULL to use numeric IDs.} @@ -395,15 +388,15 @@ read_graph <- function( #' This is a line-oriented text file (ASCII) format. #' The first character of each line defines the type of the line. #' If the first character is c the line is a comment line and it is ignored. -#' There is one problem line (p in the file), -#' it must appear before any node and arc descriptor lines. -#' The problem line has three fields separated by spaces: the problem type (max or edge), -#' the number of vertices, and number of edges in the graph. In MAX problems, -#' exactly two node identification lines are expected (n), one for the source, and one for the target vertex. +#' There is one problem line (p in the file), it must appear before any node and arc descriptor lines. +#' The problem line has three fields separated by spaces: the problem type (max or edge), the number of vertices, +#' and number of edges in the graph. +#' In MAX problems, exactly two node identification lines are expected (n), one for the source, and one for the target vertex. #' These have two fields: the ID of the vertex and the type of the vertex, either s ( = source) or t ( = target). #' Arc lines start with a and have three fields: the source vertex, the target vertex and the edge capacity. -#' In EDGE problems, there may be a node line (n) for each node. It specifies the node index and an -#' integer node label. Nodes for which no explicit label was specified will use their index as label. +#' In EDGE problems, there may be a node line (n) for each node. +#' It specifies the node index and an integer node label. +#' Nodes for which no explicit label was specified will use their index as label. #' In EDGE problems, each edge is specified as an edge line (e). #' \describe{ #' \item{source}{Numeric ID of the source vertex.} @@ -422,8 +415,9 @@ read_graph <- function( #' @section GraphML format: #' GraphML is an XML-based file format for representing various types of graphs. #' When a numerical attribute value is NaN, it will be omitted from the file. -#' This function assumes that non-ASCII characters in attribute names and string -#' attribute values are UTF-8 encoded. If this is not the case, the resulting XML file will be invalid. Control characters, i.e. character codes up to and including 31 (with the exception of tab, cr and lf), are not allowed. +#' This function assumes that non-ASCII characters in attribute names and string attribute values are UTF-8 encoded. +#' If this is not the case, the resulting XML file will be invalid. +#' Control characters, i.e. character codes up to and including 31 (with the exception of tab, cr and lf), are not allowed. #' \describe{ #' \item{prefixAttr}{Logical, whether to prefix attribute names to ensure #' uniqueness across vertex/edge/graph attributes. Default is TRUE.} @@ -432,8 +426,9 @@ read_graph <- function( #' @section LEDA format: #' This function writes a graph to an output stream in LEDA format. #' See . -#' The support for the LEDA format is very basic at the moment; igraph writes only the LEDA graph section which supports one selected vertex and edge -#' attribute and no layout information or visual attributes. +#' The support for the LEDA format is very basic at the moment; +#' igraph writes only the LEDA graph section +#' which supports one selected vertex and edge attribute and no layout information or visual attributes. #' \describe{ #' \item{vertex.attr}{Name of vertex attribute to include in the file.} #' \item{edge.attr}{Name of edge attribute to include in the file.} @@ -442,8 +437,8 @@ read_graph <- function( #' DOT is the format used by the widely known GraphViz software, see for details. #' The grammar of the DOT format can be found here: . #' This is only a preliminary implementation, no visualization information is written. -#' This format is meant solely for interoperability with Graphviz. It is not recommended for -#' data exchange or archival. +#' This format is meant solely for interoperability with Graphviz. +#' It is not recommended for data exchange or archival. #' #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @seealso [read_graph()] @@ -774,46 +769,40 @@ write.graph.dot <- function(graph, file) { #' Load a graph from the graph database for testing graph isomorphism. #' -#' This function downloads a graph from a database created for the evaluation -#' of graph isomorphism testing algorithms. +#' This function downloads a graph from a database created for the evaluation of graph isomorphism testing algorithms. #' -#' `graph_from_graphdb()` reads a graph from the graph database from an FTP or -#' HTTP server or from a local copy. It has two modes of operation: +#' `graph_from_graphdb()` reads a graph from the graph database from an FTP or HTTP server or from a local copy. +#' It has two modes of operation: #' -#' If the `url` argument is specified then it should the complete path to -#' a local or remote graph database file. In this case we simply call -#' [read_graph()] with the proper arguments to read the file. +#' If the `url` argument is specified then it should the complete path to a local or remote graph database file. +#' In this case we simply call [read_graph()] with the proper arguments to read the file. #' -#' If `url` is `NULL`, and this is the default, then the filename is -#' assembled from the `base`, `prefix`, `type`, `nodes`, +#' If `url` is `NULL`, and this is the default, then the filename is assembled from the `base`, `prefix`, `type`, `nodes`, #' `pair` and `which` arguments. #' -#' Unfortunately the original graph database homepage is now defunct, but see -#' its old version at -#' -#' for the actual format of a graph database file and other information. +#' Unfortunately the original graph database homepage is now defunct, +#' but see its old version at for the actual format of a graph database file and other information. #' -#' @param url Complete URL with the file to import. Default: `NULL`. +#' @param url Complete URL with the file to import. +#' Default: `NULL`. #' @inheritParams rlang::args_dots_empty -#' @param prefix Gives the prefix. See details below. Possible values: -#' `iso`, `i2`, `si4`, `si6`, `mcs10`, `mcs30`, -#' `mcs50`, `mcs70`, `mcs90`. -#' @param type Gives the graph type identifier. See details below. Possible -#' values: `r001`, `r005`, `r01`, `r02`, `m2D`, -#' `m2Dr2`, `m2Dr4`, `m2Dr6` `m3D`, `m3Dr2`, -#' `m3Dr4`, `m3Dr6`, `m4D`, `m4Dr2`, `m4Dr4`, -#' `m4Dr6`, `b03`, `b03m`, `b06`, `b06m`, `b09`, -#' `b09m`. +#' @param prefix Gives the prefix. +#' See details below. +#' Possible values: `iso`, `i2`, `si4`, `si6`, `mcs10`, `mcs30`, `mcs50`, `mcs70`, `mcs90`. +#' @param type Gives the graph type identifier. +#' See details below. +#' Possible values: `r001`, `r005`, `r01`, `r02`, `m2D`, `m2Dr2`, `m2Dr4`, `m2Dr6` `m3D`, `m3Dr2`, `m3Dr4`, `m3Dr6`, `m4D`, `m4Dr2`, +#' `m4Dr4`, `m4Dr6`, `b03`, `b03m`, `b06`, `b06m`, `b09`, `b09m`. #' @param nodes The number of vertices in the graph. -#' @param pair Specifies which graph of the pair to read. Possible values: -#' `A` and `B`. -#' @param which Gives the number of the graph to read. For every graph type -#' there are a number of actual graphs in the database. This argument specifies -#' which one to read. -#' @param base The base address of the database. See details below. -#' @param compressed Logical, if TRUE than the file is expected to be -#' compressed by gzip. If `url` is `NULL` then a \sQuote{`.gz`} -#' suffix is added to the filename. +#' @param pair Specifies which graph of the pair to read. +#' Possible values: `A` and `B`. +#' @param which Gives the number of the graph to read. +#' For every graph type there are a number of actual graphs in the database. +#' This argument specifies which one to read. +#' @param base The base address of the database. +#' See details below. +#' @param compressed Logical, if TRUE than the file is expected to be compressed by gzip. +#' If `url` is `NULL` then a \sQuote{`.gz`} suffix is added to the filename. #' @param directed Logical, whether to create a directed graph. #' @return A new graph object. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} diff --git a/R/games.R b/R/games.R index c61ca99b114..d5d33cacde7 100644 --- a/R/games.R +++ b/R/games.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `watts.strogatz.game()` was renamed to [sample_smallworld()] to create a more -#' consistent API. +#' `watts.strogatz.game()` was renamed to [sample_smallworld()] to create a more consistent API. #' @inheritParams sample_smallworld #' @keywords internal #' @export @@ -37,8 +36,7 @@ watts.strogatz.game <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `static.power.law.game()` was renamed to [sample_fitness_pl()] to create a more -#' consistent API. +#' `static.power.law.game()` was renamed to [sample_fitness_pl()] to create a more consistent API. #' @inheritParams sample_fitness_pl #' @keywords internal #' @export @@ -73,8 +71,7 @@ static.power.law.game <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `static.fitness.game()` was renamed to [sample_fitness()] to create a more -#' consistent API. +#' `static.fitness.game()` was renamed to [sample_fitness()] to create a more consistent API. #' @inheritParams sample_fitness #' @keywords internal #' @export @@ -105,8 +102,7 @@ static.fitness.game <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `sbm.game()` was renamed to [sample_sbm()] to create a more -#' consistent API. +#' `sbm.game()` was renamed to [sample_sbm()] to create a more consistent API. #' @inheritParams sample_sbm #' @keywords internal #' @export @@ -133,8 +129,7 @@ sbm.game <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `preference.game()` was renamed to [sample_pref()] to create a more -#' consistent API. +#' `preference.game()` was renamed to [sample_pref()] to create a more consistent API. #' @inheritParams sample_pref #' @keywords internal #' @export @@ -165,8 +160,7 @@ preference.game <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `lastcit.game()` was renamed to [sample_last_cit()] to create a more -#' consistent API. +#' `lastcit.game()` was renamed to [sample_last_cit()] to create a more consistent API. #' @inheritParams sample_last_cit #' @keywords internal #' @export @@ -193,8 +187,7 @@ lastcit.game <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `k.regular.game()` was renamed to [sample_k_regular()] to create a more -#' consistent API. +#' `k.regular.game()` was renamed to [sample_k_regular()] to create a more consistent API. #' @inheritParams sample_k_regular #' @keywords internal #' @export @@ -214,8 +207,7 @@ k.regular.game <- function(no.of.nodes, k, directed = FALSE, multiple = FALSE) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `interconnected.islands.game()` was renamed to [sample_islands()] to create a more -#' consistent API. +#' `interconnected.islands.game()` was renamed to [sample_islands()] to create a more consistent API. #' @inheritParams sample_islands #' @keywords internal #' @export @@ -244,8 +236,7 @@ interconnected.islands.game <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `grg.game()` was renamed to [sample_grg()] to create a more -#' consistent API. +#' `grg.game()` was renamed to [sample_grg()] to create a more consistent API. #' @inheritParams sample_grg #' @keywords internal #' @export @@ -260,8 +251,7 @@ grg.game <- function(nodes, radius, torus = FALSE, coords = FALSE) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `growing.random.game()` was renamed to [sample_growing()] to create a more -#' consistent API. +#' `growing.random.game()` was renamed to [sample_growing()] to create a more consistent API. #' @inheritParams sample_growing #' @keywords internal #' @export @@ -280,8 +270,7 @@ growing.random.game <- function(n, m = 1, directed = TRUE, citation = FALSE) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `forest.fire.game()` was renamed to [sample_forestfire()] to create a more -#' consistent API. +#' `forest.fire.game()` was renamed to [sample_forestfire()] to create a more consistent API. #' @inheritParams sample_forestfire #' @keywords internal #' @export @@ -312,8 +301,7 @@ forest.fire.game <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `establishment.game()` was renamed to [sample_traits()] to create a more -#' consistent API. +#' `establishment.game()` was renamed to [sample_traits()] to create a more consistent API. #' @inheritParams sample_traits #' @keywords internal #' @export @@ -342,8 +330,7 @@ establishment.game <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `degree.sequence.game()` was renamed to [sample_degseq()] to create a more -#' consistent API. +#' `degree.sequence.game()` was renamed to [sample_degseq()] to create a more consistent API. #' @inheritParams sample_degseq #' @keywords internal #' @export @@ -366,8 +353,7 @@ degree.sequence.game <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `connect.neighborhood()` was renamed to [connect()] to create a more -#' consistent API. +#' `connect.neighborhood()` was renamed to [connect()] to create a more consistent API. #' @inheritParams connect #' @keywords internal #' @export @@ -386,8 +372,7 @@ connect.neighborhood <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `citing.cited.type.game()` was renamed to [sample_cit_cit_types()] to create a more -#' consistent API. +#' `citing.cited.type.game()` was renamed to [sample_cit_cit_types()] to create a more consistent API. #' @inheritParams sample_cit_cit_types #' @keywords internal #' @export @@ -420,8 +405,7 @@ citing.cited.type.game <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `cited.type.game()` was renamed to [sample_cit_types()] to create a more -#' consistent API. +#' `cited.type.game()` was renamed to [sample_cit_types()] to create a more consistent API. #' @inheritParams sample_cit_types #' @keywords internal #' @export @@ -450,8 +434,7 @@ cited.type.game <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `callaway.traits.game()` was renamed to [sample_traits_callaway()] to create a more -#' consistent API. +#' `callaway.traits.game()` was renamed to [sample_traits_callaway()] to create a more consistent API. #' @inheritParams sample_traits_callaway #' @keywords internal #' @export @@ -484,8 +467,7 @@ callaway.traits.game <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `bipartite.random.game()` was renamed to [sample_bipartite()] to create a more -#' consistent API. +#' `bipartite.random.game()` was renamed to [sample_bipartite()] to create a more consistent API. #' @inheritParams sample_bipartite #' @keywords internal #' @export @@ -510,8 +492,7 @@ bipartite.random.game <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `barabasi.game()` was renamed to [sample_pa()] to create a more -#' consistent API. +#' `barabasi.game()` was renamed to [sample_pa()] to create a more consistent API. #' @inheritParams sample_pa #' @keywords internal #' @export @@ -548,8 +529,7 @@ barabasi.game <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `ba.game()` was renamed to [sample_pa()] to create a more -#' consistent API. +#' `ba.game()` was renamed to [sample_pa()] to create a more consistent API. #' @inheritParams sample_pa #' @keywords internal #' @export @@ -586,8 +566,7 @@ ba.game <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `asymmetric.preference.game()` was renamed to [sample_asym_pref()] to create a more -#' consistent API. +#' `asymmetric.preference.game()` was renamed to [sample_asym_pref()] to create a more consistent API. #' @inheritParams sample_asym_pref #' @keywords internal #' @export @@ -618,8 +597,7 @@ asymmetric.preference.game <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `aging.barabasi.game()` was renamed to [sample_pa_age()] to create a more -#' consistent API. +#' `aging.barabasi.game()` was renamed to [sample_pa_age()] to create a more consistent API. #' @inheritParams sample_pa_age #' @keywords internal #' @export @@ -664,8 +642,7 @@ aging.barabasi.game <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `aging.ba.game()` was renamed to [sample_pa_age()] to create a more -#' consistent API. +#' `aging.ba.game()` was renamed to [sample_pa_age()] to create a more consistent API. #' @inheritParams sample_pa_age #' @keywords internal #' @export @@ -710,8 +687,7 @@ aging.ba.game <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `aging.prefatt.game()` was renamed to [sample_pa_age()] to create a more -#' consistent API. +#' `aging.prefatt.game()` was renamed to [sample_pa_age()] to create a more consistent API. #' @inheritParams sample_pa_age #' @keywords internal #' @export @@ -775,82 +751,64 @@ aging.prefatt.game <- function( #' Generate random graphs using preferential attachment #' -#' Preferential attachment is a family of simple stochastic algorithms for building -#' a graph. Variants include the Barabási-Abert model and the Price model. +#' Preferential attachment is a family of simple stochastic algorithms for building a graph. +#' Variants include the Barabási-Abert model and the Price model. #' -#' This is a simple stochastic algorithm to generate a graph. It is a discrete -#' time step model and in each time step a single vertex is added. +#' This is a simple stochastic algorithm to generate a graph. +#' It is a discrete time step model and in each time step a single vertex is added. #' -#' We start with a single vertex and no edges in the first time step. Then we -#' add one vertex in each time step and the new vertex initiates some edges to -#' old vertices. The probability that an old vertex is chosen is given by +#' We start with a single vertex and no edges in the first time step. +#' Then we add one vertex in each time step and the new vertex initiates some edges to old vertices. +#' The probability that an old vertex is chosen is given by #' \deqn{P[i] \sim k_i^\alpha+a}{P[i] ~ k[i]^alpha + a} where \eqn{k_i}{k[i]} -#' is the in-degree of vertex \eqn{i} in the current time step (more precisely -#' the number of adjacent edges of \eqn{i} which were not initiated by \eqn{i} -#' itself) and \eqn{\alpha}{alpha} and \eqn{a} are parameters given by the -#' `power` and `zero.appeal` arguments. -#' -#' The number of edges initiated in a time step is given by the `m`, -#' `out.dist` and `out.seq` arguments. If `out.seq` is given and -#' not NULL then it gives the number of edges to add in a vector, the first -#' element is ignored, the second is the number of edges to add in the second -#' time step and so on. If `out.seq` is not given or null and -#' `out.dist` is given and not NULL then it is used as a discrete -#' distribution to generate the number of edges in each time step. Its first -#' element is the probability that no edges will be added, the second is the -#' probability that one edge is added, etc. (`out.dist` does not need to -#' sum up to one, it normalized automatically.) `out.dist` should contain -#' non-negative numbers and at east one element should be positive. -#' -#' If both `out.seq` and `out.dist` are omitted or NULL then `m` -#' will be used, it should be a positive integer constant and `m` edges -#' will be added in each time step. -#' -#' `sample_pa()` generates a directed graph by default, set -#' `directed` to `FALSE` to generate an undirected graph. Note that -#' even if an undirected graph is generated \eqn{k_i}{k[i]} denotes the number -#' of adjacent edges not initiated by the vertex itself and not the total -#' (in- + out-) degree of the vertex, unless the `out.pref` argument is set to -#' `TRUE`. +#' is the in-degree of vertex \eqn{i} in the current time step (more precisely the number of adjacent edges of \eqn{i} which were not initiated by \eqn{i} itself) and \eqn{\alpha}{alpha} and \eqn{a} are parameters given by the `power` and `zero.appeal` arguments. +#' +#' The number of edges initiated in a time step is given by the `m`, `out.dist` and `out.seq` arguments. +#' If `out.seq` is given and not NULL then it gives the number of edges to add in a vector, the first element is ignored, +#' the second is the number of edges to add in the second time step and so on. +#' If `out.seq` is not given or null and `out.dist` is given and not NULL +#' then it is used as a discrete distribution to generate the number of edges in each time step. +#' Its first element is the probability that no edges will be added, the second is the probability that one edge is added, +#' etc. (`out.dist` does not need to sum up to one, it normalized automatically.) +#' `out.dist` should contain non-negative numbers and at east one element should be positive. +#' +#' If both `out.seq` and `out.dist` are omitted or NULL then `m` will be used, +#' it should be a positive integer constant and `m` edges will be added in each time step. +#' +#' `sample_pa()` generates a directed graph by default, set `directed` to `FALSE` to generate an undirected graph. +#' Note that even +#' if an undirected graph is generated \eqn{k_i}{k[i]} denotes the number of adjacent edges not initiated by the vertex itself and not the total (in- + out-) degree of the vertex, +#' unless the `out.pref` argument is set to `TRUE`. #' #' @param n Number of vertices. #' @param power The power of the preferential attachment, the default is one, #' i.e. linear preferential attachment. #' @param m Numeric constant, the number of edges to add in each time step, -#' defaults to 1. -#' This argument is only used if both `out.dist` and `out.seq` are omitted -#' or NULL. +#' defaults to 1. This argument is only used if both `out.dist` and `out.seq` are omitted or NULL. #' @inheritParams rlang::args_dots_empty -#' @param out.dist Numeric vector, the distribution of the number of edges to -#' add in each time step. This argument is only used if the `out.seq` -#' argument is omitted or NULL. -#' @param out.seq Numeric vector giving the number of edges to add in each time -#' step. Its first element is ignored as no edges are added in the first time -#' step. -#' @param out.pref Logical, if true the total degree is used for calculating -#' the citation probability, otherwise the in-degree is used. -#' @param zero.appeal The \sQuote{attractiveness} of the vertices with no -#' adjacent edges. See details below. +#' @param out.dist Numeric vector, the distribution of the number of edges to add in each time step. +#' This argument is only used if the `out.seq` argument is omitted or NULL. +#' @param out.seq Numeric vector giving the number of edges to add in each time step. +#' Its first element is ignored as no edges are added in the first time step. +#' @param out.pref Logical, if true the total degree is used for calculating the citation probability, otherwise the in-degree is used. +#' @param zero.appeal The \sQuote{attractiveness} of the vertices with no adjacent edges. +#' See details below. #' @param directed Whether to create a directed graph. #' @param algorithm The algorithm to use for the graph generation. -#' `psumtree` uses a partial prefix-sum tree to generate the graph, this -#' algorithm can handle any `power` and `zero.appeal` values and -#' never generates multiple edges. `psumtree-multiple` also uses a -#' partial prefix-sum tree, but the generation of multiple edges is allowed. -#' Before the 0.6 version igraph used this algorithm if `power` was not -#' one, or `zero.appeal` was not one. `bag` is the algorithm that -#' was previously (before version 0.6) used if `power` was one and -#' `zero.appeal` was one as well. It works by putting the IDs of the -#' vertices into a bag (multiset, really), exactly as many times as their -#' (in-)degree, plus once more. Then the required number of cited vertices are -#' drawn from the bag, with replacement. This method might generate multiple -#' edges. It only works if `power` and `zero.appeal` are equal one. -#' @param start.graph `NULL` or an igraph graph. If a graph, then the -#' supplied graph is used as a starting graph for the preferential attachment -#' algorithm. The graph should have at least one vertex. If a graph is supplied -#' here and the `out.seq` argument is not `NULL`, then it should -#' contain the out degrees of the new vertices only, not the ones in the -#' `start.graph`. +#' `psumtree` uses a partial prefix-sum tree to generate the graph, +#' this algorithm can handle any `power` and `zero.appeal` values and never generates multiple edges. +#' `psumtree-multiple` also uses a partial prefix-sum tree, but the generation of multiple edges is allowed. +#' Before the 0.6 version igraph used this algorithm if `power` was not one, or `zero.appeal` was not one. +#' `bag` is the algorithm that was previously (before version 0.6) used if `power` was one and `zero.appeal` was one as well. +#' It works by putting the IDs of the vertices into a bag (multiset, really), exactly as many times as their (in-)degree, plus once more. +#' Then the required number of cited vertices are drawn from the bag, with replacement. +#' This method might generate multiple edges. +#' It only works if `power` and `zero.appeal` are equal one. +#' @param start.graph `NULL` or an igraph graph. +#' If a graph, then the supplied graph is used as a starting graph for the preferential attachment algorithm. +#' The graph should have at least one vertex. +#' If a graph is supplied here and the `out.seq` argument is not `NULL`, then it should contain the out degrees of the new vertices only, +#' not the ones in the `start.graph`. #' @return A graph object. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @references Barabási, A.-L. and Albert R. 1999. Emergence of scaling in @@ -1099,22 +1057,18 @@ pa <- function( #' Generate random graphs according to the \eqn{G(n,p)} Erdős-Rényi model #' #' Every possible edge is created independently with the same probability `p`. -#' This model is also referred to as a Bernoulli random graph since the -#' connectivity status of vertex pairs follows a Bernoulli distribution. +#' This model is also referred to as a Bernoulli random graph since the connectivity status of vertex pairs follows a Bernoulli distribution. #' -#' The graph has `n` vertices and each pair of vertices is connected -#' with the same probability `p`. The `loops` parameter controls whether -#' self-connections are also considered. This model effectively constrains -#' the average number of edges, \eqn{p m_\text{max}}, where \eqn{m_\text{max}} -#' is the largest possible number of edges, which depends on whether the -#' graph is directed or undirected and whether self-loops are allowed. +#' The graph has `n` vertices and each pair of vertices is connected with the same probability `p`. +#' The `loops` parameter controls whether self-connections are also considered. +#' This model effectively constrains the average number of edges, \eqn{p m_\text{max}}, +#' where \eqn{m_\text{max}} is the largest possible number of edges, +#' which depends on whether the graph is directed or undirected and whether self-loops are allowed. #' #' @param n The number of vertices in the graph. -#' @param p The probability for drawing an edge between two -#' arbitrary vertices (\eqn{G(n,p)} graph). +#' @param p The probability for drawing an edge between two arbitrary vertices (\eqn{G(n,p)} graph). #' @inheritParams rlang::args_dots_empty -#' @param directed Logical, whether the graph will be directed, defaults to -#' `FALSE`. +#' @param directed Logical, whether the graph will be directed, defaults to `FALSE`. #' @param loops Logical, whether to add loop edges, defaults to `FALSE`. #' @return A graph object. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} @@ -1250,9 +1204,9 @@ gnp <- function( #' #' Random graph with a fixed number of edges and vertices. #' -#' The graph has `n` vertices and `m` edges. The edges are chosen uniformly -#' at random from the set of all vertex pairs. This set includes potential -#' self-connections as well if the `loops` parameter is `TRUE`. +#' The graph has `n` vertices and `m` edges. +#' The edges are chosen uniformly at random from the set of all vertex pairs. +#' This set includes potential self-connections as well if the `loops` parameter is `TRUE`. #' #' @param n The number of vertices in the graph. #' @param m The number of edges in the graph. @@ -1388,20 +1342,18 @@ gnm <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' Since igraph version 0.8.0, both `erdos.renyi.game()` and -#' `random.graph.game()` are deprecated, and [sample_gnp()] and -#' [sample_gnm()] should be used instead. See these for more details. +#' Since igraph version 0.8.0, both `erdos.renyi.game()` and `random.graph.game()` are deprecated, +#' and [sample_gnp()] and [sample_gnm()] should be used instead. +#' See these for more details. #' #' `random.graph.game()` is an (also deprecated) alias to this function. #' #' #' @aliases erdos.renyi.game random.graph.game #' @param n The number of vertices in the graph. -#' @param p.or.m Either the probability for drawing an edge between two -#' arbitrary vertices (\eqn{G(n,p)} graph), or the number of edges in -#' the graph (for \eqn{G(n,m)} graphs). -#' @param type The type of the random graph to create, either `gnp()` -#' (\eqn{G(n,p)} graph) or `gnm()` (\eqn{G(n,m)} graph). +#' @param p.or.m Either the probability for drawing an edge between two arbitrary vertices (\eqn{G(n,p)} graph), +#' or the number of edges in the graph (for \eqn{G(n,m)} graphs). +#' @param type The type of the random graph to create, either `gnp()` (\eqn{G(n,p)} graph) or `gnm()` (\eqn{G(n,m)} graph). #' @inheritParams sample_gnp #' @return A graph object. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} @@ -1457,60 +1409,50 @@ random.graph.game <- function( #' Generate random graphs with a given degree sequence #' -#' It is often useful to create a graph with given vertex degrees. This function -#' creates such a graph in a randomized manner. -#' -#' The \dQuote{configuration} method (formerly called "simple") implements the -#' configuration model. For undirected graphs, it puts all vertex IDs in a bag -#' such that the multiplicity of a vertex in the bag is the same as its degree. -#' Then it draws pairs from the bag until the bag becomes empty. This method may -#' generate both loop (self) edges and multiple edges. For directed graphs, -#' the algorithm is basically the same, but two separate bags are used -#' for the in- and out-degrees. Undirected graphs are generated -#' with probability proportional to \eqn{(\prod_{i -#' and the paper . -#' -#' The \dQuote{edge.switching.simple} is an MCMC sampler based on -#' degree-preserving edge switches. It generates simple undirected or directed graphs. -#' -#' @param out.deg Numeric vector, the sequence of degrees (for undirected -#' graphs) or out-degrees (for directed graphs). For undirected graphs its sum -#' should be even. For directed graphs its sum should be the same as the sum of -#' `in.deg`. -#' @param in.deg For directed graph, the in-degree sequence. By default this is -#' `NULL` and an undirected graph is created. +#' This generator should be favoured +#' if undirected and connected graphs are to be generated and execution time is not a concern. igraph uses the original implementation of Fabien Viger; +#' for the algorithm, +#' see and the paper . +#' +#' The \dQuote{edge.switching.simple} is an MCMC sampler based on degree-preserving edge switches. +#' It generates simple undirected or directed graphs. +#' +#' @param out.deg Numeric vector, the sequence of degrees (for undirected graphs) or out-degrees (for directed graphs). +#' For undirected graphs its sum should be even. +#' For directed graphs its sum should be the same as the sum of `in.deg`. +#' @param in.deg For directed graph, the in-degree sequence. +#' By default this is `NULL` and an undirected graph is created. #' @inheritParams rlang::args_dots_empty -#' @param method Character, the method for generating the graph. See Details. +#' @param method Character, the method for generating the graph. +#' See Details. #' @return The new graph object. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @seealso @@ -1757,18 +1699,16 @@ degseq <- function(..., deterministic = FALSE) { #' #' This function creates a random graph by simulating its stochastic evolution. #' -#' This is discrete time step model, in each time step a new vertex is added to -#' the graph and `m` new edges are created. If `citation` is -#' `FALSE` these edges are connecting two uniformly randomly chosen -#' vertices, otherwise the edges are connecting new vertex to uniformly -#' randomly chosen old vertices. +#' This is discrete time step model, in each time step a new vertex is added to the graph and `m` new edges are created. +#' If `citation` is `FALSE` these edges are connecting two uniformly randomly chosen vertices, +#' otherwise the edges are connecting new vertex to uniformly randomly chosen old vertices. #' #' @param n Numeric constant, number of vertices in the graph. #' @param m Numeric constant, number of edges added in each time step. #' @inheritParams rlang::args_dots_empty #' @param directed Logical, whether to create a directed graph. -#' @param citation Logical. If `TRUE` a citation graph is created, i.e. in -#' each time step the added edges are originating from the new vertex. +#' @param citation Logical. +#' If `TRUE` a citation graph is created, i.e. in each time step the added edges are originating from the new vertex. #' @return A new graph object. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @family games @@ -1806,52 +1746,38 @@ growing <- function(n, m = 1, ..., directed = TRUE, citation = FALSE) { #' Generate an evolving random graph with preferential attachment and aging #' -#' This function creates a random graph by simulating its evolution. Each time -#' a new vertex is added it creates a number of links to old vertices and the -#' probability that an old vertex is cited depends on its in-degree -#' (preferential attachment) and age. +#' This function creates a random graph by simulating its evolution. +#' Each time a new vertex is added it creates a number of links to old vertices and the probability that an old vertex is cited depends on its in-degree (preferential attachment) and age. #' -#' This is a discrete time step model of a growing graph. We start with a -#' network containing a single vertex (and no edges) in the first time step. -#' Then in each time step (starting with the second) a new vertex is added and -#' it initiates a number of edges to the old vertices in the network. The -#' probability that an old vertex is connected to is proportional to +#' This is a discrete time step model of a growing graph. +#' We start with a network containing a single vertex (and no edges) in the first time step. +#' Then in each time step (starting with the second) a new vertex is added and it initiates a number of edges to the old vertices in the network. +#' The probability that an old vertex is connected to is proportional to #' \deqn{P[i] \sim (c\cdot k_i^\alpha+a)(d\cdot l_i^\beta+b)}. #' -#' Here \eqn{k_i}{k[i]} is the in-degree of vertex \eqn{i} in the current time -#' step and \eqn{l_i}{l[i]} is the age of vertex \eqn{i}. The age is simply -#' defined as the number of time steps passed since the vertex is added, with -#' the extension that vertex age is divided to be in `aging.bin` bins. -#' -#' \eqn{c}, \eqn{\alpha}{alpha}, \eqn{a}, \eqn{d}, \eqn{\beta}{beta} and -#' \eqn{b} are parameters and they can be set via the following arguments: -#' `pa.exp` (\eqn{\alpha}{alpha}, mandatory argument), `aging.exp` -#' (\eqn{\beta}{beta}, mandatory argument), `zero.deg.appeal` (\eqn{a}, -#' optional, the default value is 1), `zero.age.appeal` (\eqn{b}, -#' optional, the default is 0), `deg.coef` (\eqn{c}, optional, the default -#' is 1), and `age.coef` (\eqn{d}, optional, the default is 1). -#' -#' The number of edges initiated in each time step is governed by the `m`, -#' `out.seq` and `out.pref` parameters. If `out.seq` is given -#' then it is interpreted as a vector giving the number of edges to be added in -#' each time step. It should be of length `n` (the number of vertices), -#' and its first element will be ignored. If `out.seq` is not given (or -#' NULL) and `out.dist` is given then it will be used as a discrete -#' probability distribution to generate the number of edges. Its first element -#' gives the probability that zero edges are added at a time step, the second -#' element is the probability that one edge is added, etc. (`out.seq` -#' should contain non-negative numbers, but if they don't sum up to 1, they -#' will be normalized to sum up to 1. This behavior is similar to the -#' `prob` argument of the `sample` command.) -#' -#' By default a directed graph is generated, but it `directed` is set to -#' `FALSE` then an undirected is created. Even if an undirected graph is -#' generated \eqn{k_i}{k[i]} denotes only the adjacent edges not initiated by -#' the vertex itself except if `out.pref` is set to `TRUE`. -#' -#' If the `time.window` argument is given (and not NULL) then -#' \eqn{k_i}{k[i]} means only the adjacent edges added in the previous -#' `time.window` time steps. +#' Here \eqn{k_i}{k[i]} is the in-degree of vertex \eqn{i} in the current time step and \eqn{l_i}{l[i]} is the age of vertex \eqn{i}. +#' The age is simply defined as the number of time steps passed since the vertex is added, +#' with the extension that vertex age is divided to be in `aging.bin` bins. +#' +#' \eqn{c}, \eqn{\alpha}{alpha}, \eqn{a}, \eqn{d}, +#' \eqn{\beta}{beta} and \eqn{b} are parameters and they can be set via the following arguments: +#' `pa.exp` (\eqn{\alpha}{alpha}, mandatory argument), `aging.exp` (\eqn{\beta}{beta}, mandatory argument), +#' `zero.deg.appeal` (\eqn{a}, optional, the default value is 1), `zero.age.appeal` (\eqn{b}, optional, the default is 0), +#' `deg.coef` (\eqn{c}, optional, the default is 1), and `age.coef` (\eqn{d}, optional, the default is 1). +#' +#' The number of edges initiated in each time step is governed by the `m`, `out.seq` and `out.pref` parameters. +#' If `out.seq` is given then it is interpreted as a vector giving the number of edges to be added in each time step. +#' It should be of length `n` (the number of vertices), and its first element will be ignored. +#' If `out.seq` is not given (or NULL) and `out.dist` is given then it will be used as a discrete probability distribution to generate the number of edges. +#' Its first element gives the probability that zero edges are added at a time step, +#' the second element is the probability that one edge is added, +#' etc. (`out.seq` should contain non-negative numbers, but if they don't sum up to 1, they will be normalized to sum up to 1. This behavior is similar to the `prob` argument of the `sample` command.) +#' +#' By default a directed graph is generated, but it `directed` is set to `FALSE` then an undirected is created. +#' Even if an undirected graph is generated \eqn{k_i}{k[i]} denotes only the adjacent edges not initiated by the vertex itself except +#' if `out.pref` is set to `TRUE`. +#' +#' If the `time.window` argument is given (and not NULL) then \eqn{k_i}{k[i]} means only the adjacent edges added in the previous `time.window` time steps. #' #' This function might generate graphs with multiple edges. #' @@ -1859,32 +1785,29 @@ growing <- function(n, m = 1, ..., directed = TRUE, citation = FALSE) { #' @param pa.exp The preferential attachment exponent, see the details below. #' @param aging.exp The exponent of the aging, usually a non-positive number, #' see details below. -#' @param m The number of edges each new vertex creates (except the very first -#' vertex). This argument is used only if both the `out.dist` and -#' `out.seq` arguments are NULL. +#' @param m The number of edges each new vertex creates (except the very first vertex). +#' This argument is used only if both the `out.dist` and `out.seq` arguments are NULL. #' @inheritParams rlang::args_dots_empty -#' @param aging.bin The number of bins to use for measuring the age of -#' vertices, see details below. -#' @param out.dist The discrete distribution to generate the number of edges to -#' add in each time step if `out.seq` is NULL. See details below. -#' @param out.seq The number of edges to add in each time step, a vector -#' containing as many elements as the number of vertices. See details below. -#' @param out.pref Logical, whether to include edges not initiated by -#' the vertex as a basis of preferential attachment. See details below. -#' @param directed Logical, whether to generate a directed graph. See -#' details below. -#' @param zero.deg.appeal The degree-dependent part of the -#' \sQuote{attractiveness} of the vertices with no adjacent edges. See also -#' details below. -#' @param zero.age.appeal The age-dependent part of the \sQuote{attrativeness} -#' of the vertices with age zero. It is usually zero, see details below. -#' @param deg.coef The coefficient of the degree-dependent -#' \sQuote{attractiveness}. See details below. -#' @param age.coef The coefficient of the age-dependent part of the -#' \sQuote{attractiveness}. See details below. -#' @param time.window Integer constant, if NULL only adjacent added in the last -#' `time.windows` time steps are counted as a basis of the preferential -#' attachment. See also details below. +#' @param aging.bin The number of bins to use for measuring the age of vertices, see details below. +#' @param out.dist The discrete distribution to generate the number of edges to add in each time step if `out.seq` is NULL. +#' See details below. +#' @param out.seq The number of edges to add in each time step, a vector containing as many elements as the number of vertices. +#' See details below. +#' @param out.pref Logical, whether to include edges not initiated by the vertex as a basis of preferential attachment. +#' See details below. +#' @param directed Logical, whether to generate a directed graph. +#' See details below. +#' @param zero.deg.appeal The degree-dependent part of the \sQuote{attractiveness} of the vertices with no adjacent edges. +#' See also details below. +#' @param zero.age.appeal The age-dependent part of the \sQuote{attrativeness} of the vertices with age zero. +#' It is usually zero, see details below. +#' @param deg.coef The coefficient of the degree-dependent \sQuote{attractiveness}. +#' See details below. +#' @param age.coef The coefficient of the age-dependent part of the \sQuote{attractiveness}. +#' See details below. +#' @param time.window Integer constant, +#' if NULL only adjacent added in the last `time.windows` time steps are counted as a basis of the preferential attachment. +#' See also details below. #' @return A new graph. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @family games @@ -2184,31 +2107,27 @@ pa_age <- function( #' Graph generation based on different vertex types #' -#' These functions implement evolving network models based on different vertex -#' types. +#' These functions implement evolving network models based on different vertex types. #' -#' For `sample_traits_callaway()` the simulation goes like this: in each -#' discrete time step a new vertex is added to the graph. The type of this -#' vertex is generated based on `type.dist`. Then two vertices are -#' selected uniformly randomly from the graph. The probability that they will -#' be connected depends on the types of these vertices and is taken from -#' `pref.matrix`. Then another two vertices are selected and this is -#' repeated `edges.per.step` times in each time step. +#' For `sample_traits_callaway()` the simulation goes like this: in each discrete time step a new vertex is added to the graph. +#' The type of this vertex is generated based on `type.dist`. +#' Then two vertices are selected uniformly randomly from the graph. +#' The probability that they will be connected depends on the types of these vertices and is taken from `pref.matrix`. +#' Then another two vertices are selected and this is repeated `edges.per.step` times in each time step. #' -#' For `sample_traits()` the simulation goes like this: a single vertex is -#' added at each time step. This new vertex tries to connect to `k` -#' vertices in the graph. The probability that such a connection is realized -#' depends on the types of the vertices involved and is taken from -#' `pref.matrix`. +#' For `sample_traits()` the simulation goes like this: a single vertex is added at each time step. +#' This new vertex tries to connect to `k` vertices in the graph. +#' The probability that such a connection is realized depends on the types of the vertices involved and is taken from `pref.matrix`. #' #' @param nodes The number of vertices in the graph. #' @param types The number of different vertex types. #' @inheritParams rlang::args_dots_empty #' @param edge.per.step The number of edges to add to the graph per time step. -#' @param type.dist The distribution of the vertex types. This is assumed to be -#' stationary in time. The default `NULL` gives a uniform distribution. -#' @param pref.matrix A matrix giving the preferences of the given vertex -#' types. These should be probabilities, i.e. numbers between zero and one. +#' @param type.dist The distribution of the vertex types. +#' This is assumed to be stationary in time. +#' The default `NULL` gives a uniform distribution. +#' @param pref.matrix A matrix giving the preferences of the given vertex types. +#' These should be probabilities, i.e. numbers between zero and one. #' The default `NULL` sets all preferences to one. #' @param directed Logical, whether to generate directed graphs. #' @param k The number of trials per time step, see details below. @@ -2529,24 +2448,19 @@ traits <- function( #' Geometric random graphs #' -#' Generate a random graph based on the distance of random point on a unit -#' square +#' Generate a random graph based on the distance of random point on a unit square #' -#' First a number of points are dropped on a unit square, these points -#' correspond to the vertices of the graph to create. Two points will be -#' connected with an undirected edge if they are closer to each other in -#' Euclidean norm than a given radius. If the `torus` argument is -#' `TRUE` then a unit area torus is used instead of a square. +#' First a number of points are dropped on a unit square, these points correspond to the vertices of the graph to create. +#' Two points will be connected with an undirected edge if they are closer to each other in Euclidean norm than a given radius. +#' If the `torus` argument is `TRUE` then a unit area torus is used instead of a square. #' #' @param nodes The number of vertices in the graph. -#' @param radius The radius within which the vertices will be connected by an -#' edge. +#' @param radius The radius within which the vertices will be connected by an edge. #' @inheritParams rlang::args_dots_empty #' @param torus Logical, whether to use a torus instead of a square. -#' @param coords Logical, whether to add the positions of the vertices -#' as vertex attributes called \sQuote{`x`} and \sQuote{`y`}. -#' @return A graph object. If `coords` is `TRUE` then with vertex -#' attributes \sQuote{`x`} and \sQuote{`y`}. +#' @param coords Logical, whether to add the positions of the vertices as vertex attributes called \sQuote{`x`} and \sQuote{`y`}. +#' @return A graph object. +#' If `coords` is `TRUE` then with vertex attributes \sQuote{`x`} and \sQuote{`y`}. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com}, first version was #' written by Keith Briggs (). #' @family games @@ -2683,40 +2597,32 @@ grg <- function( #' #' Generation of random graphs based on different vertex types. #' -#' Both models generate random graphs with given vertex types. For -#' `sample_pref()` the probability that two vertices will be connected -#' depends on their type and is given by the \sQuote{pref.matrix} argument. -#' This matrix should be symmetric to make sense but this is not checked. The -#' distribution of the different vertex types is given by the -#' \sQuote{type.dist} vector. +#' Both models generate random graphs with given vertex types. +#' For `sample_pref()` the probability that two vertices will be connected depends on their type and is given by the \sQuote{pref.matrix} argument. +#' This matrix should be symmetric to make sense but this is not checked. +#' The distribution of the different vertex types is given by the \sQuote{type.dist} vector. #' -#' For `sample_asym_pref()` each vertex has an in-type and an -#' out-type and a directed graph is created. The probability that a directed -#' edge is realized from a vertex with a given out-type to a vertex with a -#' given in-type is given in the \sQuote{pref.matrix} argument, which can be -#' asymmetric. The joint distribution for the in- and out-types is given in the -#' \sQuote{type.dist.matrix} argument. +#' For `sample_asym_pref()` each vertex has an in-type and an out-type and a directed graph is created. +#' The probability that a directed edge is realized from a vertex with a given out-type to a vertex with a given in-type is given in the \sQuote{pref.matrix} argument, +#' which can be asymmetric. +#' The joint distribution for the in- and out-types is given in the \sQuote{type.dist.matrix} argument. #' -#' The types of the generated vertices can be retrieved from the -#' `type` vertex attribute for `sample_pref()` and from the -#' `intype` and `outtype` vertex attribute for `sample_asym_pref()`. +#' The types of the generated vertices can be retrieved from the `type` vertex attribute for `sample_pref()` and from the `intype` and `outtype` vertex attribute for `sample_asym_pref()`. #' #' @param nodes The number of vertices in the graphs. #' @param types The number of different vertex types. #' @inheritParams rlang::args_dots_empty -#' @param type.dist The distribution of the vertex types, a numeric vector of -#' length \sQuote{types} containing non-negative numbers. The vector will be -#' normed to obtain probabilities. The default `NULL` gives a uniform -#' distribution. -#' @param fixed.sizes Fix the number of vertices with a given vertex type -#' label. The `type.dist` argument gives the group sizes (i.e. number of -#' vertices with the different labels) in this case. -#' @param type.dist.matrix The joint distribution of the in- and out-vertex -#' types. The default `NULL` gives a uniform distribution. -#' @param pref.matrix A square matrix giving the preferences of the vertex -#' types. The matrix has \sQuote{types} rows and columns. When generating -#' an undirected graph, it must be symmetric. The default `NULL` sets all -#' preferences to one. +#' @param type.dist The distribution of the vertex types, a numeric vector of length \sQuote{types} containing non-negative numbers. +#' The vector will be normed to obtain probabilities. +#' The default `NULL` gives a uniform distribution. +#' @param fixed.sizes Fix the number of vertices with a given vertex type label. +#' The `type.dist` argument gives the group sizes (i.e. number of vertices with the different labels) in this case. +#' @param type.dist.matrix The joint distribution of the in- and out-vertex types. +#' The default `NULL` gives a uniform distribution. +#' @param pref.matrix A square matrix giving the preferences of the vertex types. +#' The matrix has \sQuote{types} rows and columns. +#' When generating an undirected graph, it must be symmetric. +#' The default `NULL` sets all preferences to one. #' @param directed Logical, whether to create a directed graph. #' @param loops Logical, whether self-loops are allowed in the graph. #' @return An igraph graph. @@ -3129,36 +3035,28 @@ connect <- function( #' The Watts-Strogatz small-world model #' -#' This function generates networks with the small-world property -#' based on a variant of the Watts-Strogatz model. The network is obtained -#' by first creating a periodic undirected lattice, then rewiring both -#' endpoints of each edge with probability `p`, while avoiding the -#' creation of multi-edges. +#' This function generates networks with the small-world property based on a variant of the Watts-Strogatz model. +#' The network is obtained by first creating a periodic undirected lattice, then rewiring both endpoints of each edge with probability `p`, +#' while avoiding the creation of multi-edges. #' -#' Note that this function might create graphs with loops and/or multiple -#' edges. You can use [simplify()] to get rid of these. +#' Note that this function might create graphs with loops and/or multiple edges. +#' You can use [simplify()] to get rid of these. #' #' @details -#' This process differs from the original model of Watts and Strogatz -#' (see reference) in that it rewires **both** endpoints of edges. Thus in -#' the limit of `p=1`, we obtain a G(n,m) random graph with the -#' same number of vertices and edges as the original lattice. In comparison, -#' the original Watts-Strogatz model only rewires a single endpoint of each edge, +#' This process differs from the original model of Watts and Strogatz (see reference) in that it rewires **both** endpoints of edges. +#' Thus in the limit of `p=1`, we obtain a G(n,m) random graph with the same number of vertices and edges as the original lattice. +#' In comparison, the original Watts-Strogatz model only rewires a single endpoint of each edge, #' thus the network does not become fully random even for `p=1`. -#' For appropriate choices of `p`, both models exhibit the property of -#' simultaneously having short path lengths and high clustering. +#' For appropriate choices of `p`, both models exhibit the property of simultaneously having short path lengths and high clustering. #' #' #' @param dim Integer constant, the dimension of the starting lattice. #' @param size Integer constant, the size of the lattice along each dimension. -#' @param nei Integer constant, the neighborhood within which the vertices of -#' the lattice will be connected. +#' @param nei Integer constant, the neighborhood within which the vertices of the lattice will be connected. #' @param p Real constant between zero and one, the rewiring probability. #' @inheritParams rlang::args_dots_empty -#' @param loops Logical, whether loops edges are allowed in the -#' generated graph. -#' @param multiple Logical, whether multiple edges are allowed int the -#' generated graph. +#' @param loops Logical, whether loops edges are allowed in the generated graph. +#' @param multiple Logical, whether multiple edges are allowed int the generated graph. #' @return A graph object. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @seealso [make_lattice()], [rewire()] @@ -3303,32 +3201,25 @@ smallworld <- function( #' Random citation graphs #' -#' `sample_last_cit()` creates a graph, where vertices age, and -#' gain new connections based on how long ago their last citation -#' happened. +#' `sample_last_cit()` creates a graph, where vertices age, and gain new connections based on how long ago their last citation happened. #' -#' `sample_cit_cit_types()` is a stochastic block model where the -#' graph is growing. +#' `sample_cit_cit_types()` is a stochastic block model where the graph is growing. #' #' `sample_cit_types()` is similarly a growing stochastic block model, -#' but the probability of an edge depends on the (potentially) cited -#' vertex only. +#' but the probability of an edge depends on the (potentially) cited vertex only. #' #' @param n Number of vertices. #' @param edges Number of edges per step. #' @inheritParams rlang::args_dots_empty -#' @param agebins Number of aging bins. The default `NULL` uses `n / 7100`. -#' @param pref Vector (`sample_last_cit()` and `sample_cit_types()` or -#' matrix (`sample_cit_cit_types()`) giving the (unnormalized) citation -#' probabilities for the different vertex types. The default `NULL` uses -#' `(1:(agebins + 1))^-3` for `sample_last_cit()` and all-one probabilities -#' for the other two. +#' @param agebins Number of aging bins. +#' The default `NULL` uses `n / 7100`. +#' @param pref Vector (`sample_last_cit()` and `sample_cit_types()` or matrix (`sample_cit_cit_types()`) giving the (unnormalized) citation probabilities for the different vertex types. +#' The default `NULL` uses `(1:(agebins + 1))^-3` for `sample_last_cit()` and all-one probabilities for the other two. #' @param directed Logical, whether to generate directed networks. #' @param types Vector of length \sQuote{`n`}, the types of the vertices. -#' Types are numbered from zero. The default `NULL` gives all vertices -#' type zero. -#' @param attr Logical, whether to add the vertex types to the generated -#' graph as a vertex attribute called \sQuote{`type`}. +#' Types are numbered from zero. +#' The default `NULL` gives all vertices type zero. +#' @param attr Logical, whether to add the vertex types to the generated graph as a vertex attribute called \sQuote{`type`}. #' @return A new graph. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @keywords graphs @@ -3768,21 +3659,21 @@ cit_cit_types <- function( #' #' @param n1 Integer scalar, the number of bottom vertices. #' @param n2 Integer scalar, the number of top vertices. -#' @param type Character scalar, the type of the graph, \sQuote{gnp} creates a -#' \eqn{G(n,p)} graph, \sQuote{gnm} creates a \eqn{G(n,m)} graph. See details below. -#' @param p Real scalar, connection probability for \eqn{G(n,p)} graphs. Should not -#' be given for \eqn{G(n,m)} graphs. -#' @param m Integer scalar, the number of edges for \eqn{G(n,m)} graphs. Should not -#' be given for \eqn{G(n,p)} graphs. -#' @param directed Logical, whether to create a directed graph. See also -#' the `mode` argument. -#' @param mode Character scalar, specifies how to direct the edges in directed -#' graphs. If it is \sQuote{out}, then directed edges point from bottom -#' vertices to top vertices. If it is \sQuote{in}, edges point from top -#' vertices to bottom vertices. \sQuote{out} and \sQuote{in} do not generate -#' mutual edges. If this argument is \sQuote{all}, then each edge direction is -#' considered independently and mutual edges might be generated. This argument -#' is ignored for undirected graphs. +#' @param type Character scalar, the type of the graph, \sQuote{gnp} creates a \eqn{G(n,p)} graph, +#' \sQuote{gnm} creates a \eqn{G(n,m)} graph. +#' See details below. +#' @param p Real scalar, connection probability for \eqn{G(n,p)} graphs. +#' Should not be given for \eqn{G(n,m)} graphs. +#' @param m Integer scalar, the number of edges for \eqn{G(n,m)} graphs. +#' Should not be given for \eqn{G(n,p)} graphs. +#' @param directed Logical, whether to create a directed graph. +#' See also the `mode` argument. +#' @param mode Character scalar, specifies how to direct the edges in directed graphs. +#' If it is \sQuote{out}, then directed edges point from bottom vertices to top vertices. +#' If it is \sQuote{in}, edges point from top vertices to bottom vertices. +#' \sQuote{out} and \sQuote{in} do not generate mutual edges. +#' If this argument is \sQuote{all}, then each edge direction is considered independently and mutual edges might be generated. +#' This argument is ignored for undirected graphs. #' @return A bipartite igraph graph. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @family games @@ -3905,11 +3796,11 @@ bipartite_gnp <- function( #' #' Generate bipartite graphs using the Erdős-Rényi model #' -#' Similarly to unipartite (one-mode) networks, we can define the \eqn{G(n,p)}, and -#' \eqn{G(n,m)} graph classes for bipartite graphs, via their generating process. -#' In \eqn{G(n,p)} every possible edge between top and bottom vertices is realized -#' with probability \eqn{p}, independently of the rest of the edges. In \eqn{G(n,m)}, we -#' uniformly choose \eqn{m} edges to realize. +#' Similarly to unipartite (one-mode) networks, we can define the \eqn{G(n,p)}, and \eqn{G(n,m)} graph classes for bipartite graphs, +#' via their generating process. +#' In \eqn{G(n,p)} every possible edge between top and bottom vertices is realized with probability \eqn{p}, +#' independently of the rest of the edges. +#' In \eqn{G(n,m)}, we uniformly choose \eqn{m} edges to realize. #' #' #' @param n1 Integer scalar, the number of bottom vertices. @@ -3917,15 +3808,14 @@ bipartite_gnp <- function( #' @param p Real scalar, connection probability for \eqn{G(n,p)} graphs. #' @param m Integer scalar, the number of edges for \eqn{G(n,m)} graphs. #' @inheritParams rlang::args_dots_empty -#' @param directed Logical, whether to create a directed graph. See also -#' the `mode` argument. -#' @param mode Character scalar, specifies how to direct the edges in directed -#' graphs. If it is \sQuote{out}, then directed edges point from bottom -#' vertices to top vertices. If it is \sQuote{in}, edges point from top -#' vertices to bottom vertices. \sQuote{out} and \sQuote{in} do not generate -#' mutual edges. If this argument is \sQuote{all}, then each edge direction is -#' considered independently and mutual edges might be generated. This argument -#' is ignored for undirected graphs. +#' @param directed Logical, whether to create a directed graph. +#' See also the `mode` argument. +#' @param mode Character scalar, specifies how to direct the edges in directed graphs. +#' If it is \sQuote{out}, then directed edges point from bottom vertices to top vertices. +#' If it is \sQuote{in}, edges point from top vertices to bottom vertices. +#' \sQuote{out} and \sQuote{in} do not generate mutual edges. +#' If this argument is \sQuote{all}, then each edge direction is considered independently and mutual edges might be generated. +#' This argument is ignored for undirected graphs. #' @examples #' #' ## empty graph @@ -4004,20 +3894,17 @@ sample_bipartite_gnp <- function( #' #' Sampling from the stochastic block model of networks #' -#' This function samples graphs from a stochastic block model by (doing the -#' equivalent of) Bernoulli trials for each potential edge with the -#' probabilities given by the Bernoulli rate matrix, `pref.matrix`. -#' The order of the vertices in the generated graph corresponds to the -#' `block.sizes` argument. +#' This function samples graphs from a stochastic block model by (doing the equivalent of) Bernoulli trials for each potential edge with the probabilities given by the Bernoulli rate matrix, `pref.matrix`. +#' The order of the vertices in the generated graph corresponds to the `block.sizes` argument. #' #' @param n Number of vertices in the graph. -#' @param pref.matrix The matrix giving the Bernoulli rates. This is a -#' \eqn{K\times K}{KxK} matrix, where \eqn{K} is the number of groups. The -#' probability of creating an edge between vertices from groups \eqn{i} and -#' \eqn{j} is given by element \eqn{(i,j)}. For undirected graphs, this matrix -#' must be symmetric. -#' @param block.sizes Numeric vector giving the number of vertices in each -#' group. The sum of the vector must match the number of vertices. +#' @param pref.matrix The matrix giving the Bernoulli rates. +#' This is a \eqn{K\times K}{KxK} matrix, +#' where \eqn{K} is the number of groups. +#' The probability of creating an edge between vertices from groups \eqn{i} and \eqn{j} is given by element \eqn{(i,j)}. +#' For undirected graphs, this matrix must be symmetric. +#' @param block.sizes Numeric vector giving the number of vertices in each group. +#' The sum of the vector must match the number of vertices. #' @inheritParams sample_pref #' @inheritParams rlang::args_dots_empty #' @return An igraph graph. @@ -4151,23 +4038,19 @@ sbm <- function( #' #' Sampling from a hierarchical stochastic block model of networks. #' -#' The function generates a random graph according to the hierarchical -#' stochastic block model. +#' The function generates a random graph according to the hierarchical stochastic block model. #' #' @param n Integer scalar, the number of vertices. -#' @param m Integer scalar, the number of vertices per block. `n / m` must -#' be integer. Alternatively, an integer vector of block sizes, if not all the -#' blocks have equal sizes. -#' @param rho Numeric vector, the fraction of vertices per cluster, within a -#' block. Must sum up to 1, and `rho * m` must be integer for all elements -#' of rho. Alternatively a list of rho vectors, one for each block, if they are -#' not the same for all blocks. -#' @param C A square, symmetric numeric matrix, the Bernoulli rates for the -#' clusters within a block. Its size must mach the size of the `rho` -#' vector. Alternatively, a list of square matrices, if the Bernoulli rates -#' differ in different blocks. -#' @param p Numeric scalar, the Bernoulli rate of connections between vertices -#' in different blocks. +#' @param m Integer scalar, the number of vertices per block. +#' `n / m` must be integer. +#' Alternatively, an integer vector of block sizes, if not all the blocks have equal sizes. +#' @param rho Numeric vector, the fraction of vertices per cluster, within a block. +#' Must sum up to 1, and `rho * m` must be integer for all elements of rho. +#' Alternatively a list of rho vectors, one for each block, if they are not the same for all blocks. +#' @param C A square, symmetric numeric matrix, the Bernoulli rates for the clusters within a block. +#' Its size must mach the size of the `rho` vector. +#' Alternatively, a list of square matrices, if the Bernoulli rates differ in different blocks. +#' @param p Numeric scalar, the Bernoulli rate of connections between vertices in different blocks. #' @return An igraph graph. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @keywords graphs @@ -4246,23 +4129,17 @@ hierarchical_sbm <- function(n, m, rho, C, p) { #' Generate random graphs according to the random dot product graph model #' #' In this model, each vertex is represented by a latent position vector. -#' Probability of an edge between two vertices are given by the dot product of -#' their latent position vectors. +#' Probability of an edge between two vertices are given by the dot product of their latent position vectors. #' -#' The dot product of the latent position vectors should be in the \[0,1\] -#' interval, otherwise a warning is given. For negative dot products, no edges -#' are added; dot products that are larger than one always add an edge. +#' The dot product of the latent position vectors should be in the \[0,1\] interval, otherwise a warning is given. +#' For negative dot products, no edges are added; dot products that are larger than one always add an edge. #' -#' @param vecs A numeric matrix in which each latent position vector is a -#' column. +#' @param vecs A numeric matrix in which each latent position vector is a column. #' @inheritParams rlang::args_dots_empty -#' @param directed A Logical, TRUE if the generated graph should be -#' directed. -#' @return An igraph graph object which is the generated random dot product -#' graph. +#' @param directed A Logical, TRUE if the generated graph should be directed. +#' @return An igraph graph object which is the generated random dot product graph. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso [sample_dirichlet()], [sample_sphere_surface()] -#' and [sample_sphere_volume()] for sampling position vectors. +#' @seealso [sample_dirichlet()], [sample_sphere_surface()] and [sample_sphere_volume()] for sampling position vectors. #' @references Christine Leigh Myers Nickel: Random dot product graphs, a model #' for social networks. Dissertation, Johns Hopkins University, Maryland, USA, #' 2006. @@ -4378,8 +4255,7 @@ dot_product <- function( #' A graph with subgraphs that are each a random graph. #' -#' Create a number of Erdős-Rényi random graphs with identical parameters, and -#' connect them with the specified number of edges. +#' Create a number of Erdős-Rényi random graphs with identical parameters, and connect them with the specified number of edges. #' #' @section Examples: #' \preformatted{ @@ -4390,8 +4266,7 @@ dot_product <- function( #' #' @param islands.n The number of islands in the graph. #' @param islands.size The size of islands in the graph. -#' @param islands.pin The probability to create each possible edge into each -#' island. +#' @param islands.pin The probability to create each possible edge into each island. #' @param n.inter The number of edges to create between two islands. #' @return An igraph graph. #' @author Samuel Thiriot @@ -4423,24 +4298,19 @@ sample_islands <- function(islands.n, islands.size, islands.pin, n.inter) { #' #' Generate a random graph where each vertex has the same degree. #' -#' This game generates a directed or undirected random graph where the degrees -#' of vertices are equal to a predefined constant k. For undirected graphs, at -#' least one of k and the number of vertices must be even. +#' This game generates a directed or undirected random graph where the degrees of vertices are equal to a predefined constant k. +#' For undirected graphs, at least one of k and the number of vertices must be even. #' -#' The game simply uses [sample_degseq()] with appropriately -#' constructed degree sequences. +#' The game simply uses [sample_degseq()] with appropriately constructed degree sequences. #' -#' @param no.of.nodes Integer scalar, the number of vertices in the generated -#' graph. -#' @param k Integer scalar, the degree of each vertex in the graph, or the -#' out-degree and in-degree in a directed graph. +#' @param no.of.nodes Integer scalar, the number of vertices in the generated graph. +#' @param k Integer scalar, the degree of each vertex in the graph, or the out-degree and in-degree in a directed graph. #' @inheritParams rlang::args_dots_empty #' @param directed Logical, whether to create a directed graph. #' @param multiple Logical, whether multiple edges are allowed. #' @return An igraph graph. #' @author Tamas Nepusz \email{ntamas@@gmail.com} -#' @seealso [sample_degseq()] for a generator with prescribed degree -#' sequence. +#' @seealso [sample_degseq()] for a generator with prescribed degree sequence. #' @keywords graphs #' @examples #' @@ -4513,71 +4383,51 @@ sample_k_regular <- function( #' @description #' `r lifecycle::badge("experimental")` #' -#' The Chung-Lu model is useful for generating random graphs with fixed expected -#' degrees. This function implements both the original model of Chung and Lu, as -#' well as some additional variants with useful properties. +#' The Chung-Lu model is useful for generating random graphs with fixed expected degrees. +#' This function implements both the original model of Chung and Lu, as well as some additional variants with useful properties. #' #' @details -#' In the original Chung-Lu model, each pair of vertices \eqn{i} and \eqn{j} is -#' connected with independent probability +#' In the original Chung-Lu model, each pair of vertices \eqn{i} and \eqn{j} is connected with independent probability #' \deqn{p_{ij} = \frac{w_i w_j}{S},}{p_ij = w_i w_j / S,} #' where \eqn{w_i} is a weight associated with vertex \eqn{i} and #' \deqn{S = \sum_k w_k}{S = sum_k w_k} -#' is the sum of weights. In the directed variant, vertices have both -#' out-weights, \eqn{w^\text{out}}{w^out}, and in-weights, -#' \eqn{w^\text{in}}{w^in}, with equal sums, +#' is the sum of weights. +#' In the directed variant, vertices have both out-weights, \eqn{w^\text{out}}{w^out}, and in-weights, \eqn{w^\text{in}}{w^in}, +#' with equal sums, #' \deqn{S = \sum_k w^\text{out}_k = \sum_k w^\text{in}_k.}{S = sum_k w^out_k = sum_k w^in_k.} #' The connection probability between \eqn{i} and \eqn{j} is #' \deqn{p_{ij} = \frac{w^\text{out}_i w^\text{in}_j.}{S}}{p_ij = w^out_i w^in_j / S.} #' -#' This model is commonly used to create random graphs with a fixed -#' \emph{expected} degree sequence. The expected degree of vertex \eqn{i} is -#' approximately equal to the weight \eqn{w_i}. Specifically, if the graph is -#' directed and self-loops are allowed, then the expected out- and in-degrees -#' are precisely \eqn{w^\text{out}}{w^out} and \eqn{w^\text{in}}{w^in}. If -#' self-loops are disallowed, then the expected out- and in-degrees are -#' \eqn{\frac{w^\text{out} (S - w^\text{in})}{S}}{w^out (S - w^in) / S} -#' and -#' \eqn{\frac{w^\text{in} (S - w^\text{out})}{S}}{w^in (S - w^out) / S}, -#' respectively. If the graph is undirected, then the expected degrees with and -#' without self-loops are -#' \eqn{\frac{w (S + w)}{S}}{w (S + w) / S} -#' and -#' \eqn{\frac{w (S - w)}{S}}{w (S - w) / S}, -#' respectively. -#' -#' A limitation of the original Chung-Lu model is that when some of the weights -#' are large, the formula for \eqn{p_{ij}}{p_ij} yields values larger than 1. -#' Chung -#' and Lu's original paper excludes the use of such weights. When -#' \eqn{p_{ij} > 1}{p_ij > 1}, this function simply issues a warning and creates -#' a connection between \eqn{i} and \eqn{j}. However, in this case the expected -#' degrees will no longer relate to the weights in the manner stated above. Thus, -#' the original Chung-Lu model cannot produce certain (large) expected degrees. -#' -#' To overcome this limitation, this function implements additional variants of -#' the model, with modified expressions for the connection probability -#' \eqn{p_{ij}}{p_ij} between vertices \eqn{i} and \eqn{j}. Let -#' \eqn{q_{ij} = \frac{w_i w_j}{S}}{q_ij = w_i w_j / S}, or -#' \eqn{q_{ij} = \frac{w^\text{out}_i w^\text{in}_j}{S}}{q_ij = w^out_i w^in_j / S} -#' in the directed case. All model variants become equivalent in the limit of sparse -#' graphs where \eqn{q_{ij}} approaches zero. In the original Chung-Lu model, -#' selectable by setting \code{variant} to \dQuote{original}, \eqn{p_{ij} = -#' \min(q_{ij}, 1)}{p_ij = min(q_ij, 1)}. The \dQuote{maxent} variant, -#' sometimes referred to as the generalized random graph, uses \eqn{p_{ij} = -#' \frac{q_{ij}}{1 + q_{ij}}}{p_ij = q_ij / (1 + q_ij)}, and is equivalent to a -#' maximum entropy model (i.e., exponential random graph model) with a -#' constraint on expected degrees; -#' see Park and Newman (2004), Section B, setting \eqn{\exp(-\Theta_{ij}) = -#' \frac{w_i w_j}{S}}{exp(-Theta_ij) = w_i w_j / S}. This model is also discussed -#' by Britton, Deijfen, and Martin-Löf (2006). By virtue of being a -#' degree-constrained maximum entropy model, it generates graphs with the same -#' degree sequence with the same probability. A third variant can be requested -#' with \dQuote{nr}, and uses \eqn{p_{ij} = 1 - \exp(-q_{ij})}{p_ij = 1 - -#' exp(-q_ij)}. This is the underlying simple graph of a multigraph model -#' introduced by Norros and Reittu (2006). For a discussion of these three model -#' variants, see Section 16.4 of Bollobás, Janson, Riordan (2007), as well as -#' Van Der Hofstad (2013). +#' This model is commonly used to create random graphs with a fixed \emph{expected} degree sequence. +#' The expected degree of vertex \eqn{i} is approximately equal to the weight \eqn{w_i}. +#' Specifically, if the graph is directed and self-loops are allowed, +#' then the expected out- and in-degrees are precisely \eqn{w^\text{out}}{w^out} and \eqn{w^\text{in}}{w^in}. +#' If self-loops are disallowed, +#' then the expected out- and in-degrees are \eqn{\frac{w^\text{out} (S - w^\text{in})}{S}}{w^out (S - w^in) / S} and \eqn{\frac{w^\text{in} (S - w^\text{out})}{S}}{w^in (S - w^out) / S}, respectively. +#' If the graph is undirected, +#' then the expected degrees with and without self-loops are \eqn{\frac{w (S + w)}{S}}{w (S + w) / S} and \eqn{\frac{w (S - w)}{S}}{w (S - w) / S}, respectively. +#' +#' A limitation of the original Chung-Lu model is that when some of the weights are large, +#' the formula for \eqn{p_{ij}}{p_ij} yields values larger than 1. Chung and Lu's original paper excludes the use of such weights. +#' When \eqn{p_{ij} > 1}{p_ij > 1}, this function simply issues a warning and creates a connection between \eqn{i} and \eqn{j}. +#' However, in this case the expected degrees will no longer relate to the weights in the manner stated above. +#' Thus, the original Chung-Lu model cannot produce certain (large) expected degrees. +#' +#' To overcome this limitation, this function implements additional variants of the model, +#' with modified expressions for the connection probability \eqn{p_{ij}}{p_ij} between vertices \eqn{i} and \eqn{j}. +#' Let \eqn{q_{ij} = \frac{w_i w_j}{S}}{q_ij = w_i w_j / S}, or \eqn{q_{ij} = \frac{w^\text{out}_i w^\text{in}_j}{S}}{q_ij = w^out_i w^in_j / S} in the directed case. +#' All model variants become equivalent in the limit of sparse graphs where \eqn{q_{ij}} approaches zero. +#' In the original Chung-Lu model, selectable by setting \code{variant} to \dQuote{original}, +#' \eqn{p_{ij} = \min(q_{ij}, 1)}{p_ij = min(q_ij, 1)}. +#' The \dQuote{maxent} variant, sometimes referred to as the generalized random graph, uses \eqn{p_{ij} = \frac{q_{ij}}{1 + q_{ij}}}{p_ij = q_ij / (1 + q_ij)}, +#' and is equivalent to a maximum entropy model (i.e., exponential random graph model) with a constraint on expected degrees; see Park and Newman (2004), +#' Section B, setting \eqn{\exp(-\Theta_{ij}) = \frac{w_i w_j}{S}}{exp(-Theta_ij) = w_i w_j / S}. +#' This model is also discussed by Britton, Deijfen, and Martin-Löf (2006). +#' By virtue of being a degree-constrained maximum entropy model, +#' it generates graphs with the same degree sequence with the same probability. +#' A third variant can be requested with \dQuote{nr}, and uses \eqn{p_{ij} = 1 - \exp(-q_{ij})}{p_ij = 1 - exp(-q_ij)}. +#' This is the underlying simple graph of a multigraph model introduced by Norros and Reittu (2006). +#' For a discussion of these three model variants, see Section 16.4 of Bollobás, Janson, Riordan (2007), as well as Van Der Hofstad (2013). #' #' @references Chung, F., and Lu, L. (2002). Connected components in a random #' graph with given degree sequences. Annals of Combinatorics, 6, 125-145. @@ -4607,19 +4457,15 @@ sample_k_regular <- function( #' #' @inheritParams rlang::args_dots_empty #' @param out.weights A vector of non-negative vertex weights (or out-weights). -#' In sparse graphs, these will be approximately equal to the expected -#' (out-)degrees. -#' @param in.weights A vector of non-negative in-weights, approximately equal to -#' the expected in-degrees in sparse graphs. May be set to \code{NULL}, in -#' which case undirected graphs are generated. -#' @param loops Logical, whether to allow the creation of self-loops. Since -#' vertex pairs are connected independently, setting this to \code{FALSE} is -#' equivalent to simply discarding self-loops from an existing loopy Chung-Lu -#' graph. -#' @param variant The model variant to sample from, with different definitions -#' of the connection probability between vertices \eqn{i} and \eqn{j}. Given -#' \eqn{q_{ij} = \frac{w_i w_j}{S}}{q_ij = w_i w_j / S}, the following -#' formulations are available: +#' In sparse graphs, these will be approximately equal to the expected (out-)degrees. +#' @param in.weights A vector of non-negative in-weights, approximately equal to the expected in-degrees in sparse graphs. +#' May be set to \code{NULL}, in which case undirected graphs are generated. +#' @param loops Logical, whether to allow the creation of self-loops. +#' Since vertex pairs are connected independently, +#' setting this to \code{FALSE} is equivalent to simply discarding self-loops from an existing loopy Chung-Lu graph. +#' @param variant The model variant to sample from, +#' with different definitions of the connection probability between vertices \eqn{i} and \eqn{j}. +#' Given \eqn{q_{ij} = \frac{w_i w_j}{S}}{q_ij = w_i w_j / S}, the following formulations are available: #' \describe{ #' \item{\dQuote{original}}{ #' the original Chung-Lu model, \eqn{p_{ij} = \min(q_{ij}, 1)}{p_ij = min(q_ij, 1)}. @@ -4633,10 +4479,9 @@ sample_k_regular <- function( #' } #' } #' @return An igraph graph. -#' @seealso [sample_fitness()] implements a similar model with a sharp -#' constraint on the number of edges. [sample_degseq()] samples random graphs -#' with sharply specified degrees. [sample_gnp()] creates random graphs with a -#' fixed connection probability \eqn{p} between all vertex pairs. +#' @seealso [sample_fitness()] implements a similar model with a sharp constraint on the number of edges. +#' [sample_degseq()] samples random graphs with sharply specified degrees. +#' [sample_gnp()] creates random graphs with a fixed connection probability \eqn{p} between all vertex pairs. #' #' @family games #' @examples @@ -4691,35 +4536,28 @@ chung_lu <- function( #' Random graphs from vertex fitness scores #' -#' This function generates a non-growing random graph with edge probabilities -#' proportional to node fitness scores. -#' -#' This game generates a directed or undirected random graph where the -#' probability of an edge between vertices \eqn{i} and \eqn{j} depends on the -#' fitness scores of the two vertices involved. For undirected graphs, each -#' vertex has a single fitness score. For directed graphs, each vertex has an -#' out- and an in-fitness, and the probability of an edge from \eqn{i} to -#' \eqn{j} depends on the out-fitness of vertex \eqn{i} and the in-fitness of -#' vertex \eqn{j}. -#' -#' The generation process goes as follows. We start from \eqn{N} disconnected -#' nodes (where \eqn{N} is given by the length of the fitness vector). Then we -#' randomly select two vertices \eqn{i} and \eqn{j}, with probabilities -#' proportional to their fitnesses. (When the generated graph is directed, -#' \eqn{i} is selected according to the out-fitnesses and \eqn{j} is selected -#' according to the in-fitnesses). If the vertices are not connected yet (or if -#' multiple edges are allowed), we connect them; otherwise we select a new -#' pair. This is repeated until the desired number of links are created. -#' -#' It can be shown that the *expected* degree of each vertex will be -#' proportional to its fitness, although the actual, observed degree will not -#' be. If you need to generate a graph with an exact degree sequence, consider -#' [sample_degseq()] instead. -#' -#' This model is commonly used to generate static scale-free networks. To -#' achieve this, you have to draw the fitness scores from the desired power-law -#' distribution. Alternatively, you may use [sample_fitness_pl()] -#' which generates the fitnesses for you with a given exponent. +#' This function generates a non-growing random graph with edge probabilities proportional to node fitness scores. +#' +#' This game generates a directed or undirected random graph +#' where the probability of an edge between vertices \eqn{i} and \eqn{j} depends on the fitness scores of the two vertices involved. +#' For undirected graphs, each vertex has a single fitness score. +#' For directed graphs, each vertex has an out- and an in-fitness, +#' and the probability of an edge from \eqn{i} to \eqn{j} depends on the out-fitness of vertex \eqn{i} and the in-fitness of vertex \eqn{j}. +#' +#' The generation process goes as follows. +#' We start from \eqn{N} disconnected nodes (where \eqn{N} is given by the length of the fitness vector). +#' Then we randomly select two vertices \eqn{i} and \eqn{j}, with probabilities proportional to their fitnesses. +#' (When the generated graph is directed, \eqn{i} is selected according to the out-fitnesses and \eqn{j} is selected according to the in-fitnesses). +#' If the vertices are not connected yet (or if multiple edges are allowed), we connect them; otherwise we select a new pair. +#' This is repeated until the desired number of links are created. +#' +#' It can be shown that the *expected* degree of each vertex will be proportional to its fitness, although the actual, +#' observed degree will not be. +#' If you need to generate a graph with an exact degree sequence, consider [sample_degseq()] instead. +#' +#' This model is commonly used to generate static scale-free networks. +#' To achieve this, you have to draw the fitness scores from the desired power-law distribution. +#' Alternatively, you may use [sample_fitness_pl()] which generates the fitnesses for you with a given exponent. #' #' @param no.of.edges The number of edges in the generated graph. #' @param fitness.out A numeric vector containing the fitness of each vertex. @@ -4729,8 +4567,7 @@ chung_lu <- function( #' Default: `NULL`, the generated graph will be undirected. #' @inheritParams rlang::args_dots_empty #' @param loops Logical, whether to allow loop edges in the graph. -#' @param multiple Logical, whether to allow multiple edges in the -#' graph. +#' @param multiple Logical, whether to allow multiple edges in the graph. #' @return An igraph graph, directed or undirected. #' @author Tamas Nepusz \email{ntamas@@gmail.com} #' @references Goh K-I, Kahng B, Kim D: Universal behaviour of load @@ -4802,45 +4639,34 @@ sample_fitness <- function( #' Scale-free random graphs, from vertex fitness scores #' -#' This function generates a non-growing random graph with expected power-law -#' degree distributions. +#' This function generates a non-growing random graph with expected power-law degree distributions. #' -#' This game generates a directed or undirected random graph where the degrees -#' of vertices follow power-law distributions with prescribed exponents. For -#' directed graphs, the exponents of the in- and out-degree distributions may -#' be specified separately. +#' This game generates a directed or undirected random graph +#' where the degrees of vertices follow power-law distributions with prescribed exponents. +#' For directed graphs, the exponents of the in- and out-degree distributions may be specified separately. #' -#' The game simply uses [sample_fitness()] with appropriately -#' constructed fitness vectors. In particular, the fitness of vertex \eqn{i} is -#' \eqn{i^{-\alpha}}{i^(-alpha)}, where \eqn{\alpha = 1/(\gamma-1)}{alpha = 1/(gamma - 1)} -#' and \eqn{\gamma}{gamma} is the exponent given in the arguments. +#' The game simply uses [sample_fitness()] with appropriately constructed fitness vectors. +#' In particular, the fitness of vertex \eqn{i} is \eqn{i^{-\alpha}}{i^(-alpha)}, +#' where \eqn{\alpha = 1/(\gamma-1)}{alpha = 1/(gamma - 1)} and \eqn{\gamma}{gamma} is the exponent given in the arguments. #' -#' To remove correlations between in- and out-degrees in case of directed -#' graphs, the in-fitness vector will be shuffled after it has been set up and -#' before [sample_fitness()] is called. +#' To remove correlations between in- and out-degrees in case of directed graphs, +#' the in-fitness vector will be shuffled after it has been set up and before [sample_fitness()] is called. #' -#' Note that significant finite size effects may be observed for exponents -#' smaller than 3 in the original formulation of the game. This function -#' provides an argument that lets you remove the finite size effects by -#' assuming that the fitness of vertex \eqn{i} is -#' \eqn{(i+i_0-1)^{-\alpha}}{(i+i0-1)^(-alpha)} where \eqn{i_0}{i0} is a -#' constant chosen appropriately to ensure that the maximum degree is less than -#' the square root of the number of edges times the average degree; see the -#' paper of Chung and Lu, and Cho et al for more details. +#' Note that significant finite size effects may be observed for exponents smaller than 3 in the original formulation of the game. +#' This function provides an argument that lets you remove the finite size effects by assuming that the fitness of vertex \eqn{i} is \eqn{(i+i_0-1)^{-\alpha}}{(i+i0-1)^(-alpha)} where \eqn{i_0}{i0} is a constant chosen appropriately to ensure that the maximum degree is less than the square root of the number of edges times the average degree; +#' see the paper of Chung and Lu, and Cho et al for more details. #' #' @param no.of.nodes The number of vertices in the generated graph. #' @param no.of.edges The number of edges in the generated graph. -#' @param exponent.out Numeric scalar, the power law exponent of the degree -#' distribution. For directed graphs, this specifies the exponent of the -#' out-degree distribution. It must be greater than or equal to 2. If you pass -#' `Inf` here, you will get back an Erdős-Rényi random network. -#' @param exponent.in Numeric scalar. If negative, the generated graph will be -#' undirected. If greater than or equal to 2, this argument specifies the -#' exponent of the in-degree distribution. If non-negative but less than 2, an -#' error will be generated. +#' @param exponent.out Numeric scalar, the power law exponent of the degree distribution. +#' For directed graphs, this specifies the exponent of the out-degree distribution. +#' It must be greater than or equal to 2. If you pass `Inf` here, you will get back an Erdős-Rényi random network. +#' @param exponent.in Numeric scalar. +#' If negative, the generated graph will be undirected. +#' If greater than or equal to 2, this argument specifies the exponent of the in-degree distribution. +#' If non-negative but less than 2, an error will be generated. #' @inheritParams sample_fitness -#' @param finite.size.correction Logical, whether to use the proposed -#' finite size correction of Cho et al., see references below. +#' @param finite.size.correction Logical, whether to use the proposed finite size correction of Cho et al., see references below. #' @inheritParams rlang::args_dots_empty #' @return An igraph graph, directed or undirected. #' @author Tamas Nepusz \email{ntamas@@gmail.com} @@ -4933,8 +4759,7 @@ sample_fitness_pl <- function( #' Forest Fire Network Model #' -#' This is a growing network model, which resembles of how the forest fire -#' spreads by igniting trees close by. +#' This is a growing network model, which resembles of how the forest fire spreads by igniting trees close by. #' #' The forest fire model intends to reproduce the following network #' characteristics, observed in real networks: \itemize{ \item Heavy-tailed @@ -4943,9 +4768,10 @@ sample_fitness_pl <- function( #' time, according to a power-law rule. \item Shrinking diameter. The diameter #' of the network decreases in time. } #' -#' The network is generated in the following way. One vertex is added at a -#' time. This vertex connects to (cites) `ambs` vertices already present -#' in the network, chosen uniformly random. Now, for each cited vertex \eqn{v} +#' The network is generated in the following way. +#' One vertex is added at a time. +#' This vertex connects to (cites) `ambs` vertices already present in the network, chosen uniformly random. +#' Now, for each cited vertex \eqn{v} #' we do the following procedure: \enumerate{ \item We generate two random #' number, \eqn{x} and \eqn{y}, that are geometrically distributed with means #' \eqn{p/(1-p)} and \eqn{rp(1-rp)}. (\eqn{p} is `fw.prob`, \eqn{r} is @@ -4958,20 +4784,15 @@ sample_fitness_pl <- function( #' @param nodes The number of vertices in the graph. #' @param fw.prob The forward burning probability, see details below. #' @inheritParams rlang::args_dots_empty -#' @param bw.factor The backward burning ratio. The backward burning -#' probability is calculated as `bw.factor*fw.prob`. +#' @param bw.factor The backward burning ratio. +#' The backward burning probability is calculated as `bw.factor*fw.prob`. #' @param ambs The number of ambassador vertices. #' @inheritParams sample_k_regular -#' @return A simple graph, possibly directed if the `directed` argument is -#' `TRUE`. -#' @note The version of the model in the published paper is incorrect in the -#' sense that it cannot generate the kind of graphs the authors claim. A -#' corrected version is available from -#' , our -#' implementation is based on this. +#' @return A simple graph, possibly directed if the `directed` argument is `TRUE`. +#' @note The version of the model in the published paper is incorrect in the sense that it cannot generate the kind of graphs the authors claim. +#' A corrected version is available from , our implementation is based on this. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso [sample_pa()] for the basic preferential attachment -#' model. +#' @seealso [sample_pa()] for the basic preferential attachment model. #' @references Jure Leskovec, Jon Kleinberg and Christos Faloutsos. Graphs over #' time: densification laws, shrinking diameters and possible explanations. #' *KDD '05: Proceeding of the eleventh ACM SIGKDD international @@ -5056,31 +4877,26 @@ sample_forestfire <- function( } -#' Generate a new random graph from a given graph by randomly -#' adding/removing edges +#' Generate a new random graph from a given graph by randomly adding/removing edges #' -#' Sample a new graph by perturbing the adjacency matrix of a given graph -#' and shuffling its vertices. +#' Sample a new graph by perturbing the adjacency matrix of a given graph and shuffling its vertices. #' #' Please see the reference given below. #' #' @param old.graph The original graph. -#' @param corr A scalar in the unit interval, the target Pearson -#' correlation between the adjacency matrices of the original and the generated -#' graph (the adjacency matrix being used as a vector). +#' @param corr A scalar in the unit interval, +#' the target Pearson correlation between the adjacency matrices of the original and the generated graph (the adjacency matrix being used as a vector). #' @inheritParams rlang::args_dots_empty -#' @param p A numeric scalar, the probability of an edge between two -#' vertices, it must in the open (0,1) interval. The default `NULL` uses the -#' empirical edge density of the graph. If you are resampling an Erdős-Rényi graph and -#' you know the original edge probability of the Erdős-Rényi model, you should -#' supply that explicitly. -#' @param permutation A numeric vector, a permutation vector that is -#' applied on the vertices of the first graph, to get the second graph. If -#' `NULL`, the vertices are not permuted. -#' @return An unweighted graph of the same size as `old.graph` such -#' that the correlation coefficient between the entries of the two -#' adjacency matrices is `corr`. Note each pair of corresponding -#' matrix entries is a pair of correlated Bernoulli random variables. +#' @param p A numeric scalar, the probability of an edge between two vertices, it must in the open (0,1) interval. +#' The default `NULL` uses the empirical edge density of the graph. +#' If you are resampling an Erdős-Rényi graph and you know the original edge probability of the Erdős-Rényi model, +#' you should supply that explicitly. +#' @param permutation A numeric vector, a permutation vector that is applied on the vertices of the first graph, +#' to get the second graph. +#' If `NULL`, the vertices are not permuted. +#' @return An unweighted graph of the same size as `old.graph` +#' such that the correlation coefficient between the entries of the two adjacency matrices is `corr`. +#' Note each pair of corresponding matrix entries is a pair of correlated Bernoulli random variables. #' #' @references Lyzinski, V., Fishkind, D. E., Priebe, C. E. (2013). Seeded #' graph matching for correlated Erdős-Rényi graphs. @@ -5152,24 +4968,21 @@ sample_correlated_gnp <- function( #' Sample a pair of correlated \eqn{G(n,p)} random graphs #' -#' Sample a new graph by perturbing the adjacency matrix of a given graph and -#' shuffling its vertices. +#' Sample a new graph by perturbing the adjacency matrix of a given graph and shuffling its vertices. #' #' Please see the reference given below. #' #' @param n Numeric scalar, the number of vertices for the sampled graphs. -#' @param corr A scalar in the unit interval, the target Pearson correlation -#' between the adjacency matrices of the original the generated graph (the -#' adjacency matrix being used as a vector). +#' @param corr A scalar in the unit interval, +#' the target Pearson correlation between the adjacency matrices of the original the generated graph (the adjacency matrix being used as a vector). #' @param p A numeric scalar, the probability of an edge between two vertices, #' it must in the open (0,1) interval. #' @param directed Logical, whether to generate directed graphs. -#' @param permutation A numeric vector, a permutation vector that is applied on -#' the vertices of the first graph, to get the second graph. If `NULL`, -#' the vertices are not permuted. -#' @return A list of two igraph objects, named `graph1` and -#' `graph2`, which are two graphs whose adjacency matrix entries are -#' correlated with `corr`. +#' @param permutation A numeric vector, a permutation vector that is applied on the vertices of the first graph, +#' to get the second graph. +#' If `NULL`, the vertices are not permuted. +#' @return A list of two igraph objects, named `graph1` and `graph2`, +#' which are two graphs whose adjacency matrix entries are correlated with `corr`. #' #' @references Lyzinski, V., Fishkind, D. E., Priebe, C. E. (2013). Seeded #' graph matching for correlated Erdős-Rényi graphs. diff --git a/R/glet.R b/R/glet.R index 28917e03e63..bbcbd433ac6 100644 --- a/R/glet.R +++ b/R/glet.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graphlets.project()` was renamed to [graphlet_proj()] to create a more -#' consistent API. +#' `graphlets.project()` was renamed to [graphlet_proj()] to create a more consistent API. #' @inheritParams graphlet_proj #' @keywords internal #' @export @@ -31,8 +30,7 @@ graphlets.project <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graphlets.candidate.basis()` was renamed to [graphlet_basis()] to create a more -#' consistent API. +#' `graphlets.candidate.basis()` was renamed to [graphlet_basis()] to create a more consistent API. #' @inheritParams graphlet_basis #' @keywords internal #' @export @@ -48,31 +46,26 @@ graphlets.candidate.basis <- function(graph, weights = NULL) { #' Graphlet decomposition of a graph #' -#' Graphlet decomposition models a weighted undirected graph via the union of -#' potentially overlapping dense social groups. This is done by a two-step -#' algorithm. In the first step a candidate set of groups (a candidate basis) -#' is created by finding cliques if the thresholded input graph. In the second -#' step these the graph is projected on the candidate basis, resulting a weight -#' coefficient for each clique in the candidate basis. +#' Graphlet decomposition models a weighted undirected graph via the union of potentially overlapping dense social groups. +#' This is done by a two-step algorithm. +#' In the first step a candidate set of groups (a candidate basis) is created by finding cliques if the thresholded input graph. +#' In the second step these the graph is projected on the candidate basis, +#' resulting a weight coefficient for each clique in the candidate basis. #' -#' igraph contains three functions for performing the graph decomponsition of a -#' graph. The first is `graphlets()`, which performed both steps on the -#' method and returns a list of subgraphs, with their corresponding weights. -#' The second and third functions correspond to the first and second steps of -#' the algorithm, and they are useful if the user wishes to perform them -#' individually: `graphlet_basis()` and `graphlet_proj()`. +#' igraph contains three functions for performing the graph decomponsition of a graph. +#' The first is `graphlets()`, which performed both steps on the method and returns a list of subgraphs, with their corresponding weights. +#' The second and third functions correspond to the first and second steps of the algorithm, +#' and they are useful if the user wishes to perform them individually: `graphlet_basis()` and `graphlet_proj()`. #' -#' @param graph The input graph, edge directions are ignored. Only simple graph -#' (i.e. graphs without self-loops and multiple edges) are supported. +#' @param graph The input graph, edge directions are ignored. +#' Only simple graph (i.e. graphs without self-loops and multiple edges) are supported. #' @inheritParams rlang::args_dots_empty -#' @param weights Edge weights. If the graph has a `weight` edge attribute -#' and this argument is `NULL` (the default), then the `weight` edge -#' attribute is used. +#' @param weights Edge weights. +#' If the graph has a `weight` edge attribute and this argument is `NULL` (the default), then the `weight` edge attribute is used. #' @param niter Integer scalar, the number of iterations to perform. -#' @param cliques A list of vertex IDs, the graphlet basis to use for the -#' projection. -#' @param Mu Starting weights for the projection. The default `NULL` uses a -#' weight of one for each clique. +#' @param cliques A list of vertex IDs, the graphlet basis to use for the projection. +#' @param Mu Starting weights for the projection. +#' The default `NULL` uses a weight of one for each clique. #' @return `graphlets()` returns a list with two members: #' \describe{ #' \item{cliques}{ @@ -95,8 +88,7 @@ graphlets.candidate.basis <- function(graph, weights = NULL) { #' } #' } #' -#' `graphlet_proj()` return a numeric vector, the weights of the graphlet -#' basis subgraphs. +#' `graphlet_proj()` return a numeric vector, the weights of the graphlet basis subgraphs. #' @examples #' #' ## Create an example graph first diff --git a/R/hrg.R b/R/hrg.R index 5d9b5ae0eaa..77223840ce7 100644 --- a/R/hrg.R +++ b/R/hrg.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `hrg.predict()` was renamed to [predict_edges()] to create a more -#' consistent API. +#' `hrg.predict()` was renamed to [predict_edges()] to create a more consistent API. #' @inheritParams predict_edges #' @keywords internal #' @export @@ -31,8 +30,7 @@ hrg.predict <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `hrg.fit()` was renamed to [fit_hrg()] to create a more -#' consistent API. +#' `hrg.fit()` was renamed to [fit_hrg()] to create a more consistent API. #' @inheritParams fit_hrg #' @keywords internal #' @export @@ -47,8 +45,7 @@ hrg.fit <- function(graph, hrg = NULL, start = FALSE, steps = 0) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `hrg.game()` was renamed to [sample_hrg()] to create a more -#' consistent API. +#' `hrg.game()` was renamed to [sample_hrg()] to create a more consistent API. #' @inheritParams sample_hrg #' @keywords internal #' @export @@ -63,8 +60,7 @@ hrg.game <- function(hrg) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `hrg.dendrogram()` was renamed to [hrg_tree()] to create a more -#' consistent API. +#' `hrg.dendrogram()` was renamed to [hrg_tree()] to create a more consistent API. #' @inheritParams hrg_tree #' @keywords internal #' @export @@ -79,8 +75,7 @@ hrg.dendrogram <- function(hrg) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `hrg.create()` was renamed to [hrg()] to create a more -#' consistent API. +#' `hrg.create()` was renamed to [hrg()] to create a more consistent API. #' @inheritParams hrg #' @keywords internal #' @export @@ -95,8 +90,7 @@ hrg.create <- function(graph, prob) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `hrg.consensus()` was renamed to [consensus_tree()] to create a more -#' consistent API. +#' `hrg.consensus()` was renamed to [consensus_tree()] to create a more consistent API. #' @inheritParams consensus_tree #' @keywords internal #' @export @@ -140,24 +134,18 @@ hrg.consensus <- function( #' #' Fitting and sampling hierarchical random graph models. #' -#' A hierarchical random graph is an ensemble of undirected graphs with \eqn{n} -#' vertices. It is defined via a binary tree with \eqn{n} leaf and \eqn{n-1} -#' internal vertices, where the internal vertices are labeled with -#' probabilities. The probability that two vertices are connected in the -#' random graph is given by the probability label at their closest common -#' ancestor. +#' A hierarchical random graph is an ensemble of undirected graphs with \eqn{n} vertices. +#' It is defined via a binary tree with \eqn{n} leaf and \eqn{n-1} internal vertices, +#' where the internal vertices are labeled with probabilities. +#' The probability that two vertices are connected in the random graph is given by the probability label at their closest common ancestor. #' #' Please see references below for more about hierarchical random graphs. #' -#' igraph contains functions for fitting HRG models to a given network -#' (`fit_hrg()`, for generating networks from a given HRG ensemble -#' (`sample_hrg()`), converting an igraph graph to a HRG and back -#' (`hrg()`, `hrg_tree()`), for calculating a consensus tree from a set -#' of sampled HRGs (`consensus_tree()`) and for predicting missing edges in -#' a network based on its HRG models (`predict_edges()`). +#' igraph contains functions for fitting HRG models to a given network (`fit_hrg()`, +#' for generating networks from a given HRG ensemble (`sample_hrg()`), converting an igraph graph to a HRG and back (`hrg()`, `hrg_tree()`), +#' for calculating a consensus tree from a set of sampled HRGs (`consensus_tree()`) and for predicting missing edges in a network based on its HRG models (`predict_edges()`). #' -#' The igraph HRG implementation is heavily based on the code published by -#' Aaron Clauset, at his website (not functional any more). +#' The igraph HRG implementation is heavily based on the code published by Aaron Clauset, at his website (not functional any more). #' #' @name hrg-methods #' @family hierarchical random graph functions @@ -165,25 +153,22 @@ NULL #' Fit a hierarchical random graph model #' -#' `fit_hrg()` fits a HRG to a given graph. It takes the specified -#' `steps` number of MCMC steps to perform the fitting, or a convergence -#' criteria if the specified number of steps is zero. `fit_hrg()` can start -#' from a given HRG, if this is given in the `hrg()` argument and the -#' `start` argument is `TRUE`. It can be converted to the `hclust` class using -#' `as.hclust()` provided in this package. +#' `fit_hrg()` fits a HRG to a given graph. +#' It takes the specified `steps` number of MCMC steps to perform the fitting, +#' or a convergence criteria if the specified number of steps is zero. +#' `fit_hrg()` can start from a given HRG, if this is given in the `hrg()` argument and the `start` argument is `TRUE`. +#' It can be converted to the `hclust` class using `as.hclust()` provided in this package. #' -#' @param graph The graph to fit the model to. Edge directions are ignored in -#' directed graphs. -#' @param hrg A hierarchical random graph model, in the form of an -#' `igraphHRG` object. `fit_hrg()` allows this to be `NULL`, in -#' which case a random starting point is used for the fitting. +#' @param graph The graph to fit the model to. +#' Edge directions are ignored in directed graphs. +#' @param hrg A hierarchical random graph model, in the form of an `igraphHRG` object. +#' `fit_hrg()` allows this to be `NULL`, in which case a random starting point is used for the fitting. #' @inheritParams rlang::args_dots_empty -#' @param start Logical, whether to start the fitting/sampling from the -#' supplied `igraphHRG` object, or from a random starting point. -#' @param steps The number of MCMC steps to make. If this is zero, then the -#' MCMC procedure is performed until convergence. -#' @return `fit_hrg()` returns an `igraphHRG` object. This is a list -#' with the following members: +#' @param start Logical, whether to start the fitting/sampling from the supplied `igraphHRG` object, or from a random starting point. +#' @param steps The number of MCMC steps to make. +#' If this is zero, then the MCMC procedure is performed until convergence. +#' @return `fit_hrg()` returns an `igraphHRG` object. +#' This is a list with the following members: #' \describe{ #' \item{left}{ #' Vector that contains the left children of the internal tree vertices. @@ -316,26 +301,19 @@ fit_hrg <- function( #' Create a consensus tree from several hierarchical random graph models #' -#' `consensus_tree()` creates a consensus tree from several fitted -#' hierarchical random graph models, using phylogeny methods. If the `hrg()` -#' argument is given and `start` is set to `TRUE`, then it starts -#' sampling from the given HRG. Otherwise it optimizes the HRG log-likelihood -#' first, and then samples starting from the optimum. +#' `consensus_tree()` creates a consensus tree from several fitted hierarchical random graph models, using phylogeny methods. +#' If the `hrg()` argument is given and `start` is set to `TRUE`, then it starts sampling from the given HRG. +#' Otherwise it optimizes the HRG log-likelihood first, and then samples starting from the optimum. #' #' @param graph The graph the models were fitted to. -#' @param hrg A hierarchical random graph model, in the form of an -#' `igraphHRG` object. `consensus_tree()` allows this to be -#' `NULL` as well, then a HRG is fitted to the graph first, from a -#' random starting point. +#' @param hrg A hierarchical random graph model, in the form of an `igraphHRG` object. +#' `consensus_tree()` allows this to be `NULL` as well, then a HRG is fitted to the graph first, from a random starting point. #' @inheritParams rlang::args_dots_empty -#' @param start Logical, whether to start the fitting/sampling from the -#' supplied `igraphHRG` object, or from a random starting point. -#' @param num.samples Number of samples to use for consensus generation or -#' missing edge prediction. -#' @return `consensus_tree()` returns a list of two objects. The first -#' is an `igraphHRGConsensus` object, the second is an -#' `igraphHRG` object. The `igraphHRGConsensus` object has the -#' following members: +#' @param start Logical, whether to start the fitting/sampling from the supplied `igraphHRG` object, or from a random starting point. +#' @param num.samples Number of samples to use for consensus generation or missing edge prediction. +#' @return `consensus_tree()` returns a list of two objects. +#' The first is an `igraphHRGConsensus` object, the second is an `igraphHRG` object. +#' The `igraphHRGConsensus` object has the following members: #' \describe{ #' \item{parents}{ #' For each vertex, the ID of its parent vertex is stored, @@ -406,14 +384,12 @@ consensus_tree <- function( #' Create a hierarchical random graph from an igraph graph #' -#' `hrg()` creates a HRG from an igraph graph. The igraph graph must be -#' a directed binary tree, with \eqn{n-1} internal and \eqn{n} leaf -#' vertices. The `prob` argument contains the HRG probability labels -#' for each vertex; these are ignored for leaf vertices. +#' `hrg()` creates a HRG from an igraph graph. +#' The igraph graph must be a directed binary tree, with \eqn{n-1} internal and \eqn{n} leaf vertices. +#' The `prob` argument contains the HRG probability labels for each vertex; these are ignored for leaf vertices. #' #' @param graph The igraph graph to create the HRG from. -#' @param prob A vector of probabilities, one for each vertex, in the order of -#' vertex IDs. +#' @param prob A vector of probabilities, one for each vertex, in the order of vertex IDs. #' @return `hrg()` returns an `igraphHRG` object. #' #' @family hierarchical random graph functions @@ -428,8 +404,7 @@ hrg <- function(graph, prob) { #' Create an igraph graph from a hierarchical random graph model #' -#' `hrg_tree()` creates the corresponsing igraph tree of a hierarchical -#' random graph model. +#' `hrg_tree()` creates the corresponsing igraph tree of a hierarchical random graph model. #' #' @param hrg A hierarchical random graph model. #' @return An igraph graph with a vertex attribute called `"probability"`. @@ -454,8 +429,7 @@ hrg_tree <- function(hrg) { #' Sample from a hierarchical random graph model #' -#' `sample_hrg()` samples a graph from a given hierarchical random graph -#' model. +#' `sample_hrg()` samples a graph from a given hierarchical random graph model. #' #' @param hrg A hierarchical random graph model. #' @return An igraph graph. @@ -475,26 +449,20 @@ sample_hrg <- function(hrg) { } #' Predict edges based on a hierarchical random graph model #' -#' `predict_edges()` uses a hierarchical random graph model to predict -#' missing edges from a network. This is done by sampling hierarchical models -#' around the optimum model, proportionally to their likelihood. The MCMC -#' sampling is stated from `hrg()`, if it is given and the `start` -#' argument is set to `TRUE`. Otherwise a HRG is fitted to the graph -#' first. +#' `predict_edges()` uses a hierarchical random graph model to predict missing edges from a network. +#' This is done by sampling hierarchical models around the optimum model, proportionally to their likelihood. +#' The MCMC sampling is stated from `hrg()`, if it is given and the `start` argument is set to `TRUE`. +#' Otherwise a HRG is fitted to the graph first. #' -#' @param graph The graph to fit the model to. Edge directions are ignored in -#' directed graphs. -#' @param hrg A hierarchical random graph model, in the form of an -#' `igraphHRG` object. `predict_edges()` allow this to be -#' `NULL` as well, then a HRG is fitted to the graph first, from a -#' random starting point. +#' @param graph The graph to fit the model to. +#' Edge directions are ignored in directed graphs. +#' @param hrg A hierarchical random graph model, in the form of an `igraphHRG` object. +#' `predict_edges()` allow this to be `NULL` as well, then a HRG is fitted to the graph first, from a random starting point. #' @inheritParams rlang::args_dots_empty -#' @param start Logical, whether to start the fitting/sampling from the -#' supplied `igraphHRG` object, or from a random starting point. -#' @param num.samples Number of samples to use for consensus generation or -#' missing edge prediction. -#' @param num.bins Number of bins for the edge probabilities. Give a higher -#' number for a more accurate prediction. +#' @param start Logical, whether to start the fitting/sampling from the supplied `igraphHRG` object, or from a random starting point. +#' @param num.samples Number of samples to use for consensus generation or missing edge prediction. +#' @param num.bins Number of bins for the edge probabilities. +#' Give a higher number for a more accurate prediction. #' @return A list with entries: #' \describe{ #' \item{edges}{ @@ -604,7 +572,8 @@ predict_edges <- function( #' #' @aliases as.igraph as.igraph.igraphHRG #' @param x The object to convert. -#' @param \dots Additional arguments. None currently. +#' @param \dots Additional arguments. +#' None currently. #' @return All these functions return an igraph graph. #' @export #' @author Gabor Csardi \email{csardi.gabor@@gmail.com}. @@ -639,8 +608,8 @@ as.igraph.igraphHRG <- function(x, ...) { } buildMerges <- function(object) { - ## Build a merge matrix. This is done by a post-order - ## traversal of the tree. + ## Build a merge matrix. + ## This is done by a post-order traversal of the tree. S <- numeric() vcount <- length(object$left) + 1 @@ -761,9 +730,8 @@ as.hclust.igraphHRG <- function(x, ...) { merge[gs] <- map[-merge[gs]] merge[-gs] <- -merge[-gs] - 1 - ## To get the ordering, we need to recode the merge matrix again, - ## without using group ids. Here the right node is merged _into_ - ## the left node. + ## To get the ordering, we need to recode the merge matrix again, without using group ids. + ## Here the right node is merged _into_ the left node. map2 <- numeric(nrow(merge)) mergeInto <- merge for (i in seq_len(nrow(merge))) { @@ -819,19 +787,18 @@ rlang::on_load(s3_register("ape::as.phylo", "igraphHRG")) #' #' Plot a hierarchical random graph as a dendrogram. #' -#' `plot_dendrogram()` supports three different plotting functions, selected via -#' the `mode` argument. By default the plotting function is taken from the -#' `dend.plot.type` igraph option, and it has for possible values: +#' `plot_dendrogram()` supports three different plotting functions, selected via the `mode` argument. +#' By default the plotting function is taken from the `dend.plot.type` igraph option, and it has for possible values: #' \itemize{ \item `auto` Choose automatically between the plotting -#' functions. As `plot.phylo` is the most sophisticated, that is choosen, -#' whenever the `ape` package is available. Otherwise `plot.hclust` -#' is used. \item `phylo` Use `plot.phylo` from the `ape` -#' package. \item `hclust` Use `plot.hclust` from the `stats` -#' package. \item `dendrogram` Use `plot.dendrogram` from the -#' `stats` package. } +#' functions. +#' As `plot.phylo` is the most sophisticated, that is choosen, whenever the `ape` package is available. +#' Otherwise `plot.hclust` is used. +#' \item `phylo` Use `plot.phylo` from the `ape` package. +#' \item `hclust` Use `plot.hclust` from the `stats` package. +#' \item `dendrogram` Use `plot.dendrogram` from the `stats` package. } #' -#' The different plotting functions take different sets of arguments. When -#' using `plot.phylo` (`mode="phylo"`), we have the following syntax: +#' The different plotting functions take different sets of arguments. +#' When using `plot.phylo` (`mode="phylo"`), we have the following syntax: #' \preformatted{ #' plot_dendrogram(x, mode="phylo", colbar = rainbow(11, start=0.7, #' end=0.1), edge.color = NULL, use.edge.length = FALSE, \dots) @@ -848,24 +815,16 @@ rlang::on_load(s3_register("ape::as.phylo", "igraphHRG")) #' hang = 0.01, ann = FALSE, main = "", sub = "", xlab = "", #' ylab = "", \dots) #' } The extra arguments not documented above: \itemize{ -#' \item `rect` A numeric scalar, the number of groups to mark on -#' the dendrogram. The dendrogram is cut into exactly `rect` -#' groups and they are marked via the `rect.hclust` command. Set -#' this to zero if you don't want to mark any groups. -#' \item `colbar` The colors of the rectangles that mark the -#' vertex groups via the `rect` argument. -#' \item `hang` Where to put the leaf nodes, this corresponds to the -#' `hang` argument of `plot.hclust`. -#' \item `ann` Whether to annotate the plot, the `ann` argument -#' of `plot.hclust`. -#' \item `main` The main title of the plot, the `main` argument -#' of `plot.hclust`. -#' \item `sub` The sub-title of the plot, the `sub` argument of -#' `plot.hclust`. -#' \item `xlab` The label on the horizontal axis, passed to -#' `plot.hclust`. -#' \item `ylab` The label on the vertical axis, passed to -#' `plot.hclust`. +#' \item `rect` A numeric scalar, the number of groups to mark on the dendrogram. +#' The dendrogram is cut into exactly `rect` groups and they are marked via the `rect.hclust` command. +#' Set this to zero if you don't want to mark any groups. +#' \item `colbar` The colors of the rectangles that mark the vertex groups via the `rect` argument. +#' \item `hang` Where to put the leaf nodes, this corresponds to the `hang` argument of `plot.hclust`. +#' \item `ann` Whether to annotate the plot, the `ann` argument of `plot.hclust`. +#' \item `main` The main title of the plot, the `main` argument of `plot.hclust`. +#' \item `sub` The sub-title of the plot, the `sub` argument of `plot.hclust`. +#' \item `xlab` The label on the horizontal axis, passed to `plot.hclust`. +#' \item `ylab` The label on the vertical axis, passed to `plot.hclust`. #' \item `dots` Attitional arguments to pass to `plot.hclust`. #' } #' @@ -874,12 +833,11 @@ rlang::on_load(s3_register("ape::as.phylo", "igraphHRG")) #' plot_dendrogram(x, \dots) #' } The extra arguments are simply passed to [as.dendrogram()]. #' -#' @param x An `igraphHRG`, a hierarchical random graph, as returned by -#' the [fit_hrg()] function. -#' @param mode Which dendrogram plotting function to use. See details below. +#' @param x An `igraphHRG`, a hierarchical random graph, as returned by the [fit_hrg()] function. +#' @param mode Which dendrogram plotting function to use. +#' See details below. #' The default `NULL` uses the `dend.plot.type` igraph option. -#' @param \dots Additional arguments to supply to the dendrogram plotting -#' function. +#' @param \dots Additional arguments to supply to the dendrogram plotting function. #' @return Returns whatever the return value was from the plotting function, #' `plot.phylo`, `plot.dendrogram` or `plot.hclust`. #' @method plot_dendrogram igraphHRG @@ -973,11 +931,10 @@ hrgPlotPhylo <- function( #' Print a hierarchical random graph model to the screen #' -#' `igraphHRG` objects can be printed to the screen in two forms: as -#' a tree or as a list, depending on the `type` argument of the -#' print function. By default the `auto` type is used, which selects -#' `tree` for small graphs and `simple` (=list) for bigger -#' ones. The `tree` format looks like +#' `igraphHRG` objects can be printed to the screen in two forms: as a tree or as a list, +#' depending on the `type` argument of the print function. +#' By default the `auto` type is used, which selects `tree` for small graphs and `simple` (=list) for bigger ones. +#' The `tree` format looks like #' this: \preformatted{Hierarchical random graph, at level 3: #' g1 p= 0 #' '- g15 p=0.33 1 @@ -985,16 +942,12 @@ hrgPlotPhylo <- function( #' '- g8 p= 0.5 #' '- g16 p= 0.2 20 14 17 19 11 15 16 13 #' '- g5 p= 0 12 18 } -#' This is a graph with 20 vertices, and the -#' top three levels of the fitted hierarchical random graph are -#' printed. The root node of the HRG is always vertex group #1 -#' (\sQuote{`g1`} in the the printout). Vertex pairs in the left -#' subtree of `g1` connect to vertices in the right subtree with -#' probability zero, according to the fitted model. `g1` has two -#' subgroups, `g15` and `g8`. `g15` has a subgroup of a -#' single vertex (vertex 1), and another larger subgroup that contains -#' vertices 6, 3, etc. on lower levels, etc. -#' The `plain` printing is simpler and faster to produce, but less +#' This is a graph with 20 vertices, and the top three levels of the fitted hierarchical random graph are printed. +#' The root node of the HRG is always vertex group #1 (\sQuote{`g1`} in the the printout). +#' Vertex pairs in the left subtree of `g1` connect to vertices in the right subtree with probability zero, according to the fitted model. +#' `g1` has two subgroups, `g15` and `g8`. +#' `g15` has a subgroup of a single vertex (vertex 1), and another larger subgroup that contains vertices 6, 3, etc. on lower levels, +#' etc. The `plain` printing is simpler and faster to produce, but less #' visual: \preformatted{Hierarchical random graph: #' g1 p=0.0 -> g12 g10 g2 p=1.0 -> 7 10 g3 p=1.0 -> g18 14 #' g4 p=1.0 -> g17 15 g5 p=0.4 -> g15 17 g6 p=0.0 -> 1 4 @@ -1003,8 +956,7 @@ hrgPlotPhylo <- function( #' g13 p=0.0 -> g14 9 g14 p=1.0 -> 2 6 g15 p=0.2 -> g19 18 #' g16 p=1.0 -> g13 g2 g17 p=0.5 -> g7 13 g18 p=1.0 -> 12 19 #' g19 p=0.7 -> g3 20} -#' It lists the two subgroups of each internal node, in -#' as many columns as the screen width allows. +#' It lists the two subgroups of each internal node, in as many columns as the screen width allows. #' #' @param x `igraphHRG` object to print. #' @param type How to print the dendrogram, see details below. @@ -1179,14 +1131,12 @@ print2.igraphHRG <- function(x, ...) { #' Print a hierarchical random graph consensus tree to the screen #' -#' Consensus dendrograms (`igraphHRGConsensus` objects) are printed -#' simply by listing the children of each internal node of the +#' Consensus dendrograms (`igraphHRGConsensus` objects) are printed simply by listing the children of each internal node of the #' dendrogram: \preformatted{HRG consensus tree: #' g1 -> 11 12 13 14 15 16 17 18 19 20 #' g2 -> 1 2 3 4 5 6 7 8 9 10 #' g3 -> g1 g2} -#' The root of the dendrogram is `g3` (because it has no incoming -#' edges), and it has two subgroups, `g1` and `g2`. +#' The root of the dendrogram is `g3` (because it has no incoming edges), and it has two subgroups, `g1` and `g2`. #' #' @param x `igraphHRGConsensus` object to print. #' @param ... Ignored. diff --git a/R/igraph-package.R b/R/igraph-package.R index 71e6b0c0cbf..1330fc03535 100644 --- a/R/igraph-package.R +++ b/R/igraph-package.R @@ -9,14 +9,12 @@ NULL #' Magrittr's pipes #' -#' igraph re-exports the `%>%` operator of magrittr, because -#' we find it very useful. Please see the documentation in the -#' `magrittr` package. +#' igraph re-exports the `%>%` operator of magrittr, because we find it very useful. +#' Please see the documentation in the `magrittr` package. #' #' @param lhs Left hand side of the pipe. #' @param rhs Right hand side of the pipe. -#' @return Result of applying the right hand side to the -#' result of the left hand side. +#' @return Result of applying the right hand side to the result of the left hand side. #' #' @export #' @name %>% @@ -37,37 +35,28 @@ NULL #' @aliases igraph-package igraph #' #' @section Introduction: -#' The main goals of the igraph library is to provide a set of data types -#' and functions for 1) pain-free implementation of graph algorithms, 2) -#' fast handling of large graphs, with millions of vertices and edges, 3) -#' allowing rapid prototyping via high level languages like R. +#' The main goals of the igraph library is to provide a set of data types and functions for 1) pain-free implementation of graph algorithms, 2) fast handling of large graphs, +#' with millions of vertices and edges, 3) allowing rapid prototyping via high level languages like R. #' #' @section igraph graphs: -#' igraph graphs have a class \sQuote{`igraph`}. They are printed to -#' the screen in a special format, here is an example, a ring graph +#' igraph graphs have a class \sQuote{`igraph`}. +#' They are printed to the screen in a special format, here is an example, a ring graph #' created using [make_ring()]: \preformatted{ #' IGRAPH U--- 10 10 -- Ring graph #' + attr: name (g/c), mutual (g/x), circular (g/x) } -#' \sQuote{`IGRAPH`} denotes that this is an igraph graph. Then -#' come four bits that denote the kind of the graph: the first is -#' \sQuote{`U`} for undirected and \sQuote{`D`} for directed -#' graphs. The second is \sQuote{`N`} for named graph (i.e. if the -#' graph has the \sQuote{`name`} vertex attribute set). The third is -#' \sQuote{`W`} for weighted graphs (i.e. if the -#' \sQuote{`weight`} edge attribute is set). The fourth is -#' \sQuote{`B`} for bipartite graphs (i.e. if the -#' \sQuote{`type`} vertex attribute is set). -#' -#' Then come two numbers, the number of vertices and the number of edges -#' in the graph, and after a double dash, the name of the graph (the -#' \sQuote{`name`} graph attribute) is printed if present. The -#' second line is optional and it contains all the attributes of the -#' graph. This graph has a \sQuote{`name`} graph attribute, of type -#' character, and two other graph attributes called -#' \sQuote{`mutual`} and \sQuote{`circular`}, of a complex -#' type. A complex type is simply anything that is not numeric or -#' character. See the documentation of [print.igraph()] for -#' details. +#' \sQuote{`IGRAPH`} denotes that this is an igraph graph. +#' Then come four bits that denote the kind of the graph: the first is \sQuote{`U`} for undirected and \sQuote{`D`} for directed graphs. +#' The second is \sQuote{`N`} for named graph (i.e. if the graph has the \sQuote{`name`} vertex attribute set). +#' The third is \sQuote{`W`} for weighted graphs (i.e. if the \sQuote{`weight`} edge attribute is set). +#' The fourth is \sQuote{`B`} for bipartite graphs (i.e. if the \sQuote{`type`} vertex attribute is set). +#' +#' Then come two numbers, the number of vertices and the number of edges in the graph, and after a double dash, +#' the name of the graph (the \sQuote{`name`} graph attribute) is printed if present. +#' The second line is optional and it contains all the attributes of the graph. +#' This graph has a \sQuote{`name`} graph attribute, of type character, +#' and two other graph attributes called \sQuote{`mutual`} and \sQuote{`circular`}, of a complex type. +#' A complex type is simply anything that is not numeric or character. +#' See the documentation of [print.igraph()] for details. #' #' If you want to see the edges of the graph as well, then use the #' [print_all()] function: \preformatted{ > print_all(g) @@ -77,105 +66,83 @@ NULL #' [1] 1-- 2 2-- 3 3-- 4 4-- 5 5-- 6 6-- 7 7-- 8 8-- 9 9--10 1--10 } #' #' @section Creating graphs: -#' There are many functions in igraph for creating graphs, both -#' deterministic and stochastic; stochastic graph constructors are called -#' \sQuote{games}. +#' There are many functions in igraph for creating graphs, both deterministic and stochastic; +#' stochastic graph constructors are called \sQuote{games}. #' -#' To create small graphs with a given structure probably the -#' [graph_from_literal()] function is easiest. It uses R's formula -#' interface, its manual page contains many examples. Another option is -#' [make_graph()], which takes numeric vertex IDs directly. -#' [graph_from_atlas()] creates graph from the Graph Atlas, -#' [make_graph()] can create some special graphs. +#' To create small graphs with a given structure probably the [graph_from_literal()] function is easiest. +#' It uses R's formula interface, its manual page contains many examples. +#' Another option is [make_graph()], which takes numeric vertex IDs directly. +#' [graph_from_atlas()] creates graph from the Graph Atlas, [make_graph()] can create some special graphs. #' #' To create graphs from field data, [graph_from_edgelist()], -#' [graph_from_data_frame()] and [graph_from_adjacency_matrix()] are -#' probably the best choices. +#' [graph_from_data_frame()] and [graph_from_adjacency_matrix()] are probably the best choices. #' -#' The igraph package includes some classic random graphs like the -#' Erdős-Rényi GNP and GNM graphs ([sample_gnp()], [sample_gnm()]) and -#' some recent popular models, like preferential attachment -#' ([sample_pa()]) and the small-world model -#' ([sample_smallworld()]). +#' The igraph package includes some classic random graphs like the Erdős-Rényi GNP and GNM graphs ([sample_gnp()], [sample_gnm()]) and some recent popular models, +#' like preferential attachment ([sample_pa()]) and the small-world model ([sample_smallworld()]). #' #' @section Vertex and edge IDs: -#' Vertices and edges have numerical vertex IDs in igraph. Vertex IDs are -#' always consecutive and they start with one. I.e. for a graph with -#' \eqn{n} vertices the vertex IDs are between \eqn{1} and -#' \eqn{n}. If some operation changes the number of vertices in the -#' graphs, e.g. a subgraph is created via [induced_subgraph()], then -#' the vertices are renumbered to satisfy this criteria. -#' -#' The same is true for the edges as well, edge IDs are always between -#' one and \eqn{m}, the total number of edges in the graph. -#' -#' It is often desirable to follow vertices along a number of graph -#' operations, and vertex IDs don't allow this because of the -#' renumbering. The solution is to assign attributes to the -#' vertices. These are kept by all operations, if possible. See more -#' about attributes in the next section. +#' Vertices and edges have numerical vertex IDs in igraph. +#' Vertex IDs are always consecutive and they start with one. +#' I.e. for a graph with \eqn{n} vertices the vertex IDs are between \eqn{1} and \eqn{n}. +#' If some operation changes the number of vertices in the graphs, e.g. a subgraph is created via [induced_subgraph()], +#' then the vertices are renumbered to satisfy this criteria. +#' +#' The same is true for the edges as well, edge IDs are always between one and \eqn{m}, the total number of edges in the graph. +#' +#' It is often desirable to follow vertices along a number of graph operations, +#' and vertex IDs don't allow this because of the renumbering. +#' The solution is to assign attributes to the vertices. +#' These are kept by all operations, if possible. +#' See more about attributes in the next section. #' #' @section Attributes: -#' In igraph it is possible to assign attributes to the vertices or edges -#' of a graph, or to the graph itself. igraph provides flexible -#' constructs for selecting a set of vertices or edges based on their -#' attribute values, see [vertex_attr()], -#' [V()] and [E()] for details. -#' -#' Some vertex/edge/graph attributes are treated specially. One of them -#' is the \sQuote{name} attribute. This is used for printing the graph -#' instead of the numerical IDs, if it exists. Vertex names can also be -#' used to specify a vector or set of vertices, in all igraph -#' functions. E.g. [degree()] has a `v` argument -#' that gives the vertices for which the degree is calculated. This -#' argument can be given as a character vector of vertex names. -#' -#' Edges can also have a \sQuote{name} attribute, and this is treated -#' specially as well. Just like for vertices, edges can also be selected -#' based on their names, e.g. in the [delete_edges()] and -#' other functions. +#' In igraph it is possible to assign attributes to the vertices or edges of a graph, +#' or to the graph itself. igraph provides flexible constructs for selecting a set of vertices or edges based on their attribute values, +#' see [vertex_attr()], [V()] and [E()] for details. +#' +#' Some vertex/edge/graph attributes are treated specially. +#' One of them is the \sQuote{name} attribute. +#' This is used for printing the graph instead of the numerical IDs, if it exists. +#' Vertex names can also be used to specify a vector or set of vertices, in all igraph functions. +#' E.g. [degree()] has a `v` argument that gives the vertices for which the degree is calculated. +#' This argument can be given as a character vector of vertex names. +#' +#' Edges can also have a \sQuote{name} attribute, and this is treated specially as well. +#' Just like for vertices, edges can also be selected based on their names, e.g. in the [delete_edges()] and other functions. #' #' We note here, that vertex names can also be used to select edges. -#' The form \sQuote{`from|to`}, where \sQuote{`from`} and -#' \sQuote{`to`} are vertex names, select a single, possibly -#' directed, edge going from \sQuote{`from`} to -#' \sQuote{`to`}. The two forms can also be mixed in the same edge -#' selector. +#' The form \sQuote{`from|to`}, where \sQuote{`from`} and \sQuote{`to`} are vertex names, select a single, possibly directed, +#' edge going from \sQuote{`from`} to \sQuote{`to`}. +#' The two forms can also be mixed in the same edge selector. #' -#' Other attributes define visualization parameters, see -#' [igraph.plotting] for details. +#' Other attributes define visualization parameters, see [igraph.plotting] for details. #' -#' Attribute values can be set to any R object, but note that storing the -#' graph in some file formats might result the loss of complex attribute -#' values. All attribute values are preserved if you use -#' [base::save()] and [base::load()] to store/retrieve your -#' graphs. +#' Attribute values can be set to any R object, +#' but note that storing the graph in some file formats might result the loss of complex attribute values. +#' All attribute values are preserved if you use [base::save()] and [base::load()] to store/retrieve your graphs. #' #' @section Visualization: -#' igraph provides three different ways for visualization. The first is -#' the [plot.igraph()] function. (Actually you don't need to -#' write `plot.igraph()`, [plot()] is enough. This function uses -#' regular R graphics and can be used with any R device. +#' igraph provides three different ways for visualization. +#' The first is the [plot.igraph()] function. +#' (Actually you don't need to write `plot.igraph()`, [plot()] is enough. +#' This function uses regular R graphics and can be used with any R device. #' -#' The second function is [tkplot()], which uses a Tk GUI for -#' basic interactive graph manipulation. (Tk is quite resource hungry, so -#' don't try this for very large graphs.) +#' The second function is [tkplot()], which uses a Tk GUI for basic interactive graph manipulation. +#' (Tk is quite resource hungry, so don't try this for very large graphs.) #' -#' The third way requires the `rgl` package and uses OpenGL. See the -#' [rglplot()] function for the details. +#' The third way requires the `rgl` package and uses OpenGL. +#' See the [rglplot()] function for the details. #' -#' Make sure you read [igraph.plotting] before you start -#' plotting your graphs. +#' Make sure you read [igraph.plotting] before you start plotting your graphs. #' #' @section File formats: -#' igraph can handle various graph file formats, usually both for reading -#' and writing. We suggest that you use the GraphML file format for your -#' graphs, except if the graphs are too big. For big graphs a simpler -#' format is recommended. See [read_graph()] and -#' [write_graph()] for details. +#' igraph can handle various graph file formats, usually both for reading and writing. +#' We suggest that you use the GraphML file format for your graphs, except if the graphs are too big. +#' For big graphs a simpler format is recommended. +#' See [read_graph()] and [write_graph()] for details. #' #' @section Further information: #' The igraph homepage is at . -#' See especially the documentation section. Join the discussion forum at -#' if you have questions or comments. +#' See especially the documentation section. +#' Join the discussion forum at if you have questions or comments. "_PACKAGE" diff --git a/R/incidence.R b/R/incidence.R index 7dc4364063d..af35313ba7f 100644 --- a/R/incidence.R +++ b/R/incidence.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.incidence()` was renamed to [graph_from_biadjacency_matrix()] to create a more -#' consistent API. +#' `graph.incidence()` was renamed to [graph_from_biadjacency_matrix()] to create a more consistent API. #' @inheritParams graph_from_biadjacency_matrix #' @keywords internal #' @export @@ -124,53 +123,41 @@ graph_incidence_build <- function( #' Create graphs from a bipartite adjacency matrix #' -#' `graph_from_biadjacency_matrix()` creates a bipartite igraph graph from an incidence -#' matrix. +#' `graph_from_biadjacency_matrix()` creates a bipartite igraph graph from an incidence matrix. #' #' Bipartite graphs have a \sQuote{`type`} vertex attribute in igraph, -#' this is boolean and `FALSE` for the vertices of the first kind and -#' `TRUE` for vertices of the second kind. +#' this is boolean and `FALSE` for the vertices of the first kind and `TRUE` for vertices of the second kind. #' -#' `graph_from_biadjacency_matrix()` can operate in two modes, depending on the -#' `multiple` argument. If it is `FALSE` then a single edge is -#' created for every non-zero element in the bipartite adjacency matrix. If -#' `multiple` is `TRUE`, then the matrix elements are rounded up to -#' the closest non-negative integer to get the number of edges to create -#' between a pair of vertices. +#' `graph_from_biadjacency_matrix()` can operate in two modes, depending on the `multiple` argument. +#' If it is `FALSE` then a single edge is created for every non-zero element in the bipartite adjacency matrix. +#' If `multiple` is `TRUE`, +#' then the matrix elements are rounded up to the closest non-negative integer to get the number of edges to create between a pair of vertices. #' -#' @param incidence The input bipartite adjacency matrix. It can also be a sparse matrix -#' from the `Matrix` package. +#' @param incidence The input bipartite adjacency matrix. +#' It can also be a sparse matrix from the `Matrix` package. #' @inheritParams rlang::args_dots_empty #' @param directed Logical, whether to create a directed graph. -#' @param mode A character constant, defines the direction of the edges in -#' directed graphs, ignored for undirected graphs. If \sQuote{`out`}, then -#' edges go from vertices of the first kind (corresponding to rows in the -#' bipartite adjacency matrix) to vertices of the second kind (columns in the incidence -#' matrix). If \sQuote{`in`}, then the opposite direction is used. If -#' \sQuote{`all`} or \sQuote{`total`}, then mutual edges are created. -#' @param multiple Logical, specifies how to interpret the matrix -#' elements. See details below. -#' @param weighted This argument specifies whether to create a weighted graph -#' from the bipartite adjacency matrix. If it is `NULL` then an unweighted graph is -#' created and the `multiple` argument is used to determine the edges of -#' the graph. If it is a character constant then for every non-zero matrix -#' entry an edge is created and the value of the entry is added as an edge -#' attribute named by the `weighted` argument. If it is `TRUE` then a -#' weighted graph is created and the name of the edge attribute will be -#' \sQuote{`weight`}. +#' @param mode A character constant, defines the direction of the edges in directed graphs, ignored for undirected graphs. +#' If \sQuote{`out`}, +#' then edges go from vertices of the first kind (corresponding to rows in the bipartite adjacency matrix) to vertices of the second kind (columns in the incidence matrix). +#' If \sQuote{`in`}, then the opposite direction is used. +#' If \sQuote{`all`} or \sQuote{`total`}, then mutual edges are created. +#' @param multiple Logical, specifies how to interpret the matrix elements. +#' See details below. +#' @param weighted This argument specifies whether to create a weighted graph from the bipartite adjacency matrix. +#' If it is `NULL` then an unweighted graph is created and the `multiple` argument is used to determine the edges of the graph. +#' If it is a character constant then for every non-zero matrix entry an edge is created and the value of the entry is added as an edge attribute named by the `weighted` argument. +#' If it is `TRUE` then a weighted graph is created and the name of the edge attribute will be \sQuote{`weight`}. #' @param add.names A character constant, `NA` or `NULL`. -#' `graph_from_biadjacency_matrix()` can add the row and column names of the incidence -#' matrix as vertex attributes. If this argument is `NULL` (the default) -#' and the bipartite adjacency matrix has both row and column names, then these are added -#' as the \sQuote{`name`} vertex attribute. If you want a different vertex -#' attribute for this, then give the name of the attributes as a character -#' string. If this argument is `NA`, then no vertex attributes (other than -#' type) will be added. -#' @return A bipartite igraph graph. In other words, an igraph graph that has a -#' vertex attribute `type`. +#' `graph_from_biadjacency_matrix()` can add the row and column names of the incidence matrix as vertex attributes. +#' If this argument is `NULL` (the default) and the bipartite adjacency matrix has both row and column names, +#' then these are added as the \sQuote{`name`} vertex attribute. +#' If you want a different vertex attribute for this, then give the name of the attributes as a character string. +#' If this argument is `NA`, then no vertex attributes (other than type) will be added. +#' @return A bipartite igraph graph. +#' In other words, an igraph graph that has a vertex attribute `type`. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso [make_bipartite_graph()] for another way to create bipartite -#' graphs +#' @seealso [make_bipartite_graph()] for another way to create bipartite graphs #' @keywords graphs #' @examples #' @@ -180,9 +167,7 @@ graph_incidence_build <- function( #' graph_from_biadjacency_matrix(inc) #' #' @details -#' Some authors refer to the bipartite adjacency matrix as the -#' "bipartite incidence matrix". igraph 1.6.0 and later does not use -#' this naming to avoid confusion with the edge-vertex incidence matrix. +#' Some authors refer to the bipartite adjacency matrix as the "bipartite incidence matrix". igraph 1.6.0 and later does not use this naming to avoid confusion with the edge-vertex incidence matrix. #' @family biadjacency #' @export graph_from_biadjacency_matrix <- function( @@ -307,14 +292,11 @@ graph_from_biadjacency_matrix <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph_from_incidence_matrix()` was renamed to [graph_from_biadjacency_matrix()] to create a more -#' consistent API. +#' `graph_from_incidence_matrix()` was renamed to [graph_from_biadjacency_matrix()] to create a more consistent API. #' @inheritParams graph_from_biadjacency_matrix #' @keywords internal #' @details -#' Some authors refer to the bipartite adjacency matrix as the -#' "bipartite incidence matrix". igraph 1.6.0 and later does not use -#' this naming to avoid confusion with the edge-vertex incidence matrix. +#' Some authors refer to the bipartite adjacency matrix as the "bipartite incidence matrix". igraph 1.6.0 and later does not use this naming to avoid confusion with the edge-vertex incidence matrix. #' @export from_incidence_matrix <- function(...) { # nocov start @@ -330,14 +312,11 @@ from_incidence_matrix <- function(...) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph_from_incidence_matrix()` was renamed to [graph_from_biadjacency_matrix()] to create a more -#' consistent API. +#' `graph_from_incidence_matrix()` was renamed to [graph_from_biadjacency_matrix()] to create a more consistent API. #' @inheritParams graph_from_biadjacency_matrix #' @keywords internal #' @details -#' Some authors refer to the bipartite adjacency matrix as the -#' "bipartite incidence matrix". igraph 1.6.0 and later does not use -#' this naming to avoid confusion with the edge-vertex incidence matrix. +#' Some authors refer to the bipartite adjacency matrix as the "bipartite incidence matrix". igraph 1.6.0 and later does not use this naming to avoid confusion with the edge-vertex incidence matrix. #' @export graph_from_incidence_matrix <- function(...) { # nocov start diff --git a/R/indexing.R b/R/indexing.R index 1f61e246621..62f8ddd018b 100644 --- a/R/indexing.R +++ b/R/indexing.R @@ -111,8 +111,8 @@ get_adjacency_submatrix <- function(x, i, j, attr = NULL) { #' Query and manipulate a graph as it were an adjacency matrix #' #' @details -#' The single bracket indexes the (possibly weighted) adjacency matrix of -#' the graph. Here is what you can do with it: +#' The single bracket indexes the (possibly weighted) adjacency matrix of the graph. +#' Here is what you can do with it: #' #' \enumerate{ #' \item Check whether there is an edge between two vertices (\eqn{v} @@ -125,17 +125,15 @@ get_adjacency_submatrix <- function(x, i, j, attr = NULL) { #' graph[c(1,3,5),]} #' The first variants returns the full adjacency matrix, the other #' two return part of it. -#' \item The `from` and `to` arguments can be used to check -#' the existence of many edges. In this case, both `from` and -#' `to` must be present and they must have the same length. They -#' must contain vertex IDs or names. A numeric vector is returned, of -#' the same length as `from` and `to`, it contains ones -#' for existing edges edges and zeros for non-existing ones. +#' \item The `from` and `to` arguments can be used to check the existence of many edges. +#' In this case, both `from` and `to` must be present and they must have the same length. +#' They must contain vertex IDs or names. +#' A numeric vector is returned, of the same length as `from` and `to`, it contains ones for existing edges edges +#' and zeros for non-existing ones. #' Example: \preformatted{ graph[from=1:3, to=c(2,3,5)]}. -#' \item For weighted graphs, the `[` operator returns the edge -#' weights. For non-esistent edges zero weights are returned. Other -#' edge attributes can be queried as well, by giving the `attr` -#' argument. +#' \item For weighted graphs, the `[` operator returns the edge weights. +#' For non-esistent edges zero weights are returned. +#' Other edge attributes can be queried as well, by giving the `attr` argument. #' \item Querying edge IDs instead of the existance of edges or edge #' attributes. E.g. \preformatted{ graph[1, 2, edges=TRUE]} #' returns the ID of the edge between vertices 1 and 2, or zero if @@ -151,10 +149,8 @@ get_adjacency_submatrix <- function(x, i, j, attr = NULL) { #' contains the name of the edge attribute to set, so it does not #' have to be \sQuote{weight}: \preformatted{ graph[1, 2, attr="weight"]<- 5 #' graph[from=1:3, to=c(2,3,5)] <- c(1,-1,4)} -#' If an edge is already present in the network, then only its -#' weights or other attribute are updated. If the graph is already -#' weighted, then the `attr="weight"` setting is implicit, and -#' one does not need to give it explicitly. +#' If an edge is already present in the network, then only its weights or other attribute are updated. +#' If the graph is already weighted, then the `attr="weight"` setting is implicit, and one does not need to give it explicitly. #' \item Deleting edges. The replacement syntax allow the deletion of #' edges, by specifying `FALSE` or `NULL` as the #' replacement value: \preformatted{ graph[v, w] <- FALSE} @@ -173,33 +169,34 @@ get_adjacency_submatrix <- function(x, i, j, attr = NULL) { #' creates a star graph. #' #' Of course, the indexing operators support vertex names, -#' so instead of a numeric vertex ID a vertex can also be given to -#' \sQuote{`[`} and \sQuote{`[[`}. +#' so instead of a numeric vertex ID a vertex can also be given to \sQuote{`[`} and \sQuote{`[[`}. #' #' @param x The graph. -#' @param i Index. Vertex IDs or names or logical vectors. See details -#' below. -#' @param j Index. Vertex IDs or names or logical vectors. See details -#' below. +#' @param i Index. +#' Vertex IDs or names or logical vectors. +#' See details below. +#' @param j Index. +#' Vertex IDs or names or logical vectors. +#' See details below. #' @param ... Currently ignored. -#' @param from A numeric or character vector giving vertex IDs or -#' names. Together with the `to` argument, it can be used to -#' query/set a sequence of edges. See details below. This argument cannot -#' be present together with any of the `i` and `j` arguments -#' and if it is present, then the `to` argument must be present as -#' well. -#' @param to A numeric or character vector giving vertex IDs or -#' names. Together with the `from` argument, it can be used to -#' query/set a sequence of edges. See details below. This argument cannot -#' be present together with any of the `i` and `j` arguments -#' and if it is present, then the `from` argument must be present as -#' well. +#' @param from A numeric or character vector giving vertex IDs or names. +#' Together with the `to` argument, it can be used to query/set a sequence of edges. +#' See details below. +#' This argument cannot be present together with any of the `i` and `j` arguments and if it is present, +#' then the `to` argument must be present as well. +#' @param to A numeric or character vector giving vertex IDs or names. +#' Together with the `from` argument, it can be used to query/set a sequence of edges. +#' See details below. +#' This argument cannot be present together with any of the `i` and `j` arguments and if it is present, +#' then the `from` argument must be present as well. #' @param sparse Logical, whether to return sparse matrices. #' @param edges Logical, whether to return edge IDs. #' @param drop Ignored. -#' @param attr Name of an edge attribute. This attribute is queried and returned. +#' @param attr Name of an edge attribute. +#' This attribute is queried and returned. #' Default: `NULL`. -#' @return A scalar or matrix. See details below. +#' @return A scalar or matrix. +#' See details below. #' #' @family structural queries #' @@ -315,8 +312,8 @@ get_adjacency_submatrix <- function(x, i, j, attr = NULL) { #' Query and manipulate a graph as it were an adjacency list #' #' @details -#' The double bracket operator indexes the (imaginary) adjacency list -#' of the graph. This can used for the following operations: +#' The double bracket operator indexes the (imaginary) adjacency list of the graph. +#' This can used for the following operations: #' \enumerate{ #' \item Querying the adjacent vertices for one or more #' vertices: \preformatted{ graph[[1:3,]] @@ -333,35 +330,30 @@ get_adjacency_submatrix <- function(x, i, j, attr = NULL) { #' \eqn{v} to vertices \eqn{w}. #' } #' -#' The alternative argument names `from` and `to` can be used -#' instead of the usual `i` and `j`, to make the code more +#' The alternative argument names `from` and `to` can be used instead of the usual `i` and `j`, to make the code more #' readable: \preformatted{ graph[[from = 1:3]] #' graph[[from = v, to = w, edges = TRUE]]} #' -#' \sQuote{`[[`} operators allows logical indices and negative indices -#' as well, with the usual R semantics. +#' \sQuote{`[[`} operators allows logical indices and negative indices as well, with the usual R semantics. #' -#' Vertex names are also supported, so instead of a numeric vertex ID a -#' vertex can also be given to \sQuote{`[`} and \sQuote{`[[`}. +#' Vertex names are also supported, so instead of a numeric vertex ID a vertex can also be given to \sQuote{`[`} and \sQuote{`[[`}. #' #' @param x The graph. #' @param i Index, integer, character or logical, see details below. #' @param j Index, integer, character or logical, see details below. -#' @param from A numeric or character vector giving vertex IDs or -#' names. Together with the `to` argument, it can be used to -#' query/set a sequence of edges. See details below. This argument cannot -#' be present together with any of the `i` and `j` arguments -#' and if it is present, then the `to` argument must be present as -#' well. -#' @param to A numeric or character vector giving vertex IDs or -#' names. Together with the `from` argument, it can be used to -#' query/set a sequence of edges. See details below. This argument cannot -#' be present together with any of the `i` and `j` arguments -#' and if it is present, then the `from` argument must be present as -#' well. +#' @param from A numeric or character vector giving vertex IDs or names. +#' Together with the `to` argument, it can be used to query/set a sequence of edges. +#' See details below. +#' This argument cannot be present together with any of the `i` and `j` arguments and if it is present, +#' then the `to` argument must be present as well. +#' @param to A numeric or character vector giving vertex IDs or names. +#' Together with the `from` argument, it can be used to query/set a sequence of edges. +#' See details below. +#' This argument cannot be present together with any of the `i` and `j` arguments and if it is present, +#' then the `from` argument must be present as well. #' @param ... Additional arguments are not used currently. -#' @param directed Logical, whether to consider edge directions -#' in directed graphs. It is ignored for undirected graphs. +#' @param directed Logical, whether to consider edge directions in directed graphs. +#' It is ignored for undirected graphs. #' @param edges Logical, whether to return edge IDs. #' @param exact Ignored. #' diff --git a/R/interface.R b/R/interface.R index 59ce5d4178e..836cc093b7a 100644 --- a/R/interface.R +++ b/R/interface.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `is.directed()` was renamed to [is_directed()] to create a more -#' consistent API. +#' `is.directed()` was renamed to [is_directed()] to create a more consistent API. #' @inheritParams is_directed #' @keywords internal #' @export @@ -19,8 +18,7 @@ is.directed <- function(graph) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `delete.vertices()` was renamed to [delete_vertices()] to create a more -#' consistent API. +#' `delete.vertices()` was renamed to [delete_vertices()] to create a more consistent API. #' @inheritParams delete_vertices #' @keywords internal #' @export @@ -35,8 +33,7 @@ delete.vertices <- function(graph, v) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `delete.edges()` was renamed to [delete_edges()] to create a more -#' consistent API. +#' `delete.edges()` was renamed to [delete_edges()] to create a more consistent API. #' @inheritParams delete_edges #' @keywords internal #' @export @@ -51,8 +48,7 @@ delete.edges <- function(graph, edges) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `add.vertices()` was renamed to [add_vertices()] to create a more -#' consistent API. +#' `add.vertices()` was renamed to [add_vertices()] to create a more consistent API. #' @inheritParams add_vertices #' @keywords internal #' @export @@ -67,8 +63,7 @@ add.vertices <- function(graph, nv, ..., attr = list()) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `add.edges()` was renamed to [add_edges()] to create a more -#' consistent API. +#' `add.edges()` was renamed to [add_edges()] to create a more consistent API. #' @inheritParams add_edges #' @keywords internal #' @export @@ -104,23 +99,18 @@ add.edges <- function(graph, edges, ..., attr = list()) { #' Add edges to a graph #' -#' The new edges are given as a vertex sequence, e.g. internal -#' numeric vertex IDs, or vertex names. The first edge points from -#' `edges[1]` to `edges[2]`, the second from `edges[3]` -#' to `edges[4]`, etc. +#' The new edges are given as a vertex sequence, e.g. internal numeric vertex IDs, or vertex names. +#' The first edge points from `edges[1]` to `edges[2]`, the second from `edges[3]` to `edges[4]`, etc. #' #' If attributes are supplied, and they are not present in the graph, #' their values for the original edges of the graph are set to `NA`. #' #' @param graph The input graph -#' @param edges The edges to add, a vertex sequence with even number -#' of vertices. -#' @param ... Additional arguments, they must be named, -#' and they will be added as edge attributes, for the newly added -#' edges. See also details below. -#' @param attr A named list, its elements will be added -#' as edge attributes, for the newly added edges. See also details -#' below. +#' @param edges The edges to add, a vertex sequence with even number of vertices. +#' @param ... Additional arguments, they must be named, and they will be added as edge attributes, for the newly added edges. +#' See also details below. +#' @param attr A named list, its elements will be added as edge attributes, for the newly added edges. +#' See also details below. #' @return The graph, with the edges (and attributes) added. #' #' @export @@ -176,18 +166,14 @@ add_edges <- function(graph, edges, ..., attr = list()) { #' Add vertices to a graph #' -#' If attributes are supplied, and they are not present in the graph, -#' their values for the original vertices of the graph are set to -#' `NA`. +#' If attributes are supplied, and they are not present in the graph, their values for the original vertices of the graph are set to `NA`. #' #' @param graph The input graph. #' @param nv The number of vertices to add. -#' @param ... Additional arguments, they must be named, -#' and they will be added as vertex attributes, for the newly added -#' vertices. See also details below. -#' @param attr A named list, its elements will be added -#' as vertex attributes, for the newly added vertices. See also details -#' below. +#' @param ... Additional arguments, they must be named, and they will be added as vertex attributes, for the newly added vertices. +#' See also details below. +#' @param attr A named list, its elements will be added as vertex attributes, for the newly added vertices. +#' See also details below. #' @return The graph, with the vertices (and attributes) added. #' #' @family functions for manipulating graph structure @@ -242,10 +228,9 @@ add_vertices <- function(graph, nv, ..., attr = list()) { #' Delete edges from a graph #' #' @param graph The input graph. -#' @param edges The edges to remove, specified as an edge sequence. Typically -#' this is either a numeric vector containing edge IDs, or a character vector -#' containing the IDs or names of the source and target vertices, separated by -#' `|` +#' @param edges The edges to remove, specified as an edge sequence. +#' Typically this is either a numeric vector containing edge IDs, +#' or a character vector containing the IDs or names of the source and target vertices, separated by `|` #' @return The graph, with the edges removed. #' #' @family functions for manipulating graph structure @@ -330,15 +315,13 @@ ecount <- gsize #' Neighboring (adjacent) vertices in a graph #' -#' A vertex is a neighbor of another one (in other words, the two -#' vertices are adjacent), if they are incident to the same edge. +#' A vertex is a neighbor of another one (in other words, the two vertices are adjacent), if they are incident to the same edge. #' #' @param graph The input graph. #' @param v The vertex of which the adjacent vertices are queried. #' @inheritParams rlang::args_dots_empty -#' @param mode Whether to query outgoing (\sQuote{out}), incoming -#' (\sQuote{in}) edges, or both types (\sQuote{all}). This is -#' ignored for undirected graphs. +#' @param mode Whether to query outgoing (\sQuote{out}), incoming (\sQuote{in}) edges, or both types (\sQuote{all}). +#' This is ignored for undirected graphs. #' @return A vertex sequence containing the neighbors of the input vertex. #' #' @family structural queries @@ -411,8 +394,7 @@ neighbors <- function( #' @param v The vertex of which the incident edges are queried. #' @inheritParams neighbors #' @inheritParams rlang::args_dots_empty -#' @return An edge sequence containing the incident edges of -#' the input vertex. +#' @return An edge sequence containing the incident edges of the input vertex. #' #' @family structural queries #' @@ -501,8 +483,8 @@ is_directed <- function(graph) { #' @param graph The input graph #' @param es The sequence of edges to query #' @inheritParams rlang::args_dots_empty -#' @param names Whether to return vertex names or -#' numeric vertex IDs. By default vertex names are used. +#' @param names Whether to return vertex names or numeric vertex IDs. +#' By default vertex names are used. #' @return A two column matrix of vertex names or vertex IDs. #' #' @aliases get.edges @@ -622,31 +604,26 @@ el_to_vec <- function(x, call = rlang::caller_env()) { #' Find the edge IDs based on the incident vertices of the edges #' -#' Find the edges in an igraph graph that have the specified end points. This -#' function handles multi-graph (graphs with multiple edges) and can consider -#' or ignore the edge directions in directed graphs. +#' Find the edges in an igraph graph that have the specified end points. +#' This function handles multi-graph (graphs with multiple edges) and can consider or ignore the edge directions in directed graphs. #' -#' igraph vertex IDs are natural numbers, starting from one, up to the number -#' of vertices in the graph. Similarly, edges are also numbered from one, up to -#' the number of edges. +#' igraph vertex IDs are natural numbers, starting from one, up to the number of vertices in the graph. +#' Similarly, edges are also numbered from one, up to the number of edges. #' -#' This function allows finding the edges of the graph, via their incident -#' vertices. +#' This function allows finding the edges of the graph, via their incident vertices. #' #' @param graph The input graph. -#' @param vp The incident vertices, given as a two-column data frame, two-column matrix, -#' or vector of vertex IDs or symbolic vertex names. -#' For a vector, the values are interpreted pairwise, i.e. the first and second are used for -#' the first edge, the third and fourth for the second, etc. +#' @param vp The incident vertices, given as a two-column data frame, two-column matrix, or vector of vertex IDs or symbolic vertex names. +#' For a vector, the values are interpreted pairwise, i.e. the first and second are used for the first edge, +#' the third and fourth for the second, etc. #' @inheritParams rlang::args_dots_empty -#' @param directed Logical, whether to consider edge directions in -#' directed graphs. This argument is ignored for undirected graphs. -#' @param error Logical, whether to report an error if an edge is not -#' found in the graph. If `FALSE`, then no error is reported, and zero is -#' returned for the non-existant edge(s). +#' @param directed Logical, whether to consider edge directions in directed graphs. +#' This argument is ignored for undirected graphs. +#' @param error Logical, whether to report an error if an edge is not found in the graph. +#' If `FALSE`, then no error is reported, and zero is returned for the non-existant edge(s). #' @return A numeric vector of edge IDs, one for each pair of input vertices. -#' If there is no edge in the input graph for a given pair of vertices, then -#' zero is reported. (If the `error` argument is `FALSE`.) +#' If there is no edge in the input graph for a given pair of vertices, then zero is reported. +#' (If the `error` argument is `FALSE`.) #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @export #' @family structural queries @@ -731,11 +708,9 @@ get_edge_ids <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `get.edge.ids()` was renamed to [get_edge_ids()] to create a more -#' consistent API. +#' `get.edge.ids()` was renamed to [get_edge_ids()] to create a more consistent API. #' @inheritParams get_edge_ids -#' @param multi -#' `r lifecycle::badge("deprecated")` +#' @param multi `r lifecycle::badge("deprecated")` #' @keywords internal #' @export get.edge.ids <- function( @@ -783,8 +758,7 @@ gorder <- vcount #' Adjacent vertices of multiple vertices in a graph #' -#' This function is similar to [neighbors()], but it queries -#' the adjacent vertices for multiple vertices at once. +#' This function is similar to [neighbors()], but it queries the adjacent vertices for multiple vertices at once. #' #' @param graph Input graph. #' @param v The vertices to query. @@ -861,8 +835,7 @@ adjacent_vertices <- function( #' Incident edges of multiple vertices in a graph #' -#' This function is similar to [incident()], but it -#' queries multiple vertices at once. +#' This function is similar to [incident()], but it queries multiple vertices at once. #' #' @param graph Input graph. #' @param v The vertices to query @@ -939,20 +912,16 @@ incident_edges <- function( #' Invalidate the cache of a graph #' -#' igraph graphs cache some basic properties (such as whether the graph is a -#' DAG or whether it is simple) in an internal data structure for faster -#' repeated queries. This function invalidates the cache, forcing a -#' recalculation of the cached properties the next time they are needed. +#' igraph graphs cache some basic properties (such as whether the graph is a DAG or whether it is simple) in an internal data structure for faster repeated queries. +#' This function invalidates the cache, forcing a recalculation of the cached properties the next time they are needed. #' -#' You should not need to call this function during normal usage; however, it -#' may be useful for debugging cache-related issues. A tell-tale sign of an -#' invalid cache entry is when the result of a cached function (such as -#' \code{\link{is_dag}()} or \code{\link{is_simple}()}) changes after calling -#' this function. +#' You should not need to call this function during normal usage; however, it may be useful for debugging cache-related issues. +#' A tell-tale sign of an invalid cache entry is +#' when the result of a cached function (such as \code{\link{is_dag}()} or \code{\link{is_simple}()}) changes after calling this function. #' #' @param graph The graph whose cache is to be invalidated. -#' @return The graph with its cache invalidated. Since the graph is modified -#' in place in R as well, you can also ignore the return value. +#' @return The graph with its cache invalidated. +#' Since the graph is modified in place in R as well, you can also ignore the return value. #' #' @family low-level operations #' diff --git a/R/iterators.R b/R/iterators.R index 15e1875e434..e78643dfaa2 100644 --- a/R/iterators.R +++ b/R/iterators.R @@ -60,19 +60,15 @@ get_es_graph_id <- get_vs_graph_id <- function(seq) { #' Decide if two graphs are identical #' -#' Two graphs are considered identical by this function if and only if -#' they are represented in exactly the same way in the internal R -#' representation. This means that the two graphs must have the same -#' list of vertices and edges, in exactly the same order, with same -#' directedness, and the two graphs must also have identical graph, vertex and -#' edge attributes. +#' Two graphs are considered identical by this function if and only +#' if they are represented in exactly the same way in the internal R representation. +#' This means that the two graphs must have the same list of vertices and edges, in exactly the same order, with same directedness, +#' and the two graphs must also have identical graph, vertex and edge attributes. #' -#' This is similar to `identical` in the `base` package, -#' but it ignores the mutable piece of igraph objects; those might be -#' different even if the two graphs are identical. +#' This is similar to `identical` in the `base` package, but it ignores the mutable piece of igraph objects; +#' those might be different even if the two graphs are identical. #' -#' Attribute comparison can be turned off with the `attrs` parameter if -#' the attributes of the two graphs are allowed to be different. +#' Attribute comparison can be turned off with the `attrs` parameter if the attributes of the two graphs are allowed to be different. #' #' @param g1,g2 The two graphs #' @inheritParams rlang::args_dots_empty @@ -140,15 +136,14 @@ add_vses_graph_ref <- function(vses, graph) { #' Get the ID of a graph #' -#' Graph IDs are used to check that a vertex or edge sequence -#' belongs to a graph. If you create a new graph by changing the -#' structure of a graph, the new graph will have a new ID. +#' Graph IDs are used to check that a vertex or edge sequence belongs to a graph. +#' If you create a new graph by changing the structure of a graph, the new graph will have a new ID. #' Changing the attributes will not change the ID. #' #' @param x A graph or a vertex sequence or an edge sequence. #' @param ... Not used currently. -#' @return The ID of the graph, a character scalar. For -#' vertex and edge sequences the ID of the graph they were created from. +#' @return The ID of the graph, a character scalar. +#' For vertex and edge sequences the ID of the graph they were created from. #' #' @export #' @examples @@ -238,39 +233,32 @@ inside_square_error <- function(fn_name, call = rlang::caller_env()) { #' Create a vertex sequence (vs) containing all vertices of a graph. #' #' @details -#' A vertex sequence is just what the name says it is: a sequence of -#' vertices. Vertex sequences are usually used as igraph function arguments -#' that refer to vertices of a graph. -#' -#' A vertex sequence is tied to the graph it refers to: it really denoted -#' the specific vertices of that graph, and cannot be used together with -#' another graph. -#' -#' At the implementation level, a vertex sequence is simply a vector -#' containing numeric vertex IDs, but it has a special class attribute -#' which makes it possible to perform graph specific operations on it, like -#' selecting a subset of the vertices based on graph structure, or vertex -#' attributes. -#' -#' A vertex sequence is most often created by the `V()` function. The -#' result of this includes all vertices in increasing vertex ID order. A -#' vertex sequence can be indexed by a numeric vector, just like a regular -#' R vector. See \code{\link{[.igraph.vs}} and additional links to other -#' vertex sequence operations below. +#' A vertex sequence is just what the name says it is: a sequence of vertices. +#' Vertex sequences are usually used as igraph function arguments that refer to vertices of a graph. +#' +#' A vertex sequence is tied to the graph it refers to: it really denoted the specific vertices of that graph, +#' and cannot be used together with another graph. +#' +#' At the implementation level, a vertex sequence is simply a vector containing numeric vertex IDs, +#' but it has a special class attribute which makes it possible to perform graph specific operations on it, +#' like selecting a subset of the vertices based on graph structure, or vertex attributes. +#' +#' A vertex sequence is most often created by the `V()` function. +#' The result of this includes all vertices in increasing vertex ID order. +#' A vertex sequence can be indexed by a numeric vector, just like a regular R vector. +#' See \code{\link{[.igraph.vs}} and additional links to other vertex sequence operations below. #' #' @section Indexing vertex sequences: -#' Vertex sequences mostly behave like regular vectors, but there are some -#' additional indexing operations that are specific for them; -#' e.g. selecting vertices based on graph structure, or based on vertex -#' attributes. See \code{\link{[.igraph.vs}} for details. +#' Vertex sequences mostly behave like regular vectors, but there are some additional indexing operations that are specific for them; +#' e.g. selecting vertices based on graph structure, or based on vertex attributes. +#' See \code{\link{[.igraph.vs}} for details. #' #' @section Querying or setting attributes: -#' Vertex sequences can be used to query or set attributes for the -#' vertices in the sequence. See [$.igraph.vs()] for details. +#' Vertex sequences can be used to query or set attributes for the vertices in the sequence. +#' See [$.igraph.vs()] for details. #' #' @param graph The graph -#' @return A vertex sequence containing all vertices, in the order -#' of their numeric vertex IDs. +#' @return A vertex sequence containing all vertices, in the order of their numeric vertex IDs. #' #' @family vertex and edge sequences #' @export @@ -332,46 +320,37 @@ unsafe_create_es <- function(graph, idx, es = NULL) { #' Edges of a graph #' -#' An edge sequence is a vector containing numeric edge IDs, with a special -#' class attribute that allows custom operations: selecting subsets of -#' edges based on attributes, or graph structure, creating the -#' intersection, union of edges, etc. +#' An edge sequence is a vector containing numeric edge IDs, with a special class attribute that allows custom operations: +#' selecting subsets of edges based on attributes, or graph structure, creating the intersection, union of edges, etc. #' #' @details -#' Edge sequences are usually used as igraph function arguments that -#' refer to edges of a graph. +#' Edge sequences are usually used as igraph function arguments that refer to edges of a graph. #' -#' An edge sequence is tied to the graph it refers to: it really denoted -#' the specific edges of that graph, and cannot be used together with -#' another graph. +#' An edge sequence is tied to the graph it refers to: it really denoted the specific edges of that graph, +#' and cannot be used together with another graph. #' -#' An edge sequence is most often created by the `E()` function. The -#' result includes edges in increasing edge ID order by default (if. none -#' of the `P` and `path` arguments are used). An edge -#' sequence can be indexed by a numeric vector, just like a regular R -#' vector. See links to other edge sequence operations below. +#' An edge sequence is most often created by the `E()` function. +#' The result includes edges in increasing edge ID order by default (if. none of the `P` and `path` arguments are used). +#' An edge sequence can be indexed by a numeric vector, just like a regular R vector. +#' See links to other edge sequence operations below. #' #' @section Indexing edge sequences: -#' Edge sequences mostly behave like regular vectors, but there are some -#' additional indexing operations that are specific for them; -#' e.g. selecting edges based on graph structure, or based on edge -#' attributes. See \code{\link{[.igraph.es}} for details. +#' Edge sequences mostly behave like regular vectors, but there are some additional indexing operations that are specific for them; +#' e.g. selecting edges based on graph structure, or based on edge attributes. +#' See \code{\link{[.igraph.es}} for details. #' #' @section Querying or setting attributes: -#' Edge sequences can be used to query or set attributes for the -#' edges in the sequence. See [$.igraph.es()] for details. +#' Edge sequences can be used to query or set attributes for the edges in the sequence. +#' See [$.igraph.es()] for details. #' #' @param graph The graph. #' @inheritParams rlang::args_dots_empty #' @param P A list of vertices to select edges via pairs of vertices. -#' The first and second vertices select the first edge, the third -#' and fourth the second, etc. +#' The first and second vertices select the first edge, the third and fourth the second, etc. #' @param path A list of vertices, to select edges along a path. -#' Note that this only works reliable for simple graphs. If the graph -#' has multiple edges, one of them will be chosen arbitrarily to -#' be included in the edge sequence. -#' @param directed Whether to consider edge directions in the `P` -#' argument, for directed graphs. +#' Note that this only works reliable for simple graphs. +#' If the graph has multiple edges, one of them will be chosen arbitrarily to be included in the edge sequence. +#' @param directed Whether to consider edge directions in the `P` argument, for directed graphs. #' @return An edge sequence of the graph. #' #' @export @@ -497,51 +476,41 @@ simple_vs_index <- function(x, i, na_ok = FALSE) { #' with some extras. #' #' @details -#' Vertex sequences can be indexed using both the single bracket and -#' the double bracket operators, and they both work the same way. -#' The only difference between them is that the double bracket operator -#' marks the result for printing vertex attributes. +#' Vertex sequences can be indexed using both the single bracket and the double bracket operators, and they both work the same way. +#' The only difference between them is that the double bracket operator marks the result for printing vertex attributes. #' #' @section Multiple indices: -#' When using multiple indices within the bracket, all of them -#' are evaluated independently, and then the results are concatenated -#' using the `c()` function (except for the `na_ok` argument, -#' which is special an must be named. E.g. `V(g)[1, 2, .nei(1)]` -#' is equivalent to `c(V(g)[1], V(g)[2], V(g)[.nei(1)])`. +#' When using multiple indices within the bracket, all of them are evaluated independently, +#' and then the results are concatenated using the `c()` function (except for the `na_ok` argument, which is special an must be named. +#' E.g. `V(g)[1, 2, .nei(1)]` is equivalent to `c(V(g)[1], V(g)[2], V(g)[.nei(1)])`. #' #' @section Index types: #' Vertex sequences can be indexed with positive numeric vectors, #' negative numeric vectors, logical vectors, character vectors: #' \itemize{ -#' \item When indexed with positive numeric vectors, the vertices at the -#' given positions in the sequence are selected. This is the same as -#' indexing a regular R atomic vector with positive numeric vectors. -#' \item When indexed with negative numeric vectors, the vertices at the -#' given positions in the sequence are omitted. Again, this is the same -#' as indexing a regular R atomic vector. -#' \item When indexed with a logical vector, the lengths of the vertex -#' sequence and the index must match, and the vertices for which the -#' index is `TRUE` are selected. -#' \item Named graphs can be indexed with character vectors, -#' to select vertices with the given names. +#' \item When indexed with positive numeric vectors, the vertices at the given positions in the sequence are selected. +#' This is the same as indexing a regular R atomic vector with positive numeric vectors. +#' \item When indexed with negative numeric vectors, the vertices at the given positions in the sequence are omitted. +#' Again, this is the same as indexing a regular R atomic vector. +#' \item When indexed with a logical vector, the lengths of the vertex sequence and the index must match, and the vertices for +#' which the index is `TRUE` are selected. +#' \item Named graphs can be indexed with character vectors, to select vertices with the given names. #' } #' #' @section Vertex attributes: -#' When indexing vertex sequences, vertex attributes can be referred -#' to simply by using their names. E.g. if a graph has a `name` vertex -#' attribute, then `V(g)[name == "foo"]` is equivalent to -#' `V(g)[V(g)$name == "foo"]`. See more examples below. Note that attribute -#' names mask the names of variables present in the calling environment; if -#' you need to look up a variable and you do not want a similarly named -#' vertex attribute to mask it, use the `.env` pronoun to perform the -#' name lookup in the calling environment. In other words, use -#' `V(g)[.env$name == "foo"]` to make sure that `name` is looked up -#' from the calling environment even if there is a vertex attribute with the -#' same name. Similarly, you can use `.data` to match attribute names only. +#' When indexing vertex sequences, vertex attributes can be referred to simply by using their names. +#' E.g. if a graph has a `name` vertex attribute, then `V(g)[name == "foo"]` is equivalent to `V(g)[V(g)$name == "foo"]`. +#' See more examples below. +#' Note that attribute names mask the names of variables present in the calling environment; +#' if you need to look up a variable and you do not want a similarly named vertex attribute to mask it, +#' use the `.env` pronoun to perform the name lookup in the calling environment. +#' In other words, +#' use `V(g)[.env$name == "foo"]` to make sure that `name` is looked up from the calling environment even +#' if there is a vertex attribute with the same name. +#' Similarly, you can use `.data` to match attribute names only. #' #' @section Special functions: -#' There are some special igraph functions that can be used only -#' in expressions indexing vertex sequences: +#' There are some special igraph functions that can be used only in expressions indexing vertex sequences: #' \describe{ #' \item{`.nei`}{ #' takes a vertex sequence as its argument @@ -564,14 +533,12 @@ simple_vs_index <- function(x, i, na_ok = FALSE) { #' and `.outnei(v)` is a shorthand for `.nei(v, mode = "out")`. #' } #' } -#' Note that multiple special functions can be used together, or with -#' regular indices, and then their results are concatenated. See more -#' examples below. +#' Note that multiple special functions can be used together, or with regular indices, and then their results are concatenated. +#' See more examples below. #' #' @param x A vertex sequence. #' @param ... Indices, see details below. -#' @param na_ok Whether it is OK to have `NA`s in the vertex -#' sequence. +#' @param na_ok Whether it is OK to have `NA`s in the vertex sequence. #' @return Another vertex sequence, referring to the same graph. #' #' @method [ igraph.vs @@ -843,21 +810,18 @@ set_single_index <- function(x, value = TRUE) { #' Select vertices and show their metadata #' -#' The double bracket operator can be used on vertex sequences, to print -#' the meta-data (vertex attributes) of the vertices in the sequence. +#' The double bracket operator can be used on vertex sequences, to print the meta-data (vertex attributes) of the vertices in the sequence. #' #' @details -#' Technically, when used with vertex sequences, the double bracket -#' operator does exactly the same as the single bracket operator, -#' but the resulting vertex sequence is printed differently: all -#' attributes of the vertices in the sequence are printed as well. +#' Technically, when used with vertex sequences, the double bracket operator does exactly the same as the single bracket operator, +#' but the resulting vertex sequence is printed differently: all attributes of the vertices in the sequence are printed as well. #' #' See \code{\link{[.igraph.vs}} for more about indexing vertex sequences. #' #' @param x A vertex sequence. #' @param ... Additional arguments, passed to `[`. -#' @return The double bracket operator returns another vertex sequence, -#' with meta-data (attribute) printing turned on. See details below. +#' @return The double bracket operator returns another vertex sequence, with meta-data (attribute) printing turned on. +#' See details below. #' #' @method [[ igraph.vs #' @name igraph-vs-indexing2 @@ -879,14 +843,11 @@ set_single_index <- function(x, value = TRUE) { #' Select edges and show their metadata #' -#' The double bracket operator can be used on edge sequences, to print -#' the meta-data (edge attributes) of the edges in the sequence. +#' The double bracket operator can be used on edge sequences, to print the meta-data (edge attributes) of the edges in the sequence. #' #' @details -#' Technically, when used with edge sequences, the double bracket -#' operator does exactly the same as the single bracket operator, -#' but the resulting edge sequence is printed differently: all -#' attributes of the edges in the sequence are printed as well. +#' Technically, when used with edge sequences, the double bracket operator does exactly the same as the single bracket operator, +#' but the resulting edge sequence is printed differently: all attributes of the edges in the sequence are printed as well. #' #' See \code{\link{[.igraph.es}} for more about indexing edge sequences. #' @@ -940,50 +901,42 @@ simple_es_index <- function(x, i, na_ok = FALSE) { #' with some extras. #' #' @section Multiple indices: -#' When using multiple indices within the bracket, all of them -#' are evaluated independently, and then the results are concatenated -#' using the `c()` function. E.g. `E(g)[1, 2, .inc(1)]` -#' is equivalent to `c(E(g)[1], E(g)[2], E(g)[.inc(1)])`. +#' When using multiple indices within the bracket, all of them are evaluated independently, +#' and then the results are concatenated using the `c()` function. +#' E.g. `E(g)[1, 2, .inc(1)]` is equivalent to `c(E(g)[1], E(g)[2], E(g)[.inc(1)])`. #' #' @section Index types: #' Edge sequences can be indexed with positive numeric vectors, #' negative numeric vectors, logical vectors, character vectors: #' \itemize{ -#' \item When indexed with positive numeric vectors, the edges at the -#' given positions in the sequence are selected. This is the same as -#' indexing a regular R atomic vector with positive numeric vectors. -#' \item When indexed with negative numeric vectors, the edges at the -#' given positions in the sequence are omitted. Again, this is the same -#' as indexing a regular R atomic vector. -#' \item When indexed with a logical vector, the lengths of the edge -#' sequence and the index must match, and the edges for which the -#' index is `TRUE` are selected. -#' \item Named graphs can be indexed with character vectors, -#' to select edges with the given names. Note that a graph may -#' have edge names and vertex names, and both can be used to select -#' edges. Edge names are simply used as names of the numeric -#' edge ID vector. Vertex names effectively only work in graphs without -#' multiple edges, and must be separated with a `|` bar character -#' to select an edges that incident to the two given vertices. See -#' examples below. +#' \item When indexed with positive numeric vectors, the edges at the given positions in the sequence are selected. +#' This is the same as indexing a regular R atomic vector with positive numeric vectors. +#' \item When indexed with negative numeric vectors, the edges at the given positions in the sequence are omitted. +#' Again, this is the same as indexing a regular R atomic vector. +#' \item When indexed with a logical vector, the lengths of the edge sequence and the index must match, and the edges for +#' which the index is `TRUE` are selected. +#' \item Named graphs can be indexed with character vectors, to select edges with the given names. +#' Note that a graph may have edge names and vertex names, and both can be used to select edges. +#' Edge names are simply used as names of the numeric edge ID vector. +#' Vertex names effectively only work in graphs without multiple edges, and must be separated with a `|` bar character to select an edges +#' that incident to the two given vertices. +#' See examples below. #' } #' #' @section Edge attributes: -#' When indexing edge sequences, edge attributes can be referred -#' to simply by using their names. E.g. if a graph has a `weight` edge -#' attribute, then `E(G)[weight > 1]` selects all edges with a weight -#' larger than one. See more examples below. Note that attribute names mask the -#' names of variables present in the calling environment; if you need to look up -#' a variable and you do not want a similarly named edge attribute to mask it, -#' use the `.env` pronoun to perform the name lookup in the calling -#' environment. In other words, use `E(g)[.env$weight > 1]` to make sure -#' that `weight` is looked up from the calling environment even if there is -#' an edge attribute with the same name. Similarly, you can use `.data` to -#' match attribute names only. +#' When indexing edge sequences, edge attributes can be referred to simply by using their names. +#' E.g. if a graph has a `weight` edge attribute, then `E(G)[weight > 1]` selects all edges with a weight larger than one. +#' See more examples below. +#' Note that attribute names mask the names of variables present in the calling environment; +#' if you need to look up a variable and you do not want a similarly named edge attribute to mask it, +#' use the `.env` pronoun to perform the name lookup in the calling environment. +#' In other words, +#' use `E(g)[.env$weight > 1]` to make sure that `weight` is looked up from the calling environment even +#' if there is an edge attribute with the same name. +#' Similarly, you can use `.data` to match attribute names only. #' #' @section Special functions: -#' There are some special igraph functions that can be used -#' only in expressions indexing edge sequences: +#' There are some special igraph functions that can be used only in expressions indexing edge sequences: #' \describe{ #' \item{`.inc`}{ #' takes a vertex sequence, and selects all edges that have at least one incident vertex in the vertex sequence. @@ -1007,9 +960,8 @@ simple_es_index <- function(x, i, na_ok = FALSE) { #' pointing *from* the right hand side argument, are selected, in directed graphs. #' } #' } -#' Note that multiple special functions can be used together, or with -#' regular indices, and then their results are concatenated. See more -#' examples below. +#' Note that multiple special functions can be used together, or with regular indices, and then their results are concatenated. +#' See more examples below. #' #' @aliases %--% %<-% %->% #' @param x An edge sequence @@ -1284,24 +1236,19 @@ simple_es_index <- function(x, i, na_ok = FALSE) { #' Query or set attributes of the vertices in a vertex sequence #' -#' The `$` operator is a syntactic sugar to query and set the -#' attributes of the vertices in a vertex sequence. +#' The `$` operator is a syntactic sugar to query and set the attributes of the vertices in a vertex sequence. #' #' @details -#' The query form of `$` is a shortcut for -#' [vertex_attr()], e.g. `V(g)[idx]$attr` is equivalent -#' to `vertex_attr(g, attr, V(g)[idx])`. +#' The query form of `$` is a shortcut for [vertex_attr()], e.g. `V(g)[idx]$attr` is equivalent to `vertex_attr(g, attr, V(g)[idx])`. #' -#' The assignment form of `$` is a shortcut for -#' [set_vertex_attr()], e.g. `V(g)[idx]$attr <- value` is -#' equivalent to `g <- set_vertex_attr(g, attr, V(g)[idx], value)`. +#' The assignment form of `$` is a shortcut for [set_vertex_attr()], +#' e.g. `V(g)[idx]$attr <- value` is equivalent to `g <- set_vertex_attr(g, attr, V(g)[idx], value)`. #' -#' @param x A vertex sequence. For `V<-` it is a graph. +#' @param x A vertex sequence. +#' For `V<-` it is a graph. #' @param name Name of the vertex attribute to query or set. -#' @return A vector or list, containing the values of -#' attribute `name` for the vertices in the vertex sequence. -#' For numeric, character or logical attributes, it is a vector of the -#' appropriate type, otherwise it is a list. +#' @return A vector or list, containing the values of attribute `name` for the vertices in the vertex sequence. +#' For numeric, character or logical attributes, it is a vector of the appropriate type, otherwise it is a list. #' #' @method $ igraph.vs #' @name igraph-vs-attributes @@ -1350,24 +1297,21 @@ simple_es_index <- function(x, i, na_ok = FALSE) { #' Query or set attributes of the edges in an edge sequence #' -#' The `$` operator is a syntactic sugar to query and set -#' edge attributes, for edges in an edge sequence. +#' The `$` operator is a syntactic sugar to query and set edge attributes, for edges in an edge sequence. #' #' @details #' The query form of `$` is a shortcut for [edge_attr()], #' e.g. `E(g)[idx]$attr` is equivalent to `edge_attr(g, attr, #' E(g)[idx])`. #' -#' The assignment form of `$` is a shortcut for -#' [set_edge_attr()], e.g. `E(g)[idx]$attr <- value` is -#' equivalent to `g <- set_edge_attr(g, attr, E(g)[idx], value)`. +#' The assignment form of `$` is a shortcut for [set_edge_attr()], +#' e.g. `E(g)[idx]$attr <- value` is equivalent to `g <- set_edge_attr(g, attr, E(g)[idx], value)`. #' -#' @param x An edge sequence. For `E<-` it is a graph. +#' @param x An edge sequence. +#' For `E<-` it is a graph. #' @param name Name of the edge attribute to query or set. -#' @return A vector or list, containing the values of the attribute -#' `name` for the edges in the sequence. For numeric, character or -#' logical attributes, it is a vector of the appropriate type, otherwise -#' it is a list. +#' @return A vector or list, containing the values of the attribute `name` for the edges in the sequence. +#' For numeric, character or logical attributes, it is a vector of the appropriate type, otherwise it is a list. #' #' @method $ igraph.es #' @name igraph-es-attributes @@ -1401,8 +1345,7 @@ simple_es_index <- function(x, i, na_ok = FALSE) { } } -#' @param value New value of the attribute, for the vertices in the -#' vertex sequence. +#' @param value New value of the attribute, for the vertices in the vertex sequence. #' #' @method $<- igraph.vs #' @name igraph-vs-attributes @@ -1416,8 +1359,7 @@ simple_es_index <- function(x, i, na_ok = FALSE) { x } -#' @param value New value of the attribute, for the edges in the edge -#' sequence. +#' @param value New value of the attribute, for the edges in the edge sequence. #' @method $<- igraph.es #' @name igraph-es-attributes #' @export @@ -1458,11 +1400,10 @@ simple_es_index <- function(x, i, na_ok = FALSE) { ) } -#' @param path Select edges along a path, given by a vertex sequence See -#' [E()]. -#' @param P Select edges via pairs of vertices. See [E()]. -#' @param directed Whether to use edge directions for the `path` or -#' `P` arguments. +#' @param path Select edges along a path, given by a vertex sequence See [E()]. +#' @param P Select edges via pairs of vertices. +#' See [E()]. +#' @param directed Whether to use edge directions for the `path` or `P` arguments. #' @name igraph-es-attributes #' @export `E<-` <- function(x, path = NULL, P = NULL, directed = NULL, value) { @@ -1492,17 +1433,14 @@ simple_es_index <- function(x, i, na_ok = FALSE) { #' Show a vertex sequence on the screen #' -#' For long vertex sequences, the printing is truncated to fit to the -#' screen. Use [print()] explicitly and the `full` argument to -#' see the full sequence. +#' For long vertex sequences, the printing is truncated to fit to the screen. +#' Use [print()] explicitly and the `full` argument to see the full sequence. #' -#' Vertex sequence created with the double bracket operator are -#' printed differently, together with all attributes of the vertices -#' in the sequence, as a table. +#' Vertex sequence created with the double bracket operator are printed differently, +#' together with all attributes of the vertices in the sequence, as a table. #' #' @param x A vertex sequence. -#' @param full Whether to show the full sequence, or truncate the output -#' to the screen size. +#' @param full Whether to show the full sequence, or truncate the output to the screen size. #' @inheritParams print.igraph #' @param ... These arguments are currently ignored. #' @return The vertex sequence, invisibly. @@ -1620,17 +1558,14 @@ print_igraph_vs_legacy <- function( #' Print an edge sequence to the screen #' -#' For long edge sequences, the printing is truncated to fit to the -#' screen. Use [print()] explicitly and the `full` argument to -#' see the full sequence. +#' For long edge sequences, the printing is truncated to fit to the screen. +#' Use [print()] explicitly and the `full` argument to see the full sequence. #' -#' Edge sequences created with the double bracket operator are printed -#' differently, together with all attributes of the edges in the sequence, -#' as a table. +#' Edge sequences created with the double bracket operator are printed differently, +#' together with all attributes of the edges in the sequence, as a table. #' #' @param x An edge sequence. -#' @param full Whether to show the full sequence, or truncate the output -#' to the screen size. +#' @param full Whether to show the full sequence, or truncate the output to the screen size. #' @inheritParams print.igraph #' @param ... Currently ignored. #' @return The edge sequence, invisibly. @@ -1732,11 +1667,10 @@ print_igraph_vs_cli <- function( # * compact -- a bare list of vertex ids, or names when present; produced # by `V(g)[...]`. # - # `[[` and `[` build the *same* underlying sequence: `[[.igraph.vs` merely - # tags its result with a "single" attribute, which is_single_index() reads - # here. So the only signal asking for the detailed view is that flag. We use - # the table only when it is set AND the graph is still alive (a sequence can - # outlive its graph) AND the graph actually has attributes to tabulate; + # `[[` and `[` build the *same* underlying sequence: `[[.igraph.vs` merely tags its result with a "single" attribute, + # which is_single_index() reads here. + # So the only signal asking for the detailed view is that flag. + # We use the table only when it is set AND the graph is still alive (a sequence can outlive its graph) AND the graph actually has attributes to tabulate; # anything else falls through to the compact list below. if ( is_single_index(x) && @@ -1744,9 +1678,8 @@ print_igraph_vs_cli <- function( length(vertex_attr_names(graph)) > 0 ) { vertex_attrs <- vertex_attr(graph) - # A data.frame needs flat columns, so it works only when every attribute is - # atomic. If any attribute is list-valued, drop to a named list sliced to - # the selected vertices instead of forcing it into a table. + # A data.frame needs flat columns, so it works only when every attribute is atomic. + # If any attribute is list-valued, drop to a named list sliced to the selected vertices instead of forcing it into a table. if (all(vapply(vertex_attrs, is.atomic, logical(1)))) { print(list2DF(vertex_attrs)[ as.vector(x), @@ -1816,12 +1749,11 @@ print_igraph_es_cli <- function( # * compact -- a list of "tail head" strings; produced by # `E(g)[...]`. Handled further below. # - # As with vertex sequences, `[[` and `[` build the same underlying sequence; - # `[[.igraph.es` only tags its result with the "single" attribute that - # is_single_index() reads here. The table needs only that flag and a live - # graph -- unlike the vertex case there is no attribute-count check, because - # an edge always has endpoints to tabulate (the tail/head names plus their - # raw numeric ids in tid/hid), so the table is never empty. + # As with vertex sequences, `[[` and `[` build the same underlying sequence; `[[.igraph.es` only tags its result with the "single" attribute + # that is_single_index() reads here. + # The table needs only that flag and a live graph -- unlike the vertex case there is no attribute-count check, + # because an edge always has endpoints to tabulate (the tail/head names plus their raw numeric ids in tid/hid), + # so the table is never empty. if (is_single_index(x) && !is.null(graph)) { print_edge_detail(graph, x) return(invisible(x)) @@ -2009,7 +1941,8 @@ create_op_result <- function(parsed, result, class, args) { #' #' @param x A vertex sequence. #' @param incomparables a vector of values that cannot be compared. -#' Passed to base function `duplicated`. See details there. +#' Passed to base function `duplicated`. +#' See details there. #' @param ... Passed to base function `duplicated()`. #' @return A vertex sequence with the duplicate vertices removed. #' @@ -2029,7 +1962,8 @@ unique.igraph.vs <- function(x, incomparables = FALSE, ...) { #' #' @param x An edge sequence. #' @param incomparables a vector of values that cannot be compared. -#' Passed to base function `duplicated`. See details there. +#' Passed to base function `duplicated`. +#' See details there. #' @param ... Passed to base function `duplicated()`. #' @return An edge sequence with the duplicate vertices removed. #' @@ -2047,10 +1981,9 @@ unique.igraph.es <- function(x, incomparables = FALSE, ...) { #' Concatenate vertex sequences #' -#' @param ... The vertex sequences to concatenate. They must -#' refer to the same graph. -#' @param recursive Ignored, included for S3 compatibility with -#' the base `c` function. +#' @param ... The vertex sequences to concatenate. +#' They must refer to the same graph. +#' @param recursive Ignored, included for S3 compatibility with the base `c` function. #' @return A vertex sequence, the input sequences concatenated. #' #' @method c igraph.vs @@ -2068,10 +2001,9 @@ c.igraph.vs <- function(..., recursive = FALSE) { #' Concatenate edge sequences #' -#' @param ... The edge sequences to concatenate. They must -#' all refer to the same graph. -#' @param recursive Ignored, included for S3 compatibility with the -#' base `c` function. +#' @param ... The edge sequences to concatenate. +#' They must all refer to the same graph. +#' @param recursive Ignored, included for S3 compatibility with the base `c` function. #' @return An edge sequence, the input sequences concatenated. #' #' @method c igraph.es @@ -2092,14 +2024,12 @@ c.igraph.es <- function(..., recursive = FALSE) { #' Union of vertex sequences #' #' @details -#' They must belong to the same graph. Note that this function has -#' \sQuote{set} semantics and the multiplicity of vertices is lost in the -#' result. (This is to match the behavior of the based `unique` -#' function.) +#' They must belong to the same graph. +#' Note that this function has \sQuote{set} semantics and the multiplicity of vertices is lost in the result. +#' (This is to match the behavior of the based `unique` function.) #' #' @param ... The vertex sequences to take the union of. -#' @return A vertex sequence that contains all vertices in the given -#' sequences, exactly once. +#' @return A vertex sequence that contains all vertices in the given sequences, exactly once. #' #' @method union igraph.vs #' @family vertex and edge sequence operations @@ -2115,14 +2045,12 @@ union.igraph.vs <- function(...) { #' Union of edge sequences #' #' @details -#' They must belong to the same graph. Note that this function has -#' \sQuote{set} semantics and the multiplicity of edges is lost in the -#' result. (This is to match the behavior of the based `unique` -#' function.) +#' They must belong to the same graph. +#' Note that this function has \sQuote{set} semantics and the multiplicity of edges is lost in the result. +#' (This is to match the behavior of the based `unique` function.) #' #' @param ... The edge sequences to take the union of. -#' @return An edge sequence that contains all edges in the given -#' sequences, exactly once. +#' @return An edge sequence that contains all edges in the given sequences, exactly once. #' #' @method union igraph.es #' @family vertex and edge sequence operations @@ -2136,13 +2064,11 @@ union.igraph.es <- union.igraph.vs #' Intersection of vertex sequences #' #' @details -#' They must belong to the same graph. Note that this function has -#' \sQuote{set} semantics and the multiplicity of vertices is lost in the -#' result. +#' They must belong to the same graph. +#' Note that this function has \sQuote{set} semantics and the multiplicity of vertices is lost in the result. #' #' @param ... The vertex sequences to take the intersection of. -#' @return A vertex sequence that contains vertices that appear in all -#' given sequences, each vertex exactly once. +#' @return A vertex sequence that contains vertices that appear in all given sequences, each vertex exactly once. #' #' @method intersection igraph.vs #' @family vertex and edge sequence operations @@ -2161,13 +2087,11 @@ intersection.igraph.vs <- function(...) { #' Intersection of edge sequences #' #' @details -#' They must belong to the same graph. Note that this function has -#' \sQuote{set} semantics and the multiplicity of edges is lost in the -#' result. +#' They must belong to the same graph. +#' Note that this function has \sQuote{set} semantics and the multiplicity of edges is lost in the result. #' #' @param ... The edge sequences to take the intersection of. -#' @return An edge sequence that contains edges that appear in all -#' given sequences, each edge exactly once. +#' @return An edge sequence that contains edges that appear in all given sequences, each edge exactly once. #' #' @method intersection igraph.es #' @family vertex and edge sequence operations @@ -2181,15 +2105,13 @@ intersection.igraph.es <- intersection.igraph.vs #' Difference of vertex sequences #' #' @details -#' They must belong to the same graph. Note that this function has -#' \sQuote{set} semantics and the multiplicity of vertices is lost in the -#' result. +#' They must belong to the same graph. +#' Note that this function has \sQuote{set} semantics and the multiplicity of vertices is lost in the result. #' #' @param big The \sQuote{big} vertex sequence. #' @param small The \sQuote{small} vertex sequence. #' @param ... Ignored, included for S3 signature compatibility. -#' @return A vertex sequence that contains only vertices that are part of -#' `big`, but not part of `small`. +#' @return A vertex sequence that contains only vertices that are part of `big`, but not part of `small`. #' #' @method difference igraph.vs #' @family vertex and edge sequence operations @@ -2209,15 +2131,13 @@ difference.igraph.vs <- function(big, small, ...) { #' Difference of edge sequences #' #' @details -#' They must belong to the same graph. Note that this function has -#' \sQuote{set} semantics and the multiplicity of edges is lost in the -#' result. +#' They must belong to the same graph. +#' Note that this function has \sQuote{set} semantics and the multiplicity of edges is lost in the result. #' #' @param big The \sQuote{big} edge sequence. #' @param small The \sQuote{small} edge sequence. #' @param ... Ignored, included for S3 signature compatibility. -#' @return An edge sequence that contains only edges that are part of -#' `big`, but not part of `small`. +#' @return An edge sequence that contains only edges that are part of `big`, but not part of `small`. #' #' @method difference igraph.es #' @family vertex and edge sequence operations @@ -2261,15 +2181,12 @@ rev.igraph.es <- rev.igraph.vs #' Convert a vertex or edge sequence to an ordinary vector #' #' @details -#' For graphs without names, a numeric vector is returned, containing the -#' internal numeric vertex or edge IDs. +#' For graphs without names, a numeric vector is returned, containing the internal numeric vertex or edge IDs. #' -#' For graphs with names, and vertex sequences, the vertex names are -#' returned in a character vector. +#' For graphs with names, and vertex sequences, the vertex names are returned in a character vector. #' -#' For graphs with names and edge sequences, a character vector is -#' returned, with the \sQuote{bar} notation: `a|b` means an edge from -#' vertex `a` to vertex `b`. +#' For graphs with names and edge sequences, a character vector is returned, with the \sQuote{bar} notation: +#' `a|b` means an edge from vertex `a` to vertex `b`. #' #' @param seq The vertex or edge sequence. #' @return A character or numeric vector, see details below. diff --git a/R/layout.R b/R/layout.R index 7e1c189bf97..da3ddbe03dd 100644 --- a/R/layout.R +++ b/R/layout.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `piecewise.layout()` was renamed to [layout_components()] to create a more -#' consistent API. +#' `piecewise.layout()` was renamed to [layout_components()] to create a more consistent API. #' @inheritParams layout_components #' @keywords internal #' @export @@ -23,8 +22,7 @@ piecewise.layout <- function(graph, layout = layout_with_kk, ...) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `layout.sugiyama()` was renamed to [layout_with_sugiyama()] to create a more -#' consistent API. +#' `layout.sugiyama()` was renamed to [layout_with_sugiyama()] to create a more consistent API. #' @inheritParams layout_with_sugiyama #' @keywords internal #' @export @@ -59,8 +57,7 @@ layout.sugiyama <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `layout.star()` was renamed to [layout_as_star()] to create a more -#' consistent API. +#' `layout.star()` was renamed to [layout_as_star()] to create a more consistent API. #' @inheritParams layout_as_star #' @keywords internal #' @export @@ -75,8 +72,7 @@ layout.star <- function(graph, center = V(graph)[1], order = NULL) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `layout.norm()` was renamed to [norm_coords()] to create a more -#' consistent API. +#' `layout.norm()` was renamed to [norm_coords()] to create a more consistent API. #' @inheritParams norm_coords #' @keywords internal #' @export @@ -107,8 +103,7 @@ layout.norm <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `layout.merge()` was renamed to [merge_coords()] to create a more -#' consistent API. +#' `layout.merge()` was renamed to [merge_coords()] to create a more consistent API. #' @inheritParams merge_coords #' @keywords internal #' @export @@ -123,8 +118,7 @@ layout.merge <- function(graphs, layouts, method = "dla") { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `layout.mds()` was renamed to [layout_with_mds()] to create a more -#' consistent API. +#' `layout.mds()` was renamed to [layout_with_mds()] to create a more consistent API. #' @inheritParams layout_with_mds #' @keywords internal #' @export @@ -144,8 +138,7 @@ layout.mds <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `layout.grid()` was renamed to [layout_on_grid()] to create a more -#' consistent API. +#' `layout.grid()` was renamed to [layout_on_grid()] to create a more consistent API. #' @inheritParams layout_on_grid #' @keywords internal #' @export @@ -160,8 +153,7 @@ layout.grid <- function(graph, width = 0, height = 0, dim = 2) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `layout.graphopt()` was renamed to [layout_with_graphopt()] to create a more -#' consistent API. +#' `layout.graphopt()` was renamed to [layout_with_graphopt()] to create a more consistent API. #' @inheritParams layout_with_graphopt #' @keywords internal #' @export @@ -198,8 +190,7 @@ layout.graphopt <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `layout.gem()` was renamed to [layout_with_gem()] to create a more -#' consistent API. +#' `layout.gem()` was renamed to [layout_with_gem()] to create a more consistent API. #' @inheritParams layout_with_gem #' @keywords internal #' @export @@ -228,8 +219,7 @@ layout.gem <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `layout.davidson.harel()` was renamed to [layout_with_dh()] to create a more -#' consistent API. +#' `layout.davidson.harel()` was renamed to [layout_with_dh()] to create a more consistent API. #' @inheritParams layout_with_dh #' @keywords internal #' @export @@ -270,8 +260,7 @@ layout.davidson.harel <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `layout.bipartite()` was renamed to [layout_as_bipartite()] to create a more -#' consistent API. +#' `layout.bipartite()` was renamed to [layout_as_bipartite()] to create a more consistent API. #' @inheritParams layout_as_bipartite #' @keywords internal #' @export @@ -302,8 +291,7 @@ layout.bipartite <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `layout.auto()` was renamed to [layout_nicely()] to create a more -#' consistent API. +#' `layout.auto()` was renamed to [layout_nicely()] to create a more consistent API. #' @inheritParams layout_nicely #' @keywords internal #' @export @@ -342,30 +330,24 @@ layout.auto <- function(graph, dim = 2, ...) { #' Graph layouts #' -#' This is a generic function to apply a layout function to -#' a graph. +#' This is a generic function to apply a layout function to a graph. #' #' There are two ways to calculate graph layouts in igraph. -#' The first way is to call a layout function (they all have -#' prefix `layout_()` on a graph, to get the vertex coordinates. +#' The first way is to call a layout function (they all have prefix `layout_()` on a graph, to get the vertex coordinates. #' -#' The second way (new in igraph 0.8.0), has two steps, and it -#' is more flexible. First you call a layout specification -#' function (the one without the `layout_()` prefix, and -#' then `layout_()` (or [add_layout_()]) to -#' perform the layouting. +#' The second way (new in igraph 0.8.0), has two steps, and it is more flexible. +#' First you call a layout specification function (the one without the `layout_()` prefix, +#' and then `layout_()` (or [add_layout_()]) to perform the layouting. #' -#' The second way is preferred, as it is more flexible. It allows -#' operations before and after the layouting. E.g. using the -#' `component_wise()` argument, the layout can be calculated -#' separately for each component, and then merged to get the -#' final results. +#' The second way is preferred, as it is more flexible. +#' It allows operations before and after the layouting. +#' E.g. using the `component_wise()` argument, the layout can be calculated separately for each component, +#' and then merged to get the final results. #' #' @aliases layout #' @section Modifiers: #' Modifiers modify how a layout calculation is performed. -#' Modifiers are applied in the order they are specified as arguments to -#' `layout_()`. +#' Modifiers are applied in the order they are specified as arguments to `layout_()`. #' #' There are two types of modifiers: #' \itemize{ @@ -395,15 +377,14 @@ layout.auto <- function(graph, dim = 2, ...) { #' } #' #' @param graph The input graph. -#' @param layout The layout specification. It must be a call -#' to a layout specification function. +#' @param layout The layout specification. +#' It must be a call to a layout specification function. #' @param ... Further modifiers, see a complete list below. #' For the [print()] methods, it is ignored. -#' @return The return value of the layout function, usually a -#' two column matrix. For 3D layouts a three column matrix. +#' @return The return value of the layout function, usually a two column matrix. +#' For 3D layouts a three column matrix. #' -#' @seealso [add_layout_()] to add the layout to the -#' graph as an attribute. +#' @seealso [add_layout_()] to add the layout to the graph as an attribute. #' @export #' @family graph layouts #' @examples @@ -521,10 +502,10 @@ print.igraph_layout_spec <- function(x, ...) { #' Create a layout modifier #' #' This is a constructor function for creating custom layout modifiers. -#' Layout modifiers can be used with [layout_()] to modify how layouts -#' are calculated or to transform the resulting coordinates. +#' Layout modifiers can be used with [layout_()] to modify how layouts are calculated or to transform the resulting coordinates. #' -#' @param ... Named arguments that define the modifier. Must include: +#' @param ... Named arguments that define the modifier. +#' Must include: #' \describe{ #' \item{ID}{A unique identifier string for the modifier} #' \item{type}{Either `"pre"` for pre-layout or `"post"` for post-layout} @@ -535,8 +516,7 @@ print.igraph_layout_spec <- function(x, ...) { #' #' @return An object of class `igraph_layout_modifier`. #' -#' @seealso [layout_()] for using modifiers, [component_wise()], [normalize()] -#' for examples of built-in modifiers. +#' @seealso [layout_()] for using modifiers, [component_wise()], [normalize()] for examples of built-in modifiers. #' #' @family layout modifiers #' @export @@ -574,12 +554,9 @@ print.igraph_layout_modifier <- function(x, ...) { #' Component-wise layout #' -#' This is a layout modifier function, and it can be used -#' to calculate the layout separately for each component -#' of the graph. +#' This is a layout modifier function, and it can be used to calculate the layout separately for each component of the graph. #' -#' @param merge_method Merging algorithm, the `method` -#' argument of [merge_coords()]. +#' @param merge_method Merging algorithm, the `method` argument of [merge_coords()]. #' #' @family layout modifiers #' @family graph layouts @@ -619,12 +596,10 @@ component_wise <- function(merge_method = "dla") { #' Scale coordinates of a layout. #' #' @param xmin,xmax Minimum and maximum for x coordinates. -#' @param ymin,ymax Minimum and maximum for y coordinates. When omitted, -#' they follow `xmin` and `xmax`; `NULL` disables normalization along -#' this axis. -#' @param zmin,zmax Minimum and maximum for z coordinates. When omitted, -#' they follow `xmin` and `xmax`; `NULL` disables normalization along -#' this axis. +#' @param ymin,ymax Minimum and maximum for y coordinates. +#' When omitted, they follow `xmin` and `xmax`; `NULL` disables normalization along this axis. +#' @param zmin,zmax Minimum and maximum for z coordinates. +#' When omitted, they follow `xmin` and `xmax`; `NULL` disables normalization along this axis. #' #' @family layout modifiers #' @family graph layouts @@ -678,32 +653,24 @@ normalize <- function( #' Simple two-row layout for bipartite graphs #' -#' Minimize edge-crossings in a simple two-row (or column) layout for bipartite -#' graphs. +#' Minimize edge-crossings in a simple two-row (or column) layout for bipartite graphs. #' -#' The layout is created by first placing the vertices in two rows, according -#' to their types. Then the positions within the rows are optimized to minimize -#' edge crossings, using the Sugiyama algorithm (see -#' [layout_with_sugiyama()]). +#' The layout is created by first placing the vertices in two rows, according to their types. +#' Then the positions within the rows are optimized to minimize edge crossings, using the Sugiyama algorithm (see [layout_with_sugiyama()]). #' -#' @param graph The bipartite input graph. It should have a logical -#' \sQuote{`type`} vertex attribute, or the `types` argument must be -#' given. -#' @param types A logical vector, the vertex types. If this argument is -#' `NULL` (the default), then the \sQuote{`type`} vertex attribute is -#' used. +#' @param graph The bipartite input graph. +#' It should have a logical \sQuote{`type`} vertex attribute, or the `types` argument must be given. +#' @param types A logical vector, the vertex types. +#' If this argument is `NULL` (the default), then the \sQuote{`type`} vertex attribute is used. #' @inheritParams rlang::args_dots_empty -#' @param hgap Real scalar, the minimum horizontal gap between vertices in the -#' same layer. +#' @param hgap Real scalar, the minimum horizontal gap between vertices in the same layer. #' @param vgap Real scalar, the distance between the two layers. -#' @param maxiter Integer scalar, the maximum number of iterations in the -#' crossing minimization stage. 100 is a reasonable default; if you feel that -#' you have too many edge crossings, increase this. -#' @return A matrix with two columns and as many rows as the number of vertices -#' in the input graph. +#' @param maxiter Integer scalar, the maximum number of iterations in the crossing minimization stage. +#' 100 is a reasonable default; if you feel that you have too many edge crossings, increase this. +#' @return A matrix with two columns and as many rows as the number of vertices in the input graph. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso [layout_with_sugiyama()]. See [as_bipartite()] to build a lazy -#' layout specification for [add_layout_()]. +#' @seealso [layout_with_sugiyama()]. +#' See [as_bipartite()] to build a lazy layout specification for [add_layout_()]. #' @keywords graphs #' @export #' @family graph layouts @@ -783,27 +750,20 @@ layout_as_bipartite <- function( #' Layout specifications for `layout_()` and `add_layout_()` #' #' @description -#' Each of these functions builds a lazy layout specification for the given -#' layout function, to be used with [layout_()] or [add_layout_()]. The -#' specification is only evaluated when the layout is actually computed, so it -#' can be combined with layout modifiers such as [component_wise()] or -#' [normalize()]. -#' -#' `as_bipartite()`, `as_star()` and `as_tree()` wrap [layout_as_bipartite()], -#' [layout_as_star()] and [layout_as_tree()] respectively. `in_circle()`, -#' `nicely()`, `on_grid()`, `on_sphere()` and `randomly()` wrap -#' [layout_in_circle()], [layout_nicely()], [layout_on_grid()], -#' [layout_on_sphere()] and [layout_randomly()]. `with_dh()`, `with_fr()`, -#' `with_gem()`, `with_graphopt()`, `with_kk()`, `with_lgl()`, `with_mds()`, -#' `with_sugiyama()` and `with_drl()` wrap [layout_with_dh()], -#' [layout_with_fr()], [layout_with_gem()], [layout_with_graphopt()], -#' [layout_with_kk()], [layout_with_lgl()], [layout_with_mds()], -#' [layout_with_sugiyama()] and [layout_with_drl()]. +#' Each of these functions builds a lazy layout specification for the given layout function, to be used with [layout_()] or [add_layout_()]. +#' The specification is only evaluated when the layout is actually computed, +#' so it can be combined with layout modifiers such as [component_wise()] or [normalize()]. +#' +#' `as_bipartite()`, `as_star()` and `as_tree()` wrap [layout_as_bipartite()], [layout_as_star()] and [layout_as_tree()] respectively. +#' `in_circle()`, `nicely()`, `on_grid()`, `on_sphere()` and `randomly()` wrap [layout_in_circle()], [layout_nicely()], [layout_on_grid()], +#' [layout_on_sphere()] and [layout_randomly()]. +#' `with_dh()`, `with_fr()`, `with_gem()`, `with_graphopt()`, `with_kk()`, `with_lgl()`, `with_mds()`, +#' `with_sugiyama()` and `with_drl()` wrap [layout_with_dh()], [layout_with_fr()], [layout_with_gem()], [layout_with_graphopt()], +#' [layout_with_kk()], [layout_with_lgl()], [layout_with_mds()], [layout_with_sugiyama()] and [layout_with_drl()]. #' #' @param ... Forwarded to the corresponding `layout_*()` function. #' @return An object of class `igraph_layout_spec`. -#' @seealso [layout_()] and [add_layout_()] to apply a layout specification -#' to a graph. +#' @seealso [layout_()] and [add_layout_()] to apply a layout specification to a graph. #' @family layout specifications #' @keywords graphs #' @rdname layout_spec @@ -830,25 +790,21 @@ as_bipartite <- function(...) layout_spec(layout_as_bipartite, ...) #' Generate coordinates to place the vertices of a graph in a star-shape #' -#' A simple layout generator, that places one vertex in the center of a circle -#' and the rest of the vertices equidistantly on the perimeter. +#' A simple layout generator, that places one vertex in the center of a circle and the rest of the vertices equidistantly on the perimeter. #' -#' It is possible to choose the vertex that will be in the center, and the -#' order of the vertices can be also given. +#' It is possible to choose the vertex that will be in the center, and the order of the vertices can be also given. #' #' @param graph The graph to layout. #' @inheritParams rlang::args_dots_empty -#' @param center The ID of the vertex to put in the center. The default -#' `NULL` uses the first vertex. +#' @param center The ID of the vertex to put in the center. +#' The default `NULL` uses the first vertex. #' @param order Numeric vector, the order of the vertices along the perimeter. #' The default ordering is given by the vertex IDs. -#' @return A matrix with two columns and as many rows as the number of vertices -#' in the input graph. +#' @return A matrix with two columns and as many rows as the number of vertices in the input graph. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso [layout()] and [layout_with_drl()] for other layout -#' algorithms, [plot.igraph()] and [tkplot()] on how to -#' plot graphs and [star()] on how to create ring graphs. See [as_star()] to -#' build a lazy layout specification for [add_layout_()]. +#' @seealso [layout()] and [layout_with_drl()] for other layout algorithms, +#' [plot.igraph()] and [tkplot()] on how to plot graphs and [star()] on how to create ring graphs. +#' See [as_star()] to build a lazy layout specification for [add_layout_()]. #' @keywords graphs #' @export #' @family graph layouts @@ -930,38 +886,35 @@ as_star <- function(...) layout_spec(layout_as_star, ...) #' The Reingold-Tilford graph layout algorithm #' -#' A tree-like layout, it is perfect for trees, acceptable for graphs with not -#' too many cycles. +#' A tree-like layout, it is perfect for trees, acceptable for graphs with not too many cycles. #' -#' Arranges the nodes in a tree where the given node is used as the root. The -#' tree is directed downwards and the parents are centered above its children. +#' Arranges the nodes in a tree where the given node is used as the root. +#' The tree is directed downwards and the parents are centered above its children. #' For the exact algorithm, the reference below. #' -#' If the given graph is not a tree, a breadth-first search is executed first -#' to obtain a possible spanning tree. +#' If the given graph is not a tree, a breadth-first search is executed first to obtain a possible spanning tree. #' #' @param graph The input graph. #' @inheritParams rlang::args_dots_empty -#' @param root The index of the root vertex or root vertices. If this is a -#' non-empty vector then the supplied vertex IDs are used as the roots of the -#' trees (or a single tree if the graph is connected). If it is an empty -#' vector, then the root vertices are automatically calculated based on -#' topological sorting, performed with the opposite mode than the `mode` -#' argument. After the vertices have been sorted, one is selected from each -#' component. -#' @param circular Logical, whether to plot the tree in a circular -#' fashion. Defaults to `FALSE`, so the tree branches are going bottom-up -#' (or top-down, see the `flip.y` argument. -#' @param rootlevel This argument can be useful when drawing forests which are -#' not trees (i.e. they are unconnected and have tree components). It specifies -#' the level of the root vertices for every tree in the forest. It is only -#' considered if the `roots` argument is not an empty vector. -#' @param mode Specifies which edges to consider when building the tree. If it -#' is \sQuote{out}, then only the outgoing, if it is \sQuote{in}, then only the -#' incoming edges of a parent are considered. If it is \sQuote{all} then all -#' edges are used (this was the behavior in igraph 0.5 and before). This -#' parameter also influences how the root vertices are calculated, if they are -#' not given. See the `roots` parameter. +#' @param root The index of the root vertex or root vertices. +#' If this is a non-empty vector then the supplied vertex IDs are used as the roots of the trees +#' (or a single tree if the graph is connected). +#' If it is an empty vector, +#' then the root vertices are automatically calculated based on topological sorting, +#' performed with the opposite mode than the `mode` argument. +#' After the vertices have been sorted, one is selected from each component. +#' @param circular Logical, whether to plot the tree in a circular fashion. +#' Defaults to `FALSE`, so the tree branches are going bottom-up (or top-down, see the `flip.y` argument. +#' @param rootlevel This argument can be useful when drawing forests +#' which are not trees (i.e. they are unconnected and have tree components). +#' It specifies the level of the root vertices for every tree in the forest. +#' It is only considered if the `roots` argument is not an empty vector. +#' @param mode Specifies which edges to consider when building the tree. +#' If it is \sQuote{out}, then only the outgoing, +#' if it is \sQuote{in}, then only the incoming edges of a parent are considered. +#' If it is \sQuote{all} then all edges are used (this was the behavior in igraph 0.5 and before). +#' This parameter also influences how the root vertices are calculated, if they are not given. +#' See the `roots` parameter. #' @param flip.y Logical, whether to flip the \sQuote{y} coordinates. #' The default is flipping because that puts the root vertex on the top. #' @return A numeric matrix with two columns, and one row for each vertex. @@ -969,8 +922,7 @@ as_star <- function(...) layout_spec(layout_as_star, ...) #' \email{csardi.gabor@@gmail.com} #' @references Reingold, E and Tilford, J (1981). Tidier drawing of trees. #' *IEEE Trans. on Softw. Eng.*, SE-7(2):223--228. -#' @seealso [as_tree()] to build a lazy layout specification for -#' [add_layout_()]. +#' @seealso [as_tree()] to build a lazy layout specification for [add_layout_()]. #' @keywords graphs #' @export #' @family graph layouts @@ -1079,8 +1031,7 @@ as_tree <- function(...) layout_spec(layout_as_tree, ...) #' @description #' `r lifecycle::badge("deprecated")` #' -#' `layout.reingold.tilford()` was renamed to [layout_as_tree()] to create a more -#' consistent API. +#' `layout.reingold.tilford()` was renamed to [layout_as_tree()] to create a more consistent API. #' @param ... Passed to the new layout functions. #' @param params Passed to the new layout functions as arguments. #' @keywords internal @@ -1100,18 +1051,15 @@ layout.reingold.tilford <- function(..., params = list()) { #' #' Place vertices on a circle, in the order of their vertex IDs. #' -#' If you want to order the vertices differently, then permute them using the -#' [permute()] function. +#' If you want to order the vertices differently, then permute them using the [permute()] function. #' #' @param graph The input graph. -#' @param order The vertices to place on the circle, in the order of their -#' desired placement. Vertices that are not included here will be placed at -#' (0,0). The default `NULL` selects all vertices, in the order of their -#' IDs. +#' @param order The vertices to place on the circle, in the order of their desired placement. +#' Vertices that are not included here will be placed at (0,0). +#' The default `NULL` selects all vertices, in the order of their IDs. #' @return A numeric matrix with two columns, and one row for each vertex. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso [in_circle()] to build a lazy layout specification for -#' [add_layout_()]. +#' @seealso [in_circle()] to build a lazy layout specification for [add_layout_()]. #' @keywords graphs #' @export #' @family graph layouts @@ -1150,8 +1098,7 @@ in_circle <- function(...) layout_spec(layout_in_circle, ...) #' @description #' `r lifecycle::badge("deprecated")` #' -#' `layout.circle()` was renamed to [layout_in_circle()] to create a more -#' consistent API. +#' `layout.circle()` was renamed to [layout_in_circle()] to create a more consistent API. #' @param ... Passed to the new layout functions. #' @param params Passed to the new layout functions as arguments. #' @keywords internal @@ -1165,12 +1112,11 @@ layout.circle <- function(..., params = list()) { #' Choose an appropriate graph layout algorithm automatically #' -#' This function tries to choose an appropriate graph layout algorithm for the -#' graph, automatically, based on a simple algorithm. See details below. +#' This function tries to choose an appropriate graph layout algorithm for the graph, automatically, based on a simple algorithm. +#' See details below. #' -#' `layout_nicely()` tries to choose an appropriate layout function for the -#' supplied graph, and uses that to generate the layout. The current -#' implementation works like this: +#' `layout_nicely()` tries to choose an appropriate layout function for the supplied graph, and uses that to generate the layout. +#' The current implementation works like this: #' \enumerate{ #' \item If the graph has a graph attribute called \sQuote{layout}, #' then this is used. If this attribute is an R function, then it is called, with the graph and any other extra arguments. @@ -1186,28 +1132,25 @@ layout.circle <- function(..., params = list()) { #' Fruchterman-Reingold layout is used, by calling `layout_with_fr()`. #' \item Otherwise the DrL layout is used, `layout_with_drl()` is called. } #' -#' In layout algorithm implementations, an argument named \sQuote{weights} is -#' typically used to specify the weights of the edges if the layout algorithm -#' supports them. In this case, omitting \sQuote{weights} or setting it to -#' `NULL` will make igraph use the 'weight' edge attribute from the graph -#' if it is present. However, most layout algorithms do not support non-positive -#' weights, so `layout_nicely()` would fail if you simply called it on -#' your graph without specifying explicit weights and the weights happened to -#' include non-positive numbers. We strive to ensure that `layout_nicely()` -#' works out-of-the-box for most graphs, so the rule is that if you omit -#' \sQuote{weights} or set it to `NULL` and `layout_nicely()` would -#' end up calling `layout_with_fr()` or `layout_with_drl()`, we do not -#' forward the weights to these functions and issue a warning about this. You -#' can use `weights = NA` to silence the warning. +#' In layout algorithm implementations, +#' an argument named \sQuote{weights} is typically used to specify the weights of the edges if the layout algorithm supports them. +#' In this case, +#' omitting \sQuote{weights} or setting it to `NULL` will make igraph use the 'weight' edge attribute from the graph if it is present. +#' However, most layout algorithms do not support non-positive weights, +#' so `layout_nicely()` would fail +#' if you simply called it on your graph without specifying explicit weights and the weights happened to include non-positive numbers. +#' We strive to ensure that `layout_nicely()` works out-of-the-box for most graphs, +#' so the rule is that if you omit \sQuote{weights} or set it to `NULL` and `layout_nicely()` would end up calling `layout_with_fr()` or `layout_with_drl()`, +#' we do not forward the weights to these functions and issue a warning about this. +#' You can use `weights = NA` to silence the warning. #' #' @param graph The input graph #' @param dim Dimensions, should be 2 or 3. -#' @param \dots Extra arguments are passed to the real layout function that -#' `layout_nicely()` ends up calling. +#' @param \dots Extra arguments are passed to the real layout function that `layout_nicely()` ends up calling. #' @return A numeric matrix with two or three columns. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso [plot.igraph()]. See [nicely()] to build a lazy layout -#' specification for [add_layout_()]. +#' @seealso [plot.igraph()]. +#' See [nicely()] to build a lazy layout specification for [add_layout_()]. #' @keywords graphs #' @export #' @family graph layouts @@ -1282,27 +1225,25 @@ nicely <- function(...) layout_spec(layout_nicely, ...) #' Simple grid layout #' -#' This layout places vertices on a rectangular grid, in two or three -#' dimensions. +#' This layout places vertices on a rectangular grid, in two or three dimensions. #' -#' The function places the vertices on a simple rectangular grid, one after the -#' other. If you want to change the order of the vertices, then see the -#' [permute()] function. +#' The function places the vertices on a simple rectangular grid, one after the other. +#' If you want to change the order of the vertices, then see the [permute()] function. #' #' @param graph The input graph. #' @inheritParams rlang::args_dots_empty -#' @param width The number of vertices in a single row of the grid. If this is -#' zero or negative, then for 2d layouts the width of the grid will be the -#' square root of the number of vertices in the graph, rounded up to the next -#' integer. Similarly, it will be the cube root for 3d layouts. -#' @param height The number of vertices in a single column of the grid, for -#' three dimensional layouts. If this is zero or negative, then it is -#' determinted automatically. -#' @param dim Two or three. Whether to make 2d or a 3d layout. +#' @param width The number of vertices in a single row of the grid. +#' If this is zero or negative, then for 2d layouts the width of the grid will be the square root of the number of vertices in the graph, +#' rounded up to the next integer. +#' Similarly, it will be the cube root for 3d layouts. +#' @param height The number of vertices in a single column of the grid, for three dimensional layouts. +#' If this is zero or negative, then it is determinted automatically. +#' @param dim Two or three. +#' Whether to make 2d or a 3d layout. #' @return A two-column or three-column matrix. #' @author Tamas Nepusz \email{ntamas@@gmail.com} -#' @seealso [layout()] for other layout generators. See [on_grid()] to build -#' a lazy layout specification for [add_layout_()]. +#' @seealso [layout()] for other layout generators. +#' See [on_grid()] to build a lazy layout specification for [add_layout_()]. #' @keywords graphs #' @export #' @family graph layouts @@ -1396,21 +1337,17 @@ on_grid <- function(...) layout_spec(layout_on_grid, ...) #' Graph layout with vertices on the surface of a sphere #' -#' Place vertices on a sphere, approximately uniformly, in the order of their -#' vertex IDs. +#' Place vertices on a sphere, approximately uniformly, in the order of their vertex IDs. #' -#' `layout_on_sphere()` places the vertices (approximately) uniformly on the -#' surface of a sphere, this is thus a 3d layout. It is not clear however what -#' \dQuote{uniformly on a sphere} means. +#' `layout_on_sphere()` places the vertices (approximately) uniformly on the surface of a sphere, this is thus a 3d layout. +#' It is not clear however what \dQuote{uniformly on a sphere} means. #' -#' If you want to order the vertices differently, then permute them using the -#' [permute()] function. +#' If you want to order the vertices differently, then permute them using the [permute()] function. #' #' @param graph The input graph. #' @return A numeric matrix with three columns, and one row for each vertex. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso [on_sphere()] to build a lazy layout specification for -#' [add_layout_()]. +#' @seealso [on_sphere()] to build a lazy layout specification for [add_layout_()]. #' @keywords graphs #' @export #' @family graph layouts @@ -1430,8 +1367,7 @@ on_sphere <- function(...) layout_spec(layout_on_sphere, ...) #' @description #' `r lifecycle::badge("deprecated")` #' -#' `layout.sphere()` was renamed to [layout_on_sphere()] to create a more -#' consistent API. +#' `layout.sphere()` was renamed to [layout_on_sphere()] to create a more consistent API. #' @param ... Passed to the new layout functions. #' @param params Passed to the new layout functions as arguments. #' @keywords internal @@ -1445,21 +1381,18 @@ layout.sphere <- function(..., params = list()) { #' Randomly place vertices on a plane or in 3d space #' -#' This function uniformly randomly places the vertices of the graph in two or -#' three dimensions. +#' This function uniformly randomly places the vertices of the graph in two or three dimensions. #' -#' Randomly places vertices on a \[-1,1\] square (in 2d) or in a cube (in 3d). It -#' is probably a useless layout, but it can use as a starting point for other -#' layout generators. +#' Randomly places vertices on a \[-1,1\] square (in 2d) or in a cube (in 3d). +#' It is probably a useless layout, but it can use as a starting point for other layout generators. #' #' @param graph The input graph. #' @inheritParams rlang::args_dots_empty -#' @param dim Integer scalar, the dimension of the space to use. It must be 2 -#' or 3. +#' @param dim Integer scalar, the dimension of the space to use. +#' It must be 2 or 3. #' @return A numeric matrix with two or three columns. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso [randomly()] to build a lazy layout specification for -#' [add_layout_()]. +#' @seealso [randomly()] to build a lazy layout specification for [add_layout_()]. #' @keywords graphs #' @export #' @family graph layouts @@ -1526,8 +1459,7 @@ randomly <- function(...) layout_spec(layout_randomly, ...) #' @description #' `r lifecycle::badge("deprecated")` #' -#' `layout.random()` was renamed to [layout_randomly()] to create a more -#' consistent API. +#' `layout.random()` was renamed to [layout_randomly()] to create a more consistent API. #' @param ... Passed to the new layout functions. #' @param params Passed to the new layout functions as arguments. #' @keywords internal @@ -1542,49 +1474,41 @@ layout.random <- function(..., params = list()) { #' The Davidson-Harel layout algorithm #' -#' Place vertices of a graph on the plane, according to the simulated annealing -#' algorithm by Davidson and Harel. +#' Place vertices of a graph on the plane, according to the simulated annealing algorithm by Davidson and Harel. #' -#' This function implements the algorithm by Davidson and Harel, see Ron -#' Davidson, David Harel: Drawing Graphs Nicely Using Simulated Annealing. ACM -#' Transactions on Graphics 15(4), pp. 301-331, 1996. +#' This function implements the algorithm by Davidson and Harel, see Ron Davidson, David Harel: +#' Drawing Graphs Nicely Using Simulated Annealing. +#' ACM Transactions on Graphics 15(4), pp. 301-331, 1996. #' #' The algorithm uses simulated annealing and a sophisticated energy function, -#' which is unfortunately hard to parameterize for different graphs. The -#' original publication did not disclose any parameter values, and the ones -#' below were determined by experimentation. +#' which is unfortunately hard to parameterize for different graphs. +#' The original publication did not disclose any parameter values, and the ones below were determined by experimentation. #' -#' The algorithm consists of two phases, an annealing phase, and a fine-tuning -#' phase. There is no simulated annealing in the second phase. +#' The algorithm consists of two phases, an annealing phase, and a fine-tuning phase. +#' There is no simulated annealing in the second phase. #' -#' Our implementation tries to follow the original publication, as much as -#' possible. The only major difference is that coordinates are explicitly kept -#' within the bounds of the rectangle of the layout. +#' Our implementation tries to follow the original publication, as much as possible. +#' The only major difference is that coordinates are explicitly kept within the bounds of the rectangle of the layout. #' -#' @param graph The graph to lay out. Edge directions are ignored. +#' @param graph The graph to lay out. +#' Edge directions are ignored. #' @inheritParams rlang::args_dots_empty -#' @param coords Optional starting positions for the vertices. If this argument -#' is not `NULL` then it should be an appropriate matrix of starting -#' coordinates. +#' @param coords Optional starting positions for the vertices. +#' If this argument is not `NULL` then it should be an appropriate matrix of starting coordinates. #' @param maxiter Number of iterations to perform in the first phase. -#' @param fineiter Number of iterations in the fine tuning phase. The -#' default `NULL` uses `max(10, log2(vcount(graph)))`. +#' @param fineiter Number of iterations in the fine tuning phase. +#' The default `NULL` uses `max(10, log2(vcount(graph)))`. #' @param cool.fact Cooling factor. -#' @param weight.node.dist Weight for the node-node distances component of the -#' energy function. -#' @param weight.border Weight for the distance from the border component of -#' the energy function. It can be set to zero, if vertices are allowed to sit -#' on the border. -#' @param weight.edge.lengths Weight for the edge length component of the -#' energy function. The default `NULL` uses `edge_density(graph) / 10`. -#' @param weight.edge.crossings Weight for the edge crossing component of the -#' energy function. The default `NULL` uses -#' `1 - sqrt(edge_density(graph))`. -#' @param weight.node.edge.dist Weight for the node-edge distance component of -#' the energy function. The default `NULL` uses -#' `0.2 * (1 - edge_density(graph))`. -#' @return A matrix with two columns, containing the x and y coordinates -#' of the vertices: +#' @param weight.node.dist Weight for the node-node distances component of the energy function. +#' @param weight.border Weight for the distance from the border component of the energy function. +#' It can be set to zero, if vertices are allowed to sit on the border. +#' @param weight.edge.lengths Weight for the edge length component of the energy function. +#' The default `NULL` uses `edge_density(graph) / 10`. +#' @param weight.edge.crossings Weight for the edge crossing component of the energy function. +#' The default `NULL` uses `1 - sqrt(edge_density(graph))`. +#' @param weight.node.edge.dist Weight for the node-edge distance component of the energy function. +#' The default `NULL` uses `0.2 * (1 - edge_density(graph))`. +#' @return A matrix with two columns, containing the x and y coordinates of the vertices: #' \describe{ #' \item{x}{ #' The x-coordinate of the vertex. @@ -1594,9 +1518,8 @@ layout.random <- function(..., params = list()) { #' } #' } #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso [layout_with_fr()], -#' [layout_with_kk()] for other layout algorithms. See [with_dh()] to build a -#' lazy layout specification for [add_layout_()]. +#' @seealso [layout_with_fr()], [layout_with_kk()] for other layout algorithms. +#' See [with_dh()] to build a lazy layout specification for [add_layout_()]. #' @references Ron Davidson, David Harel: Drawing Graphs Nicely Using Simulated #' Annealing. *ACM Transactions on Graphics* 15(4), pp. 301-331, 1996. #' @export @@ -1766,58 +1689,46 @@ with_dh <- function(...) layout_spec(layout_with_dh, ...) #' The Fruchterman-Reingold layout algorithm #' -#' Place vertices on the plane using the force-directed layout algorithm by -#' Fruchterman and Reingold. +#' Place vertices on the plane using the force-directed layout algorithm by Fruchterman and Reingold. #' #' See the referenced paper below for the details of the algorithm. #' #' This function was rewritten from scratch in igraph version 0.8.0. #' -#' @param graph The graph to lay out. Edge directions are ignored. +#' @param graph The graph to lay out. +#' Edge directions are ignored. #' @inheritParams rlang::args_dots_empty -#' @param coords Optional starting positions for the vertices. If this argument -#' is not `NULL` then it should be an appropriate matrix of starting -#' coordinates. -#' @param dim Integer scalar, 2 or 3, the dimension of the layout. Two -#' dimensional layouts are places on a plane, three dimensional ones in the 3d -#' space. +#' @param coords Optional starting positions for the vertices. +#' If this argument is not `NULL` then it should be an appropriate matrix of starting coordinates. +#' @param dim Integer scalar, 2 or 3, the dimension of the layout. +#' Two dimensional layouts are places on a plane, +#' three dimensional ones in the 3d space. #' @param niter Integer scalar, the number of iterations to perform. -#' @param start.temp Real scalar, the start temperature. This is the maximum -#' amount of movement alloved along one axis, within one step, for a vertex. -#' Currently it is decreased linearly to zero during the iteration. The -#' default `NULL` uses `sqrt(vcount(graph))`. -#' @param grid Character scalar, whether to use the faster, but less accurate -#' grid based implementation of the algorithm. By default (\dQuote{auto}), the -#' grid-based implementation is used if the graph has more than one thousand -#' vertices. -#' @param weights A vector giving edge weights. The `weight` edge -#' attribute is used by default, if present. If weights are given, then the -#' attraction along the edges will be multiplied by the given edge weights. -#' This places vertices connected with a highly weighted edge closer to -#' each other. Weights must be positive. -#' @param minx Numeric vector that gives lower boundaries -#' for the \sQuote{x} coordinates of the vertices. +#' @param start.temp Real scalar, the start temperature. +#' This is the maximum amount of movement alloved along one axis, within one step, for a vertex. +#' Currently it is decreased linearly to zero during the iteration. +#' The default `NULL` uses `sqrt(vcount(graph))`. +#' @param grid Character scalar, whether to use the faster, but less accurate grid based implementation of the algorithm. +#' By default (\dQuote{auto}), the grid-based implementation is used if the graph has more than one thousand vertices. +#' @param weights A vector giving edge weights. +#' The `weight` edge attribute is used by default, if present. +#' If weights are given, then the attraction along the edges will be multiplied by the given edge weights. +#' This places vertices connected with a highly weighted edge closer to each other. +#' Weights must be positive. +#' @param minx Numeric vector that gives lower boundaries for the \sQuote{x} coordinates of the vertices. #' The length of the vector must match the number of vertices in the graph. #' Default: `NULL`. #' @param maxx Similar to `minx`, but gives the upper boundaries. -#' @param miny Similar to `minx`, but gives the lower boundaries of the -#' \sQuote{y} coordinates. -#' @param maxy Similar to `minx`, but gives the upper boundaries of the -#' \sQuote{y} coordinates. -#' @param minz Similar to `minx`, but gives the lower boundaries of the -#' \sQuote{z} coordinates. -#' @param maxz Similar to `minx`, but gives the upper boundaries of the -#' \sQuote{z} coordinates. -#' @param coolexp,maxdelta,area,repulserad `r lifecycle::badge("deprecated")` These -#' arguments are not supported from igraph version 0.8.0 and are ignored -#' (with a warning). +#' @param miny Similar to `minx`, but gives the lower boundaries of the \sQuote{y} coordinates. +#' @param maxy Similar to `minx`, but gives the upper boundaries of the \sQuote{y} coordinates. +#' @param minz Similar to `minx`, but gives the lower boundaries of the \sQuote{z} coordinates. +#' @param maxz Similar to `minx`, but gives the upper boundaries of the \sQuote{z} coordinates. +#' @param coolexp,maxdelta,area,repulserad `r lifecycle::badge("deprecated")` These arguments are not supported from igraph version 0.8.0 and are ignored (with a warning). #' @param maxiter A deprecated synonym of `niter`, for compatibility. -#' @return A two- or three-column matrix, each row giving the coordinates of a -#' vertex, according to the IDs of the vertex IDs. +#' @return A two- or three-column matrix, each row giving the coordinates of a vertex, according to the IDs of the vertex IDs. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso [layout_with_drl()], [layout_with_kk()] for -#' other layout algorithms. See [with_fr()] to build a lazy layout -#' specification for [add_layout_()]. +#' @seealso [layout_with_drl()], [layout_with_kk()] for other layout algorithms. +#' See [with_fr()] to build a lazy layout specification for [add_layout_()]. #' @references Fruchterman, T.M.J. and Reingold, E.M. (1991). Graph Drawing by #' Force-directed Placement. *Software - Practice and Experience*, #' 21(11):1129-1164. @@ -2042,8 +1953,7 @@ with_fr <- function(...) layout_spec(layout_with_fr, ...) #' @description #' `r lifecycle::badge("deprecated")` #' -#' `layout.fruchterman.reingold()` was renamed to [layout_with_fr()] to create a more -#' consistent API. +#' `layout.fruchterman.reingold()` was renamed to [layout_with_fr()] to create a more consistent API. #' @param ... Passed to the new layout functions. #' @param params Passed to the new layout functions as arguments. #' @keywords internal @@ -2065,28 +1975,26 @@ layout.fruchterman.reingold <- function(..., params = list()) { #' #' See the referenced paper below for the details of the algorithm. #' -#' @param graph The input graph. Edge directions are ignored. +#' @param graph The input graph. +#' Edge directions are ignored. #' @inheritParams rlang::args_dots_empty #' @param coords Starting coordinates in a two or three column matrix, #' depending on the `dim` argument. #' Default: `NULL`. -#' @param maxiter The maximum number of iterations to perform. Updating a -#' single vertex counts as an iteration. The default `NULL` uses 40 * n * n, -#' where n is the number of vertices. The original paper suggests 4 * n * n, -#' but this usually only works if the other parameters are set up carefully. -#' @param temp.max The maximum allowed local temperature. The default `NULL` -#' uses the number of vertices. -#' @param temp.min The global temperature at which the algorithm terminates -#' (even before reaching `maxiter` iterations). A reasonable default is -#' 1/10. -#' @param temp.init Initial local temperature of all vertices. The default -#' `NULL` uses the square root of the number of vertices. -#' @return A numeric matrix with two columns, and as many rows as the number of -#' vertices. +#' @param maxiter The maximum number of iterations to perform. +#' Updating a single vertex counts as an iteration. +#' The default `NULL` uses 40 * n * n, where n is the number of vertices. +#' The original paper suggests 4 * n * n, but this usually only works if the other parameters are set up carefully. +#' @param temp.max The maximum allowed local temperature. +#' The default `NULL` uses the number of vertices. +#' @param temp.min The global temperature at which the algorithm terminates (even before reaching `maxiter` iterations). +#' A reasonable default is 1/10. +#' @param temp.init Initial local temperature of all vertices. +#' The default `NULL` uses the square root of the number of vertices. +#' @return A numeric matrix with two columns, and as many rows as the number of vertices. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso [layout_with_fr()], -#' [plot.igraph()], [tkplot()]. See [with_gem()] to build a lazy layout -#' specification for [add_layout_()]. +#' @seealso [layout_with_fr()], [plot.igraph()], [tkplot()]. +#' See [with_gem()] to build a lazy layout specification for [add_layout_()]. #' @references Arne Frick, Andreas Ludwig, Heiko Mehldau: A Fast Adaptive #' Layout Algorithm for Undirected Graphs, *Proc. Graph Drawing 1994*, #' LNCS 894, pp. 388-403, 1995. @@ -2191,44 +2099,36 @@ with_gem <- function(...) layout_spec(layout_with_gem, ...) #' The graphopt layout algorithm #' -#' A force-directed layout algorithm, that scales relatively well to large -#' graphs. +#' A force-directed layout algorithm, that scales relatively well to large graphs. #' -#' `layout_with_graphopt()` is a port of the graphopt layout algorithm by Michael -#' Schmuhl. graphopt version 0.4.1 was rewritten in C and the support for -#' layers was removed (might be added later) and a code was a bit reorganized -#' to avoid some unnecessary steps is the node charge (see below) is zero. +#' `layout_with_graphopt()` is a port of the graphopt layout algorithm by Michael Schmuhl. graphopt version 0.4.1 was rewritten in C and the support for layers was removed (might be added later) and a code was a bit reorganized to avoid some unnecessary steps is the node charge (see below) is zero. #' -#' graphopt uses physical analogies for defining attracting and repelling -#' forces among the vertices and then the physical system is simulated until it -#' reaches an equilibrium. (There is no simulated annealing or anything like -#' that, so a stable fixed point is not guaranteed.) +#' graphopt uses physical analogies for defining attracting and repelling forces among the vertices and then the physical system is simulated until it reaches an equilibrium. +#' (There is no simulated annealing or anything like that, so a stable fixed point is not guaranteed.) #' #' @param graph The input graph. #' @inheritParams rlang::args_dots_empty -#' @param start If given, then it should be a matrix with two columns and one -#' line for each vertex. This matrix will be used as starting positions for the -#' algorithm. If not given, then a random starting matrix is used. -#' @param niter Integer scalar, the number of iterations to perform. Should be -#' a couple of hundred in general. If you have a large graph then you might -#' want to only do a few iterations and then check the result. If it is not -#' good enough you can feed it in again in the `start` argument. The -#' default value is 500. -#' @param charge The charge of the vertices, used to calculate electric -#' repulsion. The default is 0.001. -#' @param mass The mass of the vertices, used for the spring forces. The -#' default is 30. -#' @param spring.length The length of the springs, an integer number. The -#' default value is zero. +#' @param start If given, then it should be a matrix with two columns and one line for each vertex. +#' This matrix will be used as starting positions for the algorithm. +#' If not given, then a random starting matrix is used. +#' @param niter Integer scalar, the number of iterations to perform. +#' Should be a couple of hundred in general. +#' If you have a large graph then you might want to only do a few iterations and then check the result. +#' If it is not good enough you can feed it in again in the `start` argument. +#' The default value is 500. +#' @param charge The charge of the vertices, used to calculate electric repulsion. +#' The default is 0.001. +#' @param mass The mass of the vertices, used for the spring forces. +#' The default is 30. +#' @param spring.length The length of the springs, an integer number. +#' The default value is zero. #' @param spring.constant The spring constant, the default value is one. -#' @param max.sa.movement Real constant, it gives the maximum amount of -#' movement allowed in a single step along a single axis. The default value is -#' 5. +#' @param max.sa.movement Real constant, it gives the maximum amount of movement allowed in a single step along a single axis. +#' The default value is 5. #' @return A numeric matrix with two columns, and a row for each vertex. #' @author Michael Schmuhl for the original graphopt code, rewritten and #' wrapped by Gabor Csardi \email{csardi.gabor@@gmail.com}. -#' @seealso [with_graphopt()] to build a lazy layout specification for -#' [add_layout_()]. +#' @seealso [with_graphopt()] to build a lazy layout specification for [add_layout_()]. #' @keywords graphs #' @export #' @family graph layouts @@ -2325,57 +2225,46 @@ with_graphopt <- function(...) layout_spec(layout_with_graphopt, ...) #' The Kamada-Kawai layout algorithm #' -#' Place the vertices on the plane, or in 3D space, based on a physical -#' model of springs. +#' Place the vertices on the plane, or in 3D space, based on a physical model of springs. #' #' See the referenced paper below for the details of the algorithm. #' -#' This function was rewritten from scratch in igraph version 0.8.0 and it -#' follows truthfully the original publication by Kamada and Kawai now. +#' This function was rewritten from scratch in igraph version 0.8.0 and it follows truthfully the original publication by Kamada and Kawai now. #' -#' @param graph The input graph. Edge directions are ignored. +#' @param graph The input graph. +#' Edge directions are ignored. #' @inheritParams rlang::args_dots_empty #' @param coords Starting coordinates in a two or three column matrix, #' depending on the `dim` argument. #' Default: `NULL`. -#' @param dim Integer scalar, 2 or 3, the dimension of the layout. Two -#' dimensional layouts are places on a plane, three dimensional ones in the 3d -#' space. -#' @param maxiter The maximum number of iterations to perform. The algorithm -#' might terminate earlier, see the `epsilon` argument. The default `NULL` -#' uses `50 * vcount(graph)`. -#' @param epsilon Numeric scalar, the algorithm terminates, if the maximal -#' delta is less than this. (See the reference below for what delta means.) If -#' you set this to zero, then the function always performs `maxiter` -#' iterations. +#' @param dim Integer scalar, 2 or 3, the dimension of the layout. +#' Two dimensional layouts are places on a plane, +#' three dimensional ones in the 3d space. +#' @param maxiter The maximum number of iterations to perform. +#' The algorithm might terminate earlier, see the `epsilon` argument. +#' The default `NULL` uses `50 * vcount(graph)`. +#' @param epsilon Numeric scalar, the algorithm terminates, if the maximal delta is less than this. +#' (See the reference below for what delta means.) If you set this to zero, then the function always performs `maxiter` iterations. #' @param kkconst Numeric scalar, the Kamada-Kawai vertex attraction constant. #' The default `NULL` uses the number of vertices. #' @param weights Edge weights, larger values will result in longer edges. -#' Note that this is the opposite of [layout_with_fr()], which produces -#' shorter edges for larger weights. Weights must be positive. -#' @param minx Numeric vector that gives lower boundaries -#' for the \sQuote{x} coordinates of the vertices. +#' Note that this is the opposite of [layout_with_fr()], which produces shorter edges for larger weights. +#' Weights must be positive. +#' @param minx Numeric vector that gives lower boundaries for the \sQuote{x} coordinates of the vertices. #' The length of the vector must match the number of vertices in the graph. #' Default: `NULL`. #' @param maxx Similar to `minx`, but gives the upper boundaries. -#' @param miny Similar to `minx`, but gives the lower boundaries of the -#' \sQuote{y} coordinates. -#' @param maxy Similar to `minx`, but gives the upper boundaries of the -#' \sQuote{y} coordinates. -#' @param minz Similar to `minx`, but gives the lower boundaries of the -#' \sQuote{z} coordinates. -#' @param maxz Similar to `minx`, but gives the upper boundaries of the -#' \sQuote{z} coordinates. -#' @param niter,sigma,initemp,coolexp `r lifecycle::badge("deprecated")` These -#' arguments are not supported from igraph version 0.8.0 and are ignored (with a warning). +#' @param miny Similar to `minx`, but gives the lower boundaries of the \sQuote{y} coordinates. +#' @param maxy Similar to `minx`, but gives the upper boundaries of the \sQuote{y} coordinates. +#' @param minz Similar to `minx`, but gives the lower boundaries of the \sQuote{z} coordinates. +#' @param maxz Similar to `minx`, but gives the upper boundaries of the \sQuote{z} coordinates. +#' @param niter,sigma,initemp,coolexp `r lifecycle::badge("deprecated")` These arguments are not supported from igraph version 0.8.0 and are ignored (with a warning). #' @param start Deprecated synonym for `coords`, for compatibility. -#' @return A numeric matrix with two (dim=2) or three (dim=3) columns, and as -#' many rows as the number of vertices, the x, y and potentially z coordinates -#' of the vertices. +#' @return A numeric matrix with two (dim=2) or three (dim=3) columns, and as many rows as the number of vertices, the x, +#' y and potentially z coordinates of the vertices. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso [layout_with_drl()], [plot.igraph()], -#' [tkplot()]. See [with_kk()] to build a lazy layout specification for -#' [add_layout_()]. +#' @seealso [layout_with_drl()], [plot.igraph()], [tkplot()]. +#' See [with_kk()] to build a lazy layout specification for [add_layout_()]. #' @references Kamada, T. and Kawai, S.: An Algorithm for Drawing General #' Undirected Graphs. *Information Processing Letters*, 31/1, 7--15, 1989. #' @export @@ -2588,8 +2477,7 @@ with_kk <- function(...) layout_spec(layout_with_kk, ...) #' @description #' `r lifecycle::badge("deprecated")` #' -#' `layout.kamada.kawai()` was renamed to [layout_with_kk()] to create a more -#' consistent API. +#' `layout.kamada.kawai()` was renamed to [layout_with_kk()] to create a more consistent API. #' @param ... Passed to the new layout functions. #' @param params Passed to the new layout functions as arguments. #' @keywords internal @@ -2609,30 +2497,27 @@ layout.kamada.kawai <- function(..., params = list()) { #' #' A layout generator for larger graphs. #' -#' `layout_with_lgl()` is for large connected graphs, it is similar to the layout -#' generator of the Large Graph Layout software -#' (). +#' `layout_with_lgl()` is for large connected graphs, +#' it is similar to the layout generator of the Large Graph Layout software (). #' #' @param graph The input graph #' @inheritParams rlang::args_dots_empty #' @param maxiter The maximum number of iterations to perform (150). -#' @param maxdelta The maximum change for a vertex during an iteration. The -#' default `NULL` uses the number of vertices. -#' @param area The area of the surface on which the vertices are placed. The -#' default `NULL` uses the square of the number of vertices. +#' @param maxdelta The maximum change for a vertex during an iteration. +#' The default `NULL` uses the number of vertices. +#' @param area The area of the surface on which the vertices are placed. +#' The default `NULL` uses the square of the number of vertices. #' @param coolexp The cooling exponent of the simulated annealing (1.5). -#' @param repulserad Cancellation radius for the repulsion. The default -#' `NULL` uses the `area` times the number of vertices. -#' @param cellsize The size of the cells for the grid. When calculating the -#' repulsion forces between vertices only vertices in the same or neighboring -#' grid cells are taken into account. The default `NULL` uses the square -#' root of the square root of the `area`. -#' @param root The ID of the vertex to place at the middle of the layout. The -#' default value is -1 which means that a random vertex is selected. +#' @param repulserad Cancellation radius for the repulsion. +#' The default `NULL` uses the `area` times the number of vertices. +#' @param cellsize The size of the cells for the grid. +#' When calculating the repulsion forces between vertices only vertices in the same or neighboring grid cells are taken into account. +#' The default `NULL` uses the square root of the square root of the `area`. +#' @param root The ID of the vertex to place at the middle of the layout. +#' The default value is -1 which means that a random vertex is selected. #' @return A numeric matrix with two columns and as many rows as vertices. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso [with_lgl()] to build a lazy layout specification for -#' [add_layout_()]. +#' @seealso [with_lgl()] to build a lazy layout specification for [add_layout_()]. #' @keywords graphs #' @export #' @family graph layouts @@ -2739,8 +2624,7 @@ with_lgl <- function(...) layout_spec(layout_with_lgl, ...) #' @description #' `r lifecycle::badge("deprecated")` #' -#' `layout.lgl()` was renamed to [layout_with_lgl()] to create a more -#' consistent API. +#' `layout.lgl()` was renamed to [layout_with_lgl()] to create a more consistent API. #' @param ... Passed to the new layout functions. #' @param params Passed to the new layout functions as arguments. #' @keywords internal @@ -2754,39 +2638,34 @@ layout.lgl <- function(..., params = list()) { #' Graph layout by multidimensional scaling #' -#' Multidimensional scaling of some distance matrix defined on the vertices of -#' a graph. +#' Multidimensional scaling of some distance matrix defined on the vertices of a graph. #' -#' `layout_with_mds()` uses classical multidimensional scaling (Torgerson scaling) -#' for generating the coordinates. Multidimensional scaling aims to place points -#' from a higher dimensional space in a (typically) 2 dimensional plane, so that -#' the distances between the points are kept as much as this is possible. +#' `layout_with_mds()` uses classical multidimensional scaling (Torgerson scaling) for generating the coordinates. +#' Multidimensional scaling aims to place points from a higher dimensional space in a (typically) 2 dimensional plane, +#' so that the distances between the points are kept as much as this is possible. #' -#' By default igraph uses the shortest path matrix as the distances between the -#' nodes, but the user can override this via the `dist` argument. +#' By default igraph uses the shortest path matrix as the distances between the nodes, +#' but the user can override this via the `dist` argument. #' -#' Warning: If the graph is symmetric to the exchange of two vertices (as is the -#' case with leaves of a tree connecting to the same parent), classical -#' multidimensional scaling may assign the same coordinates to these vertices. +#' Warning: If the graph is symmetric to the exchange of two vertices (as is the case with leaves of a tree connecting to the same parent), +#' classical multidimensional scaling may assign the same coordinates to these vertices. #' -#' This function generates the layout separately for each graph component and -#' then merges them via [merge_coords()]. +#' This function generates the layout separately for each graph component and then merges them via [merge_coords()]. #' #' @param graph The input graph. -#' @param dist The distance matrix for the multidimensional scaling. If -#' `NULL` (the default), then the unweighted shortest path matrix is used. -#' @param dim `layout_with_mds()` supports dimensions up to the number of nodes -#' minus one, but only if the graph is connected; for unconnected graphs, the -#' only possible value is 2. This is because `merge_coords()` only works in -#' 2D. -#' @param options `r lifecycle::badge("deprecated")` This argument is not -#' supported from igraph version 1.6.0, as ARPACK is not used any more for -#' solving the eigenproblem. Supplying it raises an error. +#' @param dist The distance matrix for the multidimensional scaling. +#' If `NULL` (the default), +#' then the unweighted shortest path matrix is used. +#' @param dim `layout_with_mds()` supports dimensions up to the number of nodes minus one, but only if the graph is connected; +#' for unconnected graphs, the only possible value is 2. This is because `merge_coords()` only works in 2D. +#' @param options `r lifecycle::badge("deprecated")` This argument is not supported from igraph version 1.6.0, +#' as ARPACK is not used any more for solving the eigenproblem. +#' Supplying it raises an error. #' @return A numeric matrix with `dim` columns. #' @author Tamas Nepusz \email{ntamas@@gmail.com} and Gabor Csardi #' \email{csardi.gabor@@gmail.com} -#' @seealso [layout()], [plot.igraph()]. See [with_mds()] to build a lazy -#' layout specification for [add_layout_()]. +#' @seealso [layout()], [plot.igraph()]. +#' See [with_mds()] to build a lazy layout specification for [add_layout_()]. #' @references Cox, T. F. and Cox, M. A. A. (2001) *Multidimensional #' Scaling*. Second edition. Chapman and Hall. #' @export @@ -2824,26 +2703,21 @@ with_mds <- function(...) layout_spec(layout_with_mds, ...) #' The Sugiyama graph layout generator #' -#' Sugiyama layout algorithm for layered directed acyclic graphs. The algorithm -#' minimized edge crossings. +#' Sugiyama layout algorithm for layered directed acyclic graphs. +#' The algorithm minimized edge crossings. #' -#' This layout algorithm is designed for directed acyclic graphs where each -#' vertex is assigned to a layer. Layers are indexed from zero, and vertices of -#' the same layer will be placed on the same horizontal line. The X coordinates -#' of vertices within each layer are decided by the heuristic proposed by -#' Sugiyama et al. to minimize edge crossings. +#' This layout algorithm is designed for directed acyclic graphs where each vertex is assigned to a layer. +#' Layers are indexed from zero, and vertices of the same layer will be placed on the same horizontal line. +#' The X coordinates of vertices within each layer are decided by the heuristic proposed by Sugiyama et al. to minimize edge crossings. #' -#' You can also try to lay out undirected graphs, graphs containing cycles, or -#' graphs without an a priori layered assignment with this algorithm. igraph -#' will try to eliminate cycles and assign vertices to layers, but there is no -#' guarantee on the quality of the layout in such cases. +#' You can also try to lay out undirected graphs, graphs containing cycles, +#' or graphs without an a priori layered assignment with this algorithm. igraph will try to eliminate cycles and assign vertices to layers, +#' but there is no guarantee on the quality of the layout in such cases. #' -#' The Sugiyama layout may introduce \dQuote{bends} on the edges in order to -#' obtain a visually more pleasing layout. This is achieved by adding dummy -#' nodes to edges spanning more than one layer. The resulting layout assigns -#' coordinates not only to the nodes of the original graph but also to the -#' dummy nodes. The layout algorithm will also return the extended graph with -#' the dummy nodes. +#' The Sugiyama layout may introduce \dQuote{bends} on the edges in order to obtain a visually more pleasing layout. +#' This is achieved by adding dummy nodes to edges spanning more than one layer. +#' The resulting layout assigns coordinates not only to the nodes of the original graph but also to the dummy nodes. +#' The layout algorithm will also return the extended graph with the dummy nodes. #' #' For more details, see the reference below. #' @@ -2852,23 +2726,18 @@ with_mds <- function(...) layout_spec(layout_with_mds, ...) #' @param layers A numeric vector of the layer indices of the vertices. #' Layers are numbered from one. #' Default: `NULL`, igraph calculates the layers automatically. -#' @param hgap Real scalar, the minimum horizontal gap between vertices in the -#' same layer. +#' @param hgap Real scalar, the minimum horizontal gap between vertices in the same layer. #' @param vgap Real scalar, the distance between layers. -#' @param maxiter Integer scalar, the maximum number of iterations in the -#' crossing minimization stage. 100 is a reasonable default; if you feel that -#' you have too many edge crossings, increase this. -#' @param weights Optional edge weight vector. If `NULL`, then the -#' 'weight' edge attribute is used, if there is one. Supply `NA` here and -#' igraph ignores the edge weights. These are used only if the graph -#' contains cycles; igraph will tend to reverse edges with smaller weights -#' when breaking the cycles. -#' @param attributes Which graph/vertex/edge attributes to keep in the extended -#' graph. \sQuote{default} keeps the \sQuote{size}, \sQuote{size2}, -#' \sQuote{shape}, \sQuote{label} and \sQuote{color} vertex attributes and the -#' \sQuote{arrow.mode} and \sQuote{arrow.size} edge attributes. \sQuote{all} -#' keep all graph, vertex and edge attributes, \sQuote{none} keeps none of -#' them. +#' @param maxiter Integer scalar, the maximum number of iterations in the crossing minimization stage. +#' 100 is a reasonable default; if you feel that you have too many edge crossings, increase this. +#' @param weights Optional edge weight vector. +#' If `NULL`, then the 'weight' edge attribute is used, if there is one. +#' Supply `NA` here and igraph ignores the edge weights. +#' These are used only if the graph contains cycles; igraph will tend to reverse edges with smaller weights when breaking the cycles. +#' @param attributes Which graph/vertex/edge attributes to keep in the extended graph. +#' \sQuote{default} keeps the \sQuote{size}, \sQuote{size2}, \sQuote{shape}, +#' \sQuote{label} and \sQuote{color} vertex attributes and the \sQuote{arrow.mode} and \sQuote{arrow.size} edge attributes. +#' \sQuote{all} keep all graph, vertex and edge attributes, \sQuote{none} keeps none of them. #' @return A list with the components: #' \describe{ #' \item{layout}{ @@ -2886,8 +2755,7 @@ with_mds <- function(...) layout_spec(layout_with_mds, ...) #' } #' } #' @author Tamas Nepusz \email{ntamas@@gmail.com} -#' @seealso [with_sugiyama()] to build a lazy layout specification for -#' [add_layout_()]. +#' @seealso [with_sugiyama()] to build a lazy layout specification for [add_layout_()]. #' @references K. Sugiyama, S. Tagawa and M. Toda, "Methods for Visual #' Understanding of Hierarchical Systems". IEEE Transactions on Systems, Man #' and Cybernetics 11(2):109-125, 1981. @@ -3213,35 +3081,26 @@ with_sugiyama <- function(...) layout_spec(layout_with_sugiyama, ...) #' #' Place several graphs on the same layout #' -#' `merge_coords()` takes a list of graphs and a list of coordinates and -#' places the graphs in a common layout. The method to use is chosen via the -#' `method` parameter, although right now only the `dla` method is -#' implemented. +#' `merge_coords()` takes a list of graphs and a list of coordinates and places the graphs in a common layout. +#' The method to use is chosen via the `method` parameter, although right now only the `dla` method is implemented. #' -#' The `dla` method covers the graph with circles. Then it sorts the -#' graphs based on the number of vertices first and places the largest graph at -#' the center of the layout. Then the other graphs are placed in decreasing -#' order via a DLA (diffision limited aggregation) algorithm: the graph is -#' placed randomly on a circle far away from the center and a random walk is -#' conducted until the graph walks into the larger graphs already placed or -#' walks too far from the center of the layout. +#' The `dla` method covers the graph with circles. +#' Then it sorts the graphs based on the number of vertices first and places the largest graph at the center of the layout. +#' Then the other graphs are placed in decreasing order via a DLA (diffision limited aggregation) algorithm: +#' the graph is placed randomly on a circle far away from the center and a random walk is conducted until the graph walks into the larger graphs already placed or walks too far from the center of the layout. #' -#' The `layout_components()` function disassembles the graph first into -#' maximal connected components and calls the supplied `layout` function -#' for each component separately. Finally it merges the layouts via calling -#' `merge_coords()`. +#' The `layout_components()` function disassembles the graph first into maximal connected components and calls the supplied `layout` function for each component separately. +#' Finally it merges the layouts via calling `merge_coords()`. #' #' @param graphs A list of graph objects. #' @param layouts A list of two-column matrices. -#' @param method Character constant giving the method to use. Right now only -#' `dla` is implemented. -#' @param layout A function object, the layout function to use. The default -#' `NULL` uses `layout_with_kk`. -#' @param \dots For `layout_components()`, additional arguments to pass to -#' the `layout` layout function. For `merge_coords()`, these dots must be -#' empty. -#' @return A matrix with two columns and as many lines as the total number of -#' vertices in the graphs. +#' @param method Character constant giving the method to use. +#' Right now only `dla` is implemented. +#' @param layout A function object, the layout function to use. +#' The default `NULL` uses `layout_with_kk`. +#' @param \dots For `layout_components()`, additional arguments to pass to the `layout` layout function. +#' For `merge_coords()`, these dots must be empty. +#' @return A matrix with two columns and as many lines as the total number of vertices in the graphs. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @seealso [plot.igraph()], [tkplot()], #' [layout()], [disjoint_union()] @@ -3318,18 +3177,16 @@ merge_coords <- function( #' #' Rescale coordinates linearly to be within given bounds. #' -#' `norm_coords()` normalizes a layout, it linearly transforms each -#' coordinate separately to fit into the given limits. +#' `norm_coords()` normalizes a layout, it linearly transforms each coordinate separately to fit into the given limits. #' #' @param layout A matrix with two or three columns, the layout to normalize. #' @inheritParams rlang::args_dots_empty -#' @param xmin,xmax The limits for the first coordinate, if one of them or both -#' are `NULL` then no normalization is performed along this direction. -#' @param ymin,ymax The limits for the second coordinate, if one of them or -#' both are `NULL` then no normalization is performed along this -#' direction. -#' @param zmin,zmax The limits for the third coordinate, if one of them or both -#' are `NULL` then no normalization is performed along this direction. +#' @param xmin,xmax The limits for the first coordinate, +#' if one of them or both are `NULL` then no normalization is performed along this direction. +#' @param ymin,ymax The limits for the second coordinate, +#' if one of them or both are `NULL` then no normalization is performed along this direction. +#' @param zmin,zmax The limits for the third coordinate, +#' if one of them or both are `NULL` then no normalization is performed along this direction. #' @return A numeric matrix with at the same dimension as `layout`. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @export @@ -3515,8 +3372,7 @@ layout.fruchterman.reingold.grid <- function(graph, ...) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `layout.drl()` was renamed to [layout_with_drl()] to create a more -#' consistent API. +#' `layout.drl()` was renamed to [layout_with_drl()] to create a more consistent API. #' @inheritParams layout_with_drl #' @keywords internal #' @export @@ -3542,16 +3398,17 @@ layout.drl <- function( #' The DrL graph layout generator #' -#' DrL is a force-directed graph layout toolbox focused on real-world -#' large-scale graphs, developed by Shawn Martin and colleagues at Sandia -#' National Laboratories. +#' DrL is a force-directed graph layout toolbox focused on real-world large-scale graphs, +#' developed by Shawn Martin and colleagues at Sandia National Laboratories. #' #' This function implements the force-directed DrL layout generator. #' #' The generator has the following parameters: #' \describe{ #' \item{edge.cut}{ -#' Edge cutting is done in the late stages of the algorithm in order to achieve less dense layouts. Edges are cut if there is a lot of stress on them (a large value in the objective function sum). The edge cutting parameter is a value between 0 and 1 with 0 representing no edge cutting and 1 representing maximal edge cutting. +#' Edge cutting is done in the late stages of the algorithm in order to achieve less dense layouts. +#' Edges are cut if there is a lot of stress on them (a large value in the objective function sum). +#' The edge cutting parameter is a value between 0 and 1 with 0 representing no edge cutting and 1 representing maximal edge cutting. #' } #' \item{init.iterations}{ #' Number of iterations in the first phase. @@ -3627,39 +3484,34 @@ layout.drl <- function( #' } #' } #' -#' There are five pre-defined parameter settings as well, these are called -#' `drl_defaults$default`, `drl_defaults$coarsen`, -#' `drl_defaults$coarsest`, `drl_defaults$refine` and -#' `drl_defaults$final`. +#' There are five pre-defined parameter settings as well, these are called `drl_defaults$default`, `drl_defaults$coarsen`, +#' `drl_defaults$coarsest`, `drl_defaults$refine` and `drl_defaults$final`. #' #' @aliases drl_defaults igraph.drl.coarsen #' @aliases igraph.drl.coarsest igraph.drl.default igraph.drl.final igraph.drl.refine #' @param graph The input graph, in can be directed or undirected. #' @inheritParams rlang::args_dots_empty -#' @param use.seed Logical, whether to use the coordinates given in the -#' `seed` argument as a starting point. -#' @param seed A matrix with two columns, the starting coordinates for the -#' vertices is `use.seed` is `TRUE`. It is ignored otherwise. The default -#' `NULL` draws uniformly random starting coordinates. -#' @param options Options for the layout generator, a named list. See details -#' below. The default `NULL` uses `drl_defaults$default`. -#' @param weights The weights of the edges. It must be a positive numeric vector, -#' `NULL` or `NA`. If it is `NULL` and the input graph has a -#' \sQuote{weight} edge attribute, then that attribute will be used. If -#' `NULL` and no such attribute is present, then the edges will have equal -#' weights. Set this to `NA` if the graph was a \sQuote{weight} edge -#' attribute, but you don't want to use it for the layout. Larger edge weights -#' correspond to stronger connections. -#' @param dim Either \sQuote{2} or \sQuote{3}, it specifies whether we want a -#' two dimensional or a three dimensional layout. Note that because of the -#' nature of the DrL algorithm, the three dimensional layout takes -#' significantly longer to compute. +#' @param use.seed Logical, whether to use the coordinates given in the `seed` argument as a starting point. +#' @param seed A matrix with two columns, the starting coordinates for the vertices is `use.seed` is `TRUE`. +#' It is ignored otherwise. +#' The default `NULL` draws uniformly random starting coordinates. +#' @param options Options for the layout generator, a named list. +#' See details below. +#' The default `NULL` uses `drl_defaults$default`. +#' @param weights The weights of the edges. +#' It must be a positive numeric vector, `NULL` or `NA`. +#' If it is `NULL` and the input graph has a \sQuote{weight} edge attribute, then that attribute will be used. +#' If `NULL` and no such attribute is present, then the edges will have equal weights. +#' Set this to `NA` if the graph was a \sQuote{weight} edge attribute, but you don't want to use it for the layout. +#' Larger edge weights correspond to stronger connections. +#' @param dim Either \sQuote{2} or \sQuote{3}, it specifies whether we want a two dimensional or a three dimensional layout. +#' Note that because of the nature of the DrL algorithm, the three dimensional layout takes significantly longer to compute. #' @return A numeric matrix with two columns. #' @author Shawn Martin () #' and Gabor Csardi \email{csardi.gabor@@gmail.com} for the R/igraph interface #' and the three dimensional version. -#' @seealso [layout()] for other layout generators. See [with_drl()] to -#' build a lazy layout specification for [add_layout_()]. +#' @seealso [layout()] for other layout generators. +#' See [with_drl()] to build a lazy layout specification for [add_layout_()]. #' @references See the following technical report: Martin, S., Brown, W.M., #' Klavans, R., Boyack, K.W., DrL: Distributed Recursive (Graph) Layout. SAND #' Reports, 2008. 2936: p. 1-10. @@ -3939,10 +3791,8 @@ drl_defaults <- list( refine = igraph.drl.refine ) -#' Align a vertex layout -#' This function centers a vertex layout on the coordinate system origin and -#' rotates the layout to achieve a visually pleasing alignment with the coordinate -#' axes. Doing this is particularly useful with force-directed layouts such as [layout_with_fr()]. +#' Align a vertex layout This function centers a vertex layout on the coordinate system origin and rotates the layout to achieve a visually pleasing alignment with the coordinate axes. +#' Doing this is particularly useful with force-directed layouts such as [layout_with_fr()]. #' @param graph The graph whose layout is to be aligned. #' @param layout A matrix whose rows are the coordinates of vertices. #' @return modified layout matrix diff --git a/R/make.R b/R/make.R index ec1f8fd6487..c9151a86b34 100644 --- a/R/make.R +++ b/R/make.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph()` was renamed to [make_graph()] to create a more -#' consistent API. +#' `graph()` was renamed to [make_graph()] to create a more consistent API. #' @inheritParams make_graph #' @keywords internal #' @export @@ -128,8 +127,7 @@ graph <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.famous()` was renamed to [make_graph()] to create a more -#' consistent API. +#' `graph.famous()` was renamed to [make_graph()] to create a more consistent API. #' @inheritParams make_graph #' @keywords internal #' @export @@ -253,8 +251,7 @@ graph.famous <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `line.graph()` was renamed to [make_line_graph()] to create a more -#' consistent API. +#' `line.graph()` was renamed to [make_line_graph()] to create a more consistent API. #' @inheritParams make_line_graph #' @keywords internal #' @export @@ -277,8 +274,7 @@ line.graph <- function(graph) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.ring()` was renamed to [make_ring()] to create a more -#' consistent API. +#' `graph.ring()` was renamed to [make_ring()] to create a more consistent API. #' @inheritParams make_ring #' @keywords internal #' @export @@ -304,8 +300,7 @@ graph.ring <- function(n, directed = FALSE, mutual = FALSE, circular = TRUE) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.tree()` was renamed to [make_tree()] to create a more -#' consistent API. +#' `graph.tree()` was renamed to [make_tree()] to create a more consistent API. #' @inheritParams make_tree #' @keywords internal #' @export @@ -332,8 +327,7 @@ graph.tree <- function(n, children = 2, mode = c("out", "in", "undirected")) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.star()` was renamed to [make_star()] to create a more -#' consistent API. +#' `graph.star()` was renamed to [make_star()] to create a more consistent API. #' @inheritParams make_star #' @keywords internal #' @export @@ -364,8 +358,7 @@ graph.star <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.lcf()` was renamed to [graph_from_lcf()] to create a more -#' consistent API. +#' `graph.lcf()` was renamed to [graph_from_lcf()] to create a more consistent API. #' @inheritParams graph_from_lcf #' @keywords internal #' @export @@ -385,8 +378,7 @@ graph.lcf <- function(n, shifts, repeats = 1) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.lattice()` was renamed to [make_lattice()] to create a more -#' consistent API. +#' `graph.lattice()` was renamed to [make_lattice()] to create a more consistent API. #' @inheritParams make_lattice #' @keywords internal #' @export @@ -452,8 +444,7 @@ graph.lattice <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.kautz()` was renamed to [make_kautz_graph()] to create a more -#' consistent API. +#' `graph.kautz()` was renamed to [make_kautz_graph()] to create a more consistent API. #' @inheritParams make_kautz_graph #' @keywords internal #' @export @@ -477,8 +468,7 @@ graph.kautz <- function(m, n) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.full.citation()` was renamed to [make_full_citation_graph()] to create a more -#' consistent API. +#' `graph.full.citation()` was renamed to [make_full_citation_graph()] to create a more consistent API. #' @inheritParams make_full_citation_graph #' @keywords internal #' @export @@ -504,8 +494,7 @@ graph.full.citation <- function(n, directed = TRUE) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.full.bipartite()` was renamed to [make_full_bipartite_graph()] to create a more -#' consistent API. +#' `graph.full.bipartite()` was renamed to [make_full_bipartite_graph()] to create a more consistent API. #' @inheritParams make_full_bipartite_graph #' @keywords internal #' @export @@ -545,8 +534,7 @@ graph.full.bipartite <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.full()` was renamed to [make_full_graph()] to create a more -#' consistent API. +#' `graph.full()` was renamed to [make_full_graph()] to create a more consistent API. #' @inheritParams make_full_graph #' @keywords internal #' @export @@ -570,8 +558,7 @@ graph.full <- function(n, directed = FALSE, loops = FALSE) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.formula()` was renamed to [graph_from_literal()] to create a more -#' consistent API. +#' `graph.formula()` was renamed to [graph_from_literal()] to create a more consistent API. #' @inheritParams graph_from_literal #' @keywords internal #' @export @@ -587,8 +574,7 @@ graph.formula <- function(..., simplify = TRUE) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.extended.chordal.ring()` was renamed to [make_chordal_ring()] to create a more -#' consistent API. +#' `graph.extended.chordal.ring()` was renamed to [make_chordal_ring()] to create a more consistent API. #' @inheritParams make_chordal_ring #' @keywords internal #' @export @@ -616,8 +602,7 @@ graph.extended.chordal.ring <- function(n, w, directed = FALSE) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.empty()` was renamed to [make_empty_graph()] to create a more -#' consistent API. +#' `graph.empty()` was renamed to [make_empty_graph()] to create a more consistent API. #' @inheritParams make_empty_graph #' @keywords internal #' @export @@ -638,8 +623,7 @@ graph.empty <- function(n = 0, directed = TRUE) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.de.bruijn()` was renamed to [make_de_bruijn_graph()] to create a more -#' consistent API. +#' `graph.de.bruijn()` was renamed to [make_de_bruijn_graph()] to create a more consistent API. #' @inheritParams make_de_bruijn_graph #' @keywords internal #' @export @@ -667,8 +651,7 @@ graph.de.bruijn <- function(m, n) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.bipartite()` was renamed to [make_bipartite_graph()] to create a more -#' consistent API. +#' `graph.bipartite()` was renamed to [make_bipartite_graph()] to create a more consistent API. #' @inheritParams make_bipartite_graph #' @keywords internal #' @export @@ -718,8 +701,7 @@ graph.bipartite <- function(types, edges, directed = FALSE) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.atlas()` was renamed to [graph_from_atlas()] to create a more -#' consistent API. +#' `graph.atlas()` was renamed to [graph_from_atlas()] to create a more consistent API. #' @inheritParams graph_from_atlas #' @keywords internal #' @export @@ -759,18 +741,14 @@ graph.atlas <- function(n) { ## ## ----------------------------------------------------------------- -#' Takes an argument list and extracts the constructor specification and -#' constructor modifiers from it. +#' Takes an argument list and extracts the constructor specification and constructor modifiers from it. #' -#' This is a helper function for the common parts of `make_()` and -#' `sample_()`. +#' This is a helper function for the common parts of `make_()` and `sample_()`. #' #' @param ... Parameters to extract from -#' @param .operation Human-readable description of the operation that this -#' helper is a part of -#' @param .variant Constructor variant; must be one of \sQuote{make}, -#' \sQuote{graph} or \sQuote{sample}. Used in cases when the same constructor -#' specification has deterministic and random variants. +#' @param .operation Human-readable description of the operation that this helper is a part of +#' @param .variant Constructor variant; must be one of \sQuote{make}, \sQuote{graph} or \sQuote{sample}. +#' Used in cases when the same constructor specification has deterministic and random variants. #' @return A named list with three items: #' \describe{ #' \item{cons}{ @@ -827,8 +805,7 @@ graph.atlas <- function(n) { #' Applies a set of constructor modifiers to an already constructed graph. #' -#' This is a helper function for the common parts of `make_()` and -#' `sample_()`. +#' This is a helper function for the common parts of `make_()` and `sample_()`. #' #' @param graph The graph to apply the modifiers to #' @param mods The modifiers to apply @@ -916,15 +893,12 @@ graph.atlas <- function(n) { #' there is a corresponding function without the prefix: e.g. #' for [make_ring()] there is also [ring()], etc. #' -#' The same is true for the random graph samplers, i.e. for each -#' constructor with a `sample_` prefix, there is a corresponding -#' function without that prefix. +#' The same is true for the random graph samplers, i.e. for each constructor with a `sample_` prefix, +#' there is a corresponding function without that prefix. #' #' These shorter forms can be used together with `make_()`. -#' The advantage of this form is that the user can specify constructor -#' modifiers which work with all constructors. E.g. the -#' [with_vertex_()] modifier adds vertex attributes -#' to the newly created graphs. +#' The advantage of this form is that the user can specify constructor modifiers which work with all constructors. +#' E.g. the [with_vertex_()] modifier adds vertex attributes to the newly created graphs. #' #' See the examples and the various constructor modifiers below. #' @@ -972,15 +946,12 @@ make_ <- function(...) { #' there is a corresponding function without the prefix: e.g. #' for [sample_pa()] there is also [pa()], etc. #' -#' The same is true for the deterministic graph samplers, i.e. for each -#' constructor with a `make_` prefix, there is a corresponding -#' function without that prefix. +#' The same is true for the deterministic graph samplers, i.e. for each constructor with a `make_` prefix, +#' there is a corresponding function without that prefix. #' #' These shorter forms can be used together with `sample_()`. -#' The advantage of this form is that the user can specify constructor -#' modifiers which work with all constructors. E.g. the -#' [with_vertex_()] modifier adds vertex attributes -#' to the newly created graphs. +#' The advantage of this form is that the user can specify constructor modifiers which work with all constructors. +#' E.g. the [with_vertex_()] modifier adds vertex attributes to the newly created graphs. #' #' See the examples and the various constructor modifiers below. #' @@ -1152,7 +1123,8 @@ simplified <- function() { #' Constructor modifier to add vertex attributes #' -#' @param ... The attributes to add. They must be named. +#' @param ... The attributes to add. +#' They must be named. #' #' @family constructor modifiers #' @@ -1179,7 +1151,8 @@ with_vertex_ <- function(...) { #' Constructor modifier to add edge attributes #' -#' @param ... The attributes to add. They must be named. +#' @param ... The attributes to add. +#' They must be named. #' #' @family constructor modifiers #' @@ -1205,7 +1178,8 @@ with_edge_ <- function(...) { #' Constructor modifier to add graph attributes #' -#' @param ... The attributes to add. They must be named. +#' @param ... The attributes to add. +#' They must be named. #' #' @family constructor modifiers #' @@ -1228,10 +1202,9 @@ with_graph_ <- function(...) { #' #' @section Notable graphs: #' -#' `make_graph()` can create some notable graphs. The name of the -#' graph (case insensitive), a character scalar must be supplied as -#' the `edges` argument, and other arguments are ignored. (A warning -#' is given is they are specified.) +#' `make_graph()` can create some notable graphs. +#' The name of the graph (case insensitive), a character scalar must be supplied as the `edges` argument, and other arguments are ignored. +#' (A warning is given is they are specified.) #' #' `make_graph()` knows the following graphs: #' \describe{ @@ -1370,33 +1343,26 @@ with_graph_ <- function(...) { #' } #' #' @encoding UTF-8 -#' @param edges A vector defining the edges, the first edge points -#' from the first element to the second, the second edge from the third -#' to the fourth, etc. For a numeric vector, these are interpreted -#' as internal vertex IDs. For character vectors, they are interpreted -#' as vertex names. -#' -#' Alternatively, this can be a character scalar, the name of a -#' notable graph. See Notable graphs below. The name is case -#' insensitive. -#' -#' Starting from igraph 0.8.0, you can also include literals here, -#' via igraph's formula notation (see [graph_from_literal()]). -#' In this case, the first term of the formula has to start with -#' a \sQuote{`~`} character, just like regular formulae in R. +#' @param edges A vector defining the edges, the first edge points from the first element to the second, +#' the second edge from the third to the fourth, etc. For a numeric vector, these are interpreted as internal vertex IDs. +#' For character vectors, they are interpreted as vertex names. +#' +#' Alternatively, this can be a character scalar, the name of a notable graph. +#' See Notable graphs below. +#' The name is case insensitive. +#' +#' Starting from igraph 0.8.0, you can also include literals here, via igraph's formula notation (see [graph_from_literal()]). +#' In this case, the first term of the formula has to start with a \sQuote{`~`} character, just like regular formulae in R. #' See examples below. -#' @param ... For `make_graph()`: extra arguments for the case when the -#' graph is given via a literal, see [graph_from_literal()]. -#' For `directed_graph()` and `undirected_graph()`: -#' Passed to `make_directed_graph()` or `make_undirected_graph()`. -#' @param n The number of vertices in the graph. This argument is -#' ignored (with a warning) if `edges` are symbolic vertex names. It -#' is also ignored if there is a bigger vertex ID in `edges`. This -#' means that for this function it is safe to supply zero here if the -#' vertex with the largest ID is not an isolate. The default `NULL` uses -#' the largest vertex ID in `edges`. -#' @param isolates Character vector, names of isolate vertices, -#' for symbolic edge lists. It is ignored for numeric edge lists. +#' @param ... For `make_graph()`: extra arguments for the case when the graph is given via a literal, see [graph_from_literal()]. +#' For `directed_graph()` and `undirected_graph()`: Passed to `make_directed_graph()` or `make_undirected_graph()`. +#' @param n The number of vertices in the graph. +#' This argument is ignored (with a warning) if `edges` are symbolic vertex names. +#' It is also ignored if there is a bigger vertex ID in `edges`. +#' This means that for this function it is safe to supply zero here if the vertex with the largest ID is not an isolate. +#' The default `NULL` uses the largest vertex ID in `edges`. +#' @param isolates Character vector, names of isolate vertices, for symbolic edge lists. +#' It is ignored for numeric edge lists. #' @param directed Whether to create a directed graph. #' @param dir It is the same as `directed`, for compatibility. #' Do not give both of them. @@ -1698,85 +1664,70 @@ empty_graph <- function( #' Creating (small) graphs via a simple interface #' -#' This function is useful if you want to create a small (named) graph -#' quickly, it works for both directed and undirected graphs. +#' This function is useful if you want to create a small (named) graph quickly, it works for both directed and undirected graphs. #' #' @details #' `graph_from_literal()` is very handy for creating small graphs quickly. -#' You need to supply one or more R expressions giving the structure of -#' the graph. The expressions consist of vertex names and edge -#' operators. An edge operator is a sequence of \sQuote{`-`} and -#' \sQuote{`+`} characters, the former is for the edges and the -#' latter is used for arrow heads. The edges can be arbitrarily long, -#' i.e. you may use as many \sQuote{`-`} characters to \dQuote{draw} -#' them as you like. -#' -#' If all edge operators consist of only \sQuote{`-`} characters -#' then the graph will be undirected, whereas a single \sQuote{`+`} -#' character implies a directed graph. -#' -#' Let us see some simple examples. Without arguments the function -#' creates an empty graph: +#' You need to supply one or more R expressions giving the structure of the graph. +#' The expressions consist of vertex names and edge operators. +#' An edge operator is a sequence of \sQuote{`-`} and \sQuote{`+`} characters, +#' the former is for the edges and the latter is used for arrow heads. +#' The edges can be arbitrarily long, i.e. you may use as many \sQuote{`-`} characters to \dQuote{draw} them as you like. +#' +#' If all edge operators consist of only \sQuote{`-`} characters then the graph will be undirected, +#' whereas a single \sQuote{`+`} character implies a directed graph. +#' +#' Let us see some simple examples. +#' Without arguments the function creates an empty graph: #' \preformatted{ graph_from_literal() #' } #' -#' A simple undirected graph with two vertices called \sQuote{A} and -#' \sQuote{B} and one edge only: +#' A simple undirected graph with two vertices called \sQuote{A} and \sQuote{B} and one edge only: #' \preformatted{ graph_from_literal(A-B) #' } #' -#' Remember that the length of the edges does not matter, so we could -#' have written the following, this creates the same graph: +#' Remember that the length of the edges does not matter, so we could have written the following, this creates the same graph: #' \preformatted{ graph_from_literal( A-----B ) #' } #' -#' If you have many disconnected components in the graph, separate them -#' with commas. You can also give isolate vertices. +#' If you have many disconnected components in the graph, separate them with commas. +#' You can also give isolate vertices. #' \preformatted{ graph_from_literal( A--B, C--D, E--F, G--H, I, J, K ) #' } #' -#' The \sQuote{`:`} operator can be used to define vertex sets. If -#' an edge operator connects two vertex sets then every vertex from the -#' first set will be connected to every vertex in the second set. The -#' following form creates a full graph, including loop edges: +#' The \sQuote{`:`} operator can be used to define vertex sets. +#' If an edge operator connects two vertex sets then every vertex from the first set will be connected to every vertex in the second set. +#' The following form creates a full graph, including loop edges: #' \preformatted{ graph_from_literal( A:B:C:D -- A:B:C:D ) #' } #' -#' In directed graphs, edges will be created only if the edge operator -#' includes a arrow head (\sQuote{+}) *at the end* of the edge: +#' In directed graphs, edges will be created only if the edge operator includes a arrow head (\sQuote{+}) *at the end* of the edge: #' \preformatted{ graph_from_literal( A -+ B -+ C ) #' graph_from_literal( A +- B -+ C ) #' graph_from_literal( A +- B -- C ) #' } -#' Thus in the third example no edge is created between vertices `B` -#' and `C`. +#' Thus in the third example no edge is created between vertices `B` and `C`. #' #' Mutual edges can be also created with a simple edge operator: #' \preformatted{ graph_from_literal( A +-+ B +---+ C ++ D + E) #' } -#' Note again that the length of the edge operators is arbitrary, -#' \sQuote{`+`}, \sQuote{`++`} and \sQuote{`+-----+`} have -#' exactly the same meaning. +#' Note again that the length of the edge operators is arbitrary, \sQuote{`+`}, +#' \sQuote{`++`} and \sQuote{`+-----+`} have exactly the same meaning. #' -#' If the vertex names include spaces or other special characters then -#' you need to quote them: +#' If the vertex names include spaces or other special characters then you need to quote them: #' \preformatted{ graph_from_literal( "this is" +- "a silly" -+ "graph here" ) #' } -#' You can include any character in the vertex names this way, even -#' \sQuote{+} and \sQuote{-} characters. +#' You can include any character in the vertex names this way, even \sQuote{+} and \sQuote{-} characters. #' #' See more examples below. #' -#' @param ... For `graph_from_literal()` the formulae giving the -#' structure of the graph, see details below. For `from_literal()` -#' all arguments are passed to `graph_from_literal()`. -#' @param simplify Logical, whether to call [simplify()] -#' on the created graph. By default the graph is simplified, loop and -#' multiple edges are removed. [simplify()] is only called when the -#' created graph is not already simple, so the edge order from the -#' formula is preserved whenever no loops or multi-edges are present. -#' When the graph does contain loops or multi-edges (and `simplify = -#' TRUE`), [simplify()] reorders the edges into its canonical order. +#' @param ... For `graph_from_literal()` the formulae giving the structure of the graph, see details below. +#' For `from_literal()` all arguments are passed to `graph_from_literal()`. +#' @param simplify Logical, whether to call [simplify()] on the created graph. +#' By default the graph is simplified, loop and multiple edges are removed. +#' [simplify()] is only called when the created graph is not already simple, +#' so the edge order from the formula is preserved whenever no loops or multi-edges are present. +#' When the graph does contain loops or multi-edges (and `simplify = TRUE`), [simplify()] reorders the edges into its canonical order. #' @return An igraph graph #' #' @family deterministic constructors @@ -1914,13 +1865,11 @@ graph_from_literal_i <- function(mf) { ids <- seq(along.with = v) names(ids) <- v res <- make_graph(unname(ids[edges]), n = length(v), directed = directed) - # `!is_simple()` is what keeps the formula's edge order when there is nothing - # to simplify (#824, #1981): `simplify()` rebuilds the graph sorted by - # endpoint, and a formula that declares no loops and no multiple edges has no - # reason to be rebuilt. The check belongs here rather than inside - # `simplify()`, where it also suppressed `edge.attr.comb` -- see the note - # there. `res` has no attributes yet, so skipping is unobservable beyond the - # order. + # `!is_simple()` is what keeps the formula's edge order when there is nothing to simplify (#824, #1981): + # `simplify()` rebuilds the graph sorted by endpoint, + # and a formula that declares no loops and no multiple edges has no reason to be rebuilt. + # The check belongs here rather than inside `simplify()`, where it also suppressed `edge.attr.comb` -- see the note there. + # `res` has no attributes yet, so skipping is unobservable beyond the order. if (simplify && !is_simple(res)) { res <- simplify(res) } @@ -1938,17 +1887,13 @@ from_literal <- function(...) { #' Create a star graph, a tree with n vertices and n - 1 leaves #' -#' `star()` creates a star graph, in this every single vertex is -#' connected to the center vertex and nobody else. +#' `star()` creates a star graph, in this every single vertex is connected to the center vertex and nobody else. #' #' @concept Star graph #' @param n Number of vertices. #' @inheritParams rlang::args_dots_empty -#' @param mode It defines the direction of the -#' edges, `in`: the edges point *to* the center, `out`: -#' the edges point *from* the center, `mutual`: a directed -#' star is created with mutual edges, `undirected`: the edges -#' are undirected. +#' @param mode It defines the direction of the edges, `in`: the edges point *to* the center, `out`: the edges point *from* the center, +#' `mutual`: a directed star is created with mutual edges, `undirected`: the edges are undirected. #' @param center ID of the center vertex. #' @return An igraph graph. #' @@ -2188,26 +2133,21 @@ full_graph <- function( #' Create a lattice graph #' -#' `make_lattice()` is a flexible function, it can create lattices of -#' arbitrary dimensions, periodic or aperiodic ones. It has two -#' forms. In the first form you only supply `dimvector`, but not -#' `length` and `dim`. In the second form you omit -#' `dimvector` and supply `length` and `dim`. +#' `make_lattice()` is a flexible function, it can create lattices of arbitrary dimensions, periodic or aperiodic ones. +#' It has two forms. +#' In the first form you only supply `dimvector`, but not `length` and `dim`. +#' In the second form you omit `dimvector` and supply `length` and `dim`. #' #' @concept Lattice -#' @param dimvector A vector giving the size of the lattice in each -#' dimension. -#' @param length Integer constant, for regular lattices, the size of the -#' lattice in each dimension. +#' @param dimvector A vector giving the size of the lattice in each dimension. +#' @param length Integer constant, for regular lattices, the size of the lattice in each dimension. #' @param dim Integer constant, the dimension of the lattice. -#' @param nei The distance within which (inclusive) the neighbors on the -#' lattice will be connected. This parameter is not used right now. +#' @param nei The distance within which (inclusive) the neighbors on the lattice will be connected. +#' This parameter is not used right now. #' @param directed Whether to create a directed lattice. -#' @param mutual Logical, if `TRUE` directed lattices will be -#' mutually connected. -#' @param periodic Logical vector, defines whether the generated lattice is -#' periodic along each dimension. This parameter may also be a single logical which will -#' be extended to a logical vector of `dimvector`` length. +#' @param mutual Logical, if `TRUE` directed lattices will be mutually connected. +#' @param periodic Logical vector, defines whether the generated lattice is periodic along each dimension. +#' This parameter may also be a single logical which will be extended to a logical vector of `dimvector`` length. #' @param circular Deprecated, use `periodic` instead. #' @return An igraph graph. #' @@ -2295,17 +2235,15 @@ lattice <- function( #' Create a ring graph #' -#' A ring is a one-dimensional lattice and this function is a special case -#' of [make_lattice()]. +#' A ring is a one-dimensional lattice and this function is a special case of [make_lattice()]. #' #' @param n Number of vertices. #' @inheritParams rlang::args_dots_empty #' @param directed Whether the graph is directed. -#' @param mutual Whether directed edges are mutual. It is ignored in -#' undirected graphs. -#' @param circular Whether to create a circular ring. A non-circular -#' ring is essentially a \dQuote{line}: a tree where every non-leaf -#' vertex has one child. +#' @param mutual Whether directed edges are mutual. +#' It is ignored in undirected graphs. +#' @param circular Whether to create a circular ring. +#' A non-circular ring is essentially a \dQuote{line}: a tree where every non-leaf vertex has one child. #' @return An igraph graph. #' #' @family deterministic constructors @@ -2438,24 +2376,19 @@ ring <- function( #' @description #' `r lifecycle::badge("experimental")` #' -#' A wheel graph is created by connecting a center vertex to all vertices of a -#' cycle graph. -#' A wheel graph on `n` vertices can be thought of as a wheel with `n - 1` -#' spokes. -#' The cycle graph part makes up the rim, while the star graph part adds the -#' spokes. +#' A wheel graph is created by connecting a center vertex to all vertices of a cycle graph. +#' A wheel graph on `n` vertices can be thought of as a wheel with `n - 1` spokes. +#' The cycle graph part makes up the rim, while the star graph part adds the spokes. #' -#' Note that the two and three-vertex wheel graphs are non-simple: The -#' two-vertex wheel graph contains a self-loop, while the three-vertex wheel -#' graph contains parallel edges (a 1-cycle and a 2-cycle, respectively). +#' Note that the two and three-vertex wheel graphs are non-simple: The two-vertex wheel graph contains a self-loop, +#' while the three-vertex wheel graph contains parallel edges (a 1-cycle and a 2-cycle, respectively). #' #' @concept Wheel graph #' @param n Number of vertices. #' @inheritParams rlang::args_dots_empty #' @param mode It defines the direction of the edges. -#' `in`: the edges point *to* the center, `out`: the edges point *from* the -#' center, `mutual`: a directed wheel is created with mutual edges, -#' `undirected`: the edges are undirected. +#' `in`: the edges point *to* the center, `out`: the edges point *from* the center, `mutual`: +#' a directed wheel is created with mutual edges, `undirected`: the edges are undirected. #' @param center ID of the center vertex. #' @return An igraph graph. #' @@ -2505,19 +2438,15 @@ wheel <- function( #' Create tree graphs #' -#' Create a k-ary tree graph, where almost all vertices other than the leaves -#' have the same number of children. +#' Create a k-ary tree graph, where almost all vertices other than the leaves have the same number of children. #' #' @concept Trees. #' @param n Number of vertices. -#' @param children Integer scalar, the number of children of a vertex -#' (except for leafs) +#' @param children Integer scalar, the number of children of a vertex (except for leafs) #' @inheritParams rlang::args_dots_empty -#' @param mode Defines the direction of the -#' edges. `out` indicates that the edges point from the parent to -#' the children, `in` indicates that they point from the children -#' to their parents, while `undirected` creates an undirected -#' graph. +#' @param mode Defines the direction of the edges. +#' `out` indicates that the edges point from the parent to the children, +#' `in` indicates that they point from the children to their parents, while `undirected` creates an undirected graph. #' @return An igraph graph #' @seealso [tree()] to build a lazy constructor specification for #' [make_()] or [sample_()]. @@ -2585,22 +2514,20 @@ make_tree <- function( #' Sample trees randomly and uniformly #' -#' `sample_tree()` generates a random with a given number of nodes uniform -#' at random from the set of labelled trees. +#' `sample_tree()` generates a random with a given number of nodes uniform at random from the set of labelled trees. #' -#' In other words, the function generates each possible labelled tree with the -#' given number of nodes with the same probability. +#' In other words, the function generates each possible labelled tree with the given number of nodes with the same probability. #' #' @param n The number of nodes in the tree #' @inheritParams rlang::args_dots_empty -#' @param directed Whether to create a directed tree. The edges of the tree are -#' oriented away from the root. -#' @param method The algorithm to use to generate the tree. \sQuote{prufer} -#' samples Prüfer sequences uniformly and then converts the sampled sequence to -#' a tree. \sQuote{lerw} performs a loop-erased random walk on the complete -#' graph to uniformly sampleits spanning trees. (This is also known as Wilson's -#' algorithm). The default is \sQuote{lerw}. Note that the method based on -#' Prüfer sequences does not support directed trees at the moment. +#' @param directed Whether to create a directed tree. +#' The edges of the tree are oriented away from the root. +#' @param method The algorithm to use to generate the tree. +#' \sQuote{prufer} samples Prüfer sequences uniformly and then converts the sampled sequence to a tree. +#' \sQuote{lerw} performs a loop-erased random walk on the complete graph to uniformly sampleits spanning trees. +#' (This is also known as Wilson's algorithm). +#' The default is \sQuote{lerw}. +#' Note that the method based on Prüfer sequences does not support directed trees at the moment. #' @return A graph object. #' #' @family games @@ -2671,14 +2598,12 @@ tree <- function(...) { #' Create an undirected tree graph from its Prüfer sequence #' -#' `make_from_prufer()` creates an undirected tree graph from its Prüfer -#' sequence. +#' `make_from_prufer()` creates an undirected tree graph from its Prüfer sequence. #' -#' The Prüfer sequence of a tree graph with n labeled vertices is a sequence of -#' n-2 numbers, constructed as follows. If the graph has more than two vertices, -#' find a vertex with degree one, remove it from the tree and add the label of -#' the vertex that it was connected to to the sequence. Repeat until there are -#' only two vertices in the remaining graph. +#' The Prüfer sequence of a tree graph with n labeled vertices is a sequence of n-2 numbers, constructed as follows. +#' If the graph has more than two vertices, find a vertex with degree one, +#' remove it from the tree and add the label of the vertex that it was connected to to the sequence. +#' Repeat until there are only two vertices in the remaining graph. #' #' @param prufer The Prüfer sequence to convert into a graph #' @return A graph object. @@ -2707,11 +2632,8 @@ from_prufer <- function(prufer) { #' Create a graph from the Graph Atlas #' -#' `graph_from_atlas()` creates graphs from the book -#' \sQuote{An Atlas of Graphs} by -#' Roland C. Read and Robin J. Wilson. The atlas contains all undirected -#' graphs with up to seven vertices, numbered from 0 up to 1252. The -#' graphs are listed: +#' `graph_from_atlas()` creates graphs from the book \sQuote{An Atlas of Graphs} by Roland C. Read and Robin J. Wilson. +#' The atlas contains all undirected graphs with up to seven vertices, numbered from 0 up to 1252. The graphs are listed: #' \enumerate{ #' \item in increasing order of number of nodes; #' \item for a fixed number of nodes, in increasing order of the number @@ -2754,20 +2676,17 @@ atlas <- function(n) { #' Create an extended chordal ring graph #' #' `make_chordal_ring()` creates an extended chordal ring. -#' An extended chordal ring is regular graph, each node has the same -#' degree. It can be obtained from a simple ring by adding some extra -#' edges specified by a matrix. Let p denote the number of columns in -#' the \sQuote{`W`} matrix. The extra edges of vertex `i` -#' are added according to column `i mod p` in -#' \sQuote{`W`}. The number of extra edges is the number -#' of rows in \sQuote{`W`}: for each row `j` an edge -#' `i->i+w[ij]` is added if `i+w[ij]` is less than the number -#' of total nodes. See also Kotsis, G: Interconnection Topologies for -#' Parallel Processing Systems, PARS Mitteilungen 11, 1-6, 1993. +#' An extended chordal ring is regular graph, each node has the same degree. +#' It can be obtained from a simple ring by adding some extra edges specified by a matrix. +#' Let p denote the number of columns in the \sQuote{`W`} matrix. +#' The extra edges of vertex `i` are added according to column `i mod p` in \sQuote{`W`}. +#' The number of extra edges is the number of rows in \sQuote{`W`}: +#' for each row `j` an edge `i->i+w[ij]` is added if `i+w[ij]` is less than the number of total nodes. +#' See also Kotsis, G: Interconnection Topologies for Parallel Processing Systems, PARS Mitteilungen 11, 1-6, 1993. #' #' @param n The number of vertices. -#' @param w A matrix which specifies the extended chordal ring. See -#' details below. +#' @param w A matrix which specifies the extended chordal ring. +#' See details below. #' @inheritParams rlang::args_dots_empty #' @param directed Logical, whether or not to create a directed graph. #' @return An igraph graph. @@ -2883,9 +2802,8 @@ chordal_ring <- function( #' Create a circulant graph #' -#' A circulant graph \eqn{C_n^{\textrm{shifts}}} consists of \eqn{n} vertices -#' \eqn{v_0, \ldots, v_{n-1}} such that for each \eqn{s_i} in the list of offsets -#' `shifts`, \eqn{v_j} is connected to \eqn{v_{(j + s_i) \mod n}} for all \eqn{j}. +#' A circulant graph \eqn{C_n^{\textrm{shifts}}} consists of \eqn{n} vertices \eqn{v_0, \ldots, v_{n-1}} such that for each \eqn{s_i} in the list of offsets `shifts`, +#' \eqn{v_j} is connected to \eqn{v_{(j + s_i) \mod n}} for all \eqn{j}. #' #' The function can generate either directed or undirected graphs. #' It does not generate multi-edges or self-loops. @@ -3007,16 +2925,13 @@ circulant <- function( #' #' This function calculates the line graph of another graph. #' -#' The line graph `L(G)` of a `G` undirected graph is defined as -#' follows. `L(G)` has one vertex for each edge in `G` and two -#' vertices in `L(G)` are connected by an edge if their corresponding -#' edges share an end point. +#' The line graph `L(G)` of a `G` undirected graph is defined as follows. +#' `L(G)` has one vertex for each edge in `G` and two vertices in `L(G)` are connected by an edge +#' if their corresponding edges share an end point. #' -#' The line graph `L(G)` of a `G` directed graph is slightly -#' different, `L(G)` has one vertex for each edge in `G` and two -#' vertices in `L(G)` are connected by a directed edge if the target of -#' the first vertex's corresponding edge is the same as the source of the -#' second vertex's corresponding edge. +#' The line graph `L(G)` of a `G` directed graph is slightly different, +#' `L(G)` has one vertex for each edge in `G` and two vertices in `L(G)` are connected by a directed edge +#' if the target of the first vertex's corresponding edge is the same as the source of the second vertex's corresponding edge. #' #' @param graph The input graph, it can be directed or undirected. #' @return A new graph object. @@ -3056,22 +2971,20 @@ line_graph <- function(graph) { #' #' De Bruijn graphs are labeled graphs representing the overlap of strings. #' -#' A de Bruijn graph represents relationships between strings. An alphabet of -#' `m` letters are used and strings of length `n` are considered. A -#' vertex corresponds to every possible string and there is a directed edge -#' from vertex `v` to vertex `w` if the string of `v` can be -#' transformed into the string of `w` by removing its first letter and -#' appending a letter to it. +#' A de Bruijn graph represents relationships between strings. +#' An alphabet of `m` letters are used and strings of length `n` are considered. +#' A vertex corresponds to every possible string and there is a directed edge from vertex `v` to vertex `w` +#' if the string of `v` can be transformed into the string of `w` by removing its first letter and appending a letter to it. #' -#' Please note that the graph will have `m` to the power `n` vertices -#' and even more edges, so probably you don't want to supply too big numbers -#' for `m` and `n`. +#' Please note that the graph will have `m` to the power `n` vertices and even more edges, +#' so probably you don't want to supply too big numbers for `m` and `n`. #' -#' De Bruijn graphs have some interesting properties, please see another -#' source, e.g. Wikipedia for details. +#' De Bruijn graphs have some interesting properties, please see another source, e.g. Wikipedia for details. #' -#' @param m Integer scalar, the size of the alphabet. See details below. -#' @param n Integer scalar, the length of the labels. See details below. +#' @param m Integer scalar, the size of the alphabet. +#' See details below. +#' @param n Integer scalar, the length of the labels. +#' See details below. #' @return A graph object. #' @author Gabor Csardi #' @seealso [make_kautz_graph()], [make_line_graph()] @@ -3108,18 +3021,17 @@ de_bruijn_graph <- function(m, n) { #' #' Kautz graphs are labeled graphs representing the overlap of strings. #' -#' A Kautz graph is a labeled graph, vertices are labeled by strings of length -#' `n+1` above an alphabet with `m+1` letters, with the restriction -#' that every two consecutive letters in the string must be different. There is -#' a directed edge from a vertex `v` to another vertex `w` if it is -#' possible to transform the string of `v` into the string of `w` by -#' removing the first letter and appending a letter to it. +#' A Kautz graph is a labeled graph, vertices are labeled by strings of length `n+1` above an alphabet with `m+1` letters, +#' with the restriction that every two consecutive letters in the string must be different. +#' There is a directed edge from a vertex `v` to another vertex `w` +#' if it is possible to transform the string of `v` into the string of `w` by removing the first letter and appending a letter to it. #' -#' Kautz graphs have some interesting properties, see e.g. Wikipedia for -#' details. +#' Kautz graphs have some interesting properties, see e.g. Wikipedia for details. #' -#' @param m Integer scalar, the size of the alphabet. See details below. -#' @param n Integer scalar, the length of the labels. See details below. +#' @param m Integer scalar, the size of the alphabet. +#' See details below. +#' @param n Integer scalar, the length of the labels. +#' See details below. #' @return A graph object. #' @author Gabor Csardi , the first version in R was #' written by Vincent Matossian. @@ -3154,22 +3066,20 @@ kautz_graph <- function(m, n) { #' Create a full bipartite graph #' -#' Bipartite graphs are also called two-mode by some. This function creates a -#' bipartite graph in which every possible edge is present. +#' Bipartite graphs are also called two-mode by some. +#' This function creates a bipartite graph in which every possible edge is present. #' #' Bipartite graphs have a \sQuote{`type`} vertex attribute in igraph, -#' this is boolean and `FALSE` for the vertices of the first kind and -#' `TRUE` for vertices of the second kind. +#' this is boolean and `FALSE` for the vertices of the first kind and `TRUE` for vertices of the second kind. #' #' @param n1 The number of vertices of the first kind. #' @param n2 The number of vertices of the second kind. #' @inheritParams rlang::args_dots_empty #' @param directed Logical, whether the graphs is directed. #' @param mode Scalar giving the kind of edges to create for directed graphs. -#' If this is \sQuote{`out`} then all vertices of the first kind are -#' connected to the others; \sQuote{`in`} specifies the opposite -#' direction; \sQuote{`all`} creates mutual edges. This argument is -#' ignored for undirected graphs.x +#' If this is \sQuote{`out`} then all vertices of the first kind are connected to the others; +#' \sQuote{`in`} specifies the opposite direction; \sQuote{`all`} creates mutual edges. +#' This argument is ignored for undirected graphs.x #' @return An igraph graph, with the \sQuote{`type`} vertex attribute set. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @seealso [make_full_graph()] for creating one-mode full graphs @@ -3305,34 +3215,29 @@ full_bipartite_graph <- function( #' Create a bipartite graph #' -#' A bipartite graph has two kinds of vertices and connections are only allowed -#' between different kinds. -#' -#' Bipartite graphs have a `type` vertex attribute in igraph, this is -#' boolean and `FALSE` for the vertices of the first kind and `TRUE` -#' for vertices of the second kind. -#' -#' `make_bipartite_graph()` basically does three things. First it checks the -#' `edges` vector against the vertex `types`. Then it creates a graph -#' using the `edges` vector and finally it adds the `types` vector as -#' a vertex attribute called `type`. `edges` may contain strings as -#' vertex names; in this case, `types` must be a named vector that specifies -#' the type for each vertex name that occurs in `edges`. -#' -#' @param types A vector giving the vertex types. It will be coerced into -#' boolean. The length of the vector gives the number of vertices in the graph. -#' When the vector is a named vector, the names will be attached to the graph -#' as the `name` vertex attribute. -#' @param edges A vector giving the edges of the graph, the same way as for the -#' regular [make_graph()] function. It is checked that the edges indeed -#' connect vertices of different kind, according to the supplied `types` -#' vector. The vector may be a string vector if `types` is a named vector. +#' A bipartite graph has two kinds of vertices and connections are only allowed between different kinds. +#' +#' Bipartite graphs have a `type` vertex attribute in igraph, +#' this is boolean and `FALSE` for the vertices of the first kind and `TRUE` for vertices of the second kind. +#' +#' `make_bipartite_graph()` basically does three things. +#' First it checks the `edges` vector against the vertex `types`. +#' Then it creates a graph using the `edges` vector and finally it adds the `types` vector as a vertex attribute called `type`. +#' `edges` may contain strings as vertex names; in this case, +#' `types` must be a named vector that specifies the type for each vertex name that occurs in `edges`. +#' +#' @param types A vector giving the vertex types. +#' It will be coerced into boolean. +#' The length of the vector gives the number of vertices in the graph. +#' When the vector is a named vector, the names will be attached to the graph as the `name` vertex attribute. +#' @param edges A vector giving the edges of the graph, the same way as for the regular [make_graph()] function. +#' It is checked that the edges indeed connect vertices of different kind, according to the supplied `types` vector. +#' The vector may be a string vector if `types` is a named vector. #' @inheritParams rlang::args_dots_empty -#' @param directed Logical, whether to create a directed graph. Note -#' that by default undirected graphs are created, as this is more common for -#' bipartite graphs. -#' @return `make_bipartite_graph()` returns a bipartite igraph graph. In other -#' words, an igraph graph that has a vertex attribute named `type`. +#' @param directed Logical, whether to create a directed graph. +#' Note that by default undirected graphs are created, as this is more common for bipartite graphs. +#' @return `make_bipartite_graph()` returns a bipartite igraph graph. +#' In other words, an igraph graph that has a vertex attribute named `type`. #' #' `is_bipartite()` returns a Logical. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} @@ -3476,21 +3381,18 @@ bipartite_graph <- function( #' Create a full multipartite graph #' -#' A multipartite graph contains multiple types of vertices and connections -#' are only possible between vertices of different types. This function -#' creates a complete multipartite graph where all possible edges between -#' different partitions are present. +#' A multipartite graph contains multiple types of vertices and connections are only possible between vertices of different types. +#' This function creates a complete multipartite graph where all possible edges between different partitions are present. #' #' @param n A numeric vector giving the number of vertices in each partition. #' @inheritParams rlang::args_dots_empty #' @param directed Logical, whether to create a directed graph. #' @param mode Character scalar, the type of connections for directed graphs. -#' If `"out"`, then edges point from vertices of partitions with lower -#' indices to partitions with higher indices; if `"in"`, then the opposite -#' direction is realized; `"all"` creates mutual edges. This parameter is -#' ignored for undirected graphs. -#' @return An igraph graph with a vertex attribute `type` storing the -#' partition index of each vertex. Partition indices start from 1. +#' If `"out"`, then edges point from vertices of partitions with lower indices to partitions with higher indices; if `"in"`, +#' then the opposite direction is realized; `"all"` creates mutual edges. +#' This parameter is ignored for undirected graphs. +#' @return An igraph graph with a vertex attribute `type` storing the partition index of each vertex. +#' Partition indices start from 1. #' #' @family deterministic constructors #' @export @@ -3623,21 +3525,19 @@ full_multipartite <- function( #' Create a Turán graph #' -#' Turán graphs are complete multipartite graphs with the property that the -#' sizes of the partitions are as close to equal as possible. +#' Turán graphs are complete multipartite graphs with the property that the sizes of the partitions are as close to equal as possible. #' #' @details -#' The Turán graph with `n` vertices and `r` partitions is the densest -#' graph on `n` vertices that does not contain a clique of size `r+1`. +#' The Turán graph with `n` vertices and `r` partitions is the densest graph on `n` vertices that does not contain a clique of size `r+1`. #' -#' This function generates undirected graphs. The null graph is -#' returned when the number of vertices is zero. A complete graph is -#' returned if the number of partitions is greater than the number of vertices. +#' This function generates undirected graphs. +#' The null graph is returned when the number of vertices is zero. +#' A complete graph is returned if the number of partitions is greater than the number of vertices. #' #' @param n Integer, the number of vertices in the graph. #' @param r Integer, the number of partitions in the graph, must be positive. -#' @return An igraph graph with a vertex attribute `type` storing the -#' partition index of each vertex. Partition indices start from 1. +#' @return An igraph graph with a vertex attribute `type` storing the partition index of each vertex. +#' Partition indices start from 1. #' #' @family deterministic constructors #' @export @@ -3677,9 +3577,9 @@ turan <- function(n, r) { #' Create a complete (full) citation graph #' -#' `make_full_citation_graph()` creates a full citation graph. This is a -#' directed graph, where every `i->j` edge is present if and only if -#' \eqn{jj` edge is present if and only if \eqn{j for details. #' #' #' @aliases graph_from_lcf -#' @param n Integer, the number of vertices in the graph. If `NULL` (default), -#' it is set to `len(shifts) * repeats`. +#' @param n Integer, the number of vertices in the graph. +#' If `NULL` (default), it is set to `len(shifts) * repeats`. #' @param shifts Integer vector, the shifts. #' @param repeats Integer constant, how many times to repeat the shifts. #' @inheritParams rlang::args_dots_empty #' @return A graph object. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso [make_graph()] can create arbitrary graphs, see also the other -#' functions on the its manual page for creating special graphs. +#' @seealso [make_graph()] can create arbitrary graphs, see also the other functions on the its manual page for creating special graphs. #' @keywords graphs #' @examples #' @@ -3853,49 +3750,44 @@ graph_from_lcf <- function( #' Creating a graph from a given degree sequence, deterministically #' -#' It is often useful to create a graph with given vertex degrees. This function -#' creates such a graph in a deterministic manner. +#' It is often useful to create a graph with given vertex degrees. +#' This function creates such a graph in a deterministic manner. #' -#' Simple undirected graphs are constructed using the Havel-Hakimi algorithm -#' (undirected case), or the analogous Kleitman-Wang algorithm (directed case). -#' These algorithms work by choosing an arbitrary vertex and connecting all its -#' stubs to other vertices. This step is repeated until all degrees have been -#' connected up. +#' Simple undirected graphs are constructed using the Havel-Hakimi algorithm (undirected case), +#' or the analogous Kleitman-Wang algorithm (directed case). +#' These algorithms work by choosing an arbitrary vertex and connecting all its stubs to other vertices. +#' This step is repeated until all degrees have been connected up. #' -#' The \sQuote{method} argument controls in which order the vertices are -#' selected during the course of the algorithm. +#' The \sQuote{method} argument controls in which order the vertices are selected during the course of the algorithm. #' -#' The \dQuote{smallest} method selects the vertex with the smallest remaining -#' degree. The result is usually a graph with high negative degree assortativity. -#' In the undirected case, this method is guaranteed to generate a connected -#' graph, regardless of whether multi-edges are allowed, provided that a -#' connected realization exists. See Horvát and Modes (2021) for details. -#' In the directed case it tends to generate weakly connected graphs, but this -#' is not guaranteed. This is the default method. +#' The \dQuote{smallest} method selects the vertex with the smallest remaining degree. +#' The result is usually a graph with high negative degree assortativity. +#' In the undirected case, this method is guaranteed to generate a connected graph, regardless of whether multi-edges are allowed, +#' provided that a connected realization exists. +#' See Horvát and Modes (2021) for details. +#' In the directed case it tends to generate weakly connected graphs, but this is not guaranteed. +#' This is the default method. #' -#' The \dQuote{largest} method selects the vertex with the largest remaining -#' degree. The result is usually a graph with high positive degree assortativity, -#' and is often disconnected. +#' The \dQuote{largest} method selects the vertex with the largest remaining degree. +#' The result is usually a graph with high positive degree assortativity, and is often disconnected. #' #' The \dQuote{index} method selects the vertices in order of their index. #' -#' @param out.deg Numeric vector, the sequence of degrees (for undirected -#' graphs) or out-degrees (for directed graphs). For undirected graphs its sum -#' should be even. For directed graphs its sum should be the same as the sum of -#' `in.deg`. -#' @param in.deg For directed graph, the in-degree sequence. By default this is -#' `NULL` and an undirected graph is created. +#' @param out.deg Numeric vector, the sequence of degrees (for undirected graphs) or out-degrees (for directed graphs). +#' For undirected graphs its sum should be even. +#' For directed graphs its sum should be the same as the sum of `in.deg`. +#' @param in.deg For directed graph, the in-degree sequence. +#' By default this is `NULL` and an undirected graph is created. #' @param method Character, the method for generating the graph; see below. #' @inheritParams rlang::args_dots_empty #' @param allowed.edge.types Character, specifies the types of allowed edges. #' \dQuote{simple} allows simple graphs only (no loops, no multiple edges). #' \dQuote{multiple} allows multiple edges but disallows loop. -#' \dQuote{loops} allows loop edges but disallows multiple edges (currently -#' unimplemented). \dQuote{all} allows all types of edges. The default is -#' \dQuote{simple}. +#' \dQuote{loops} allows loop edges but disallows multiple edges (currently unimplemented). +#' \dQuote{all} allows all types of edges. +#' The default is \dQuote{simple}. #' @return The new graph object. -#' @seealso [sample_degseq()] for a randomized variant that samples -#' from graphs with the given degree sequence. +#' @seealso [sample_degseq()] for a randomized variant that samples from graphs with the given degree sequence. #' @references V. Havel, #' Poznámka o existenci konečných grafů (A remark on the existence of finite graphs), #' Časopis pro pěstování matematiky 80, 477-480 (1955). @@ -4008,24 +3900,20 @@ realize_degseq <- function( #' @description #' `r lifecycle::badge("experimental")` #' -#' Constructs a bipartite graph from the degree sequences of its partitions, -#' if one exists. This function uses a Havel-Hakimi style construction -#' algorithm. +#' Constructs a bipartite graph from the degree sequences of its partitions, if one exists. +#' This function uses a Havel-Hakimi style construction algorithm. #' #' @details -#' The \sQuote{method} argument controls in which order the vertices are -#' selected during the course of the algorithm. -#' -#' The \dQuote{smallest} method selects the vertex with the smallest remaining -#' degree, from either partition. The result is usually a graph with high -#' negative degree assortativity. In the undirected case, this method is -#' guaranteed to generate a connected graph, regardless of whether multi-edges -#' are allowed, provided that a connected realization exists. This is the -#' default method. -#' -#' The \dQuote{largest} method selects the vertex with the largest remaining -#' degree. The result is usually a graph with high positive degree -#' assortativity, and is often disconnected. +#' The \sQuote{method} argument controls in which order the vertices are selected during the course of the algorithm. +#' +#' The \dQuote{smallest} method selects the vertex with the smallest remaining degree, from either partition. +#' The result is usually a graph with high negative degree assortativity. +#' In the undirected case, this method is guaranteed to generate a connected graph, regardless of whether multi-edges are allowed, +#' provided that a connected realization exists. +#' This is the default method. +#' +#' The \dQuote{largest} method selects the vertex with the largest remaining degree. +#' The result is usually a graph with high positive degree assortativity, and is often disconnected. #' #' The \dQuote{index} method selects the vertices in order of their index. #' diff --git a/R/migration-fixture.R b/R/migration-fixture.R index 9d9de569d20..27a622ba4fa 100644 --- a/R/migration-fixture.R +++ b/R/migration-fixture.R @@ -1,12 +1,9 @@ -# Test fixture for the in-place argument-migration generator (tools/migrations.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` -# and `kind` to `type` (`directed` survives unchanged). The names are chosen so -# the tests can exercise two renames, unique and ambiguous abbreviations, and -# base-R matching of the head args (`graph`, `n`). It exists only to exercise the -# generator end-to-end; see tests/testthat/test-migration-fixture.R. +# Test fixture for the in-place argument-migration generator (tools/migrations.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` and `kind` to `type` (`directed` survives unchanged). +# The names are chosen so the tests can exercise two renames, unique and ambiguous abbreviations, +# and base-R matching of the head args (`graph`, `n`). +# It exists only to exercise the generator end-to-end; see tests/testthat/test-migration-fixture.R. #' @noRd migration_fixture <- function( @@ -67,13 +64,11 @@ migration_fixture <- function( ) } -# Second fixture: head/recoverable prefix overlaps. `dim` (recoverable) is a -# strict prefix of the head arg `dimvector`, and the head arg `p` is a strict -# prefix of the recoverable `permutation` -- the two shapes that -# make_lattice()- and sample_correlated_gnp_pair()-style signatures hit. The -# generated block gains a `.arg_forbidden` guard that rejects the forbidden -# prefixes (`d`, `di`) when legacy arguments in `...` engage recovery; with -# empty dots they bind the head arg via plain partial matching. +# Second fixture: head/recoverable prefix overlaps. +# `dim` (recoverable) is a strict prefix of the head arg `dimvector`, and the head arg `p` is a strict prefix of the recoverable `permutation` -- the two shapes +# that make_lattice()- and sample_correlated_gnp_pair()-style signatures hit. +# The generated block gains a `.arg_forbidden` guard that rejects the forbidden prefixes (`d`, `di`) when legacy arguments in `...` engage recovery; +# with empty dots they bind the head arg via plain partial matching. migration_fixture_prefix <- function( dimvector, p, @@ -128,14 +123,14 @@ migration_fixture_prefix <- function( ) } -# Third fixture: the two hazards a generated block faces in a real function -# body. `names` and `c` are argument names, so the block's own calls would -# resolve to them unless every call is namespace-qualified -- and a *missing* -# formal is worse than a shadowing one, since R forces the promise while looking -# for a function of that name. `attr` was renamed to `weights` while a -# deprecated `attr` formal stayed behind, so `attr =` binds that formal while -# its abbreviations (`a`, `at`, `att`) could mean either and are rejected. This -# is the as_adjacency_matrix()/as_biadjacency_matrix() shape. +# Third fixture: the two hazards a generated block faces in a real function body. +# `names` and `c` are argument names, +# so the block's own calls would resolve to them +# unless every call is namespace-qualified -- and a *missing* formal is worse than a shadowing one, +# since R forces the promise while looking for a function of that name. +# `attr` was renamed to `weights` while a deprecated `attr` formal stayed behind, +# so `attr =` binds that formal while its abbreviations (`a`, `at`, `att`) could mean either and are rejected. +# This is the as_adjacency_matrix()/as_biadjacency_matrix() shape. migration_fixture_shadow <- function( graph, ..., diff --git a/R/minimum.spanning.tree.R b/R/minimum.spanning.tree.R index 0ea8c52a00e..5defbc65adc 100644 --- a/R/minimum.spanning.tree.R +++ b/R/minimum.spanning.tree.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `minimum.spanning.tree()` was renamed to [mst()] to create a more -#' consistent API. +#' `minimum.spanning.tree()` was renamed to [mst()] to create a more consistent API. #' @inheritParams mst #' @keywords internal #' @export @@ -41,32 +40,29 @@ minimum.spanning.tree <- function( #' Minimum spanning tree #' -#' A *spanning tree* of a connected graph is a connected subgraph with -#' the smallest number of edges that includes all vertices of the graph. -#' A graph will have many spanning trees. Among these, the *minimum spanning -#' tree* will have the smallest sum of edge weights. +#' A *spanning tree* of a connected graph is a connected subgraph with the smallest number of edges that includes all vertices of the graph. +#' A graph will have many spanning trees. +#' Among these, the *minimum spanning tree* will have the smallest sum of edge weights. #' -#' The *minimum spanning forest* of a disconnected graph is the collection -#' of minimum spanning trees of all of its components. +#' The *minimum spanning forest* of a disconnected graph is the collection of minimum spanning trees of all of its components. #' #' If the graph is not connected a minimum spanning forest is returned. #' #' @param graph The graph object to analyze. -#' @param weights Numeric vector giving the weights of the edges in the -#' graph. The order is determined by the edge IDs. This is ignored if the -#' `unweighted` algorithm is chosen. Edge weights are interpreted as -#' distances. -#' @param algorithm The algorithm to use for calculation. `unweighted` can -#' be used for unweighted graphs, and `prim` runs Prim's algorithm for -#' weighted graphs. If this is `NULL` then igraph will select the -#' algorithm automatically: if the graph has an edge attribute called -#' `weight` or the `weights` argument is not `NULL` then Prim's -#' algorithm is chosen, otherwise the unweighted algorithm is used. +#' @param weights Numeric vector giving the weights of the edges in the graph. +#' The order is determined by the edge IDs. +#' This is ignored if the `unweighted` algorithm is chosen. +#' Edge weights are interpreted as distances. +#' @param algorithm The algorithm to use for calculation. +#' `unweighted` can be used for unweighted graphs, +#' and `prim` runs Prim's algorithm for weighted graphs. +#' If this is `NULL` then igraph will select the algorithm automatically: +#' if the graph has an edge attribute called `weight` or the `weights` argument is not `NULL` then Prim's algorithm is chosen, +#' otherwise the unweighted algorithm is used. #' @param \dots Additional arguments, unused. -#' @return A graph object with the minimum spanning forest. To check whether it -#' is a tree, check that the number of its edges is `vcount(graph)-1`. -#' The edge and vertex attributes of the original graph are preserved in the -#' result. +#' @return A graph object with the minimum spanning forest. +#' To check whether it is a tree, check that the number of its edges is `vcount(graph)-1`. +#' The edge and vertex attributes of the original graph are preserved in the result. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @seealso [components()] #' @references Prim, R.C. 1957. Shortest connection networks and some diff --git a/R/motifs.R b/R/motifs.R index 97a526b2905..1e6ed07336c 100644 --- a/R/motifs.R +++ b/R/motifs.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `triad.census()` was renamed to [triad_census()] to create a more -#' consistent API. +#' `triad.census()` was renamed to [triad_census()] to create a more consistent API. #' @inheritParams triad_census #' @keywords internal #' @export @@ -19,8 +18,7 @@ triad.census <- function(graph) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.motifs.no()` was renamed to [count_motifs()] to create a more -#' consistent API. +#' `graph.motifs.no()` was renamed to [count_motifs()] to create a more consistent API. #' @inheritParams count_motifs #' @keywords internal #' @export @@ -35,11 +33,9 @@ graph.motifs.no <- function(graph, size = 3, cut.prob = rep(0, size)) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.motifs.est()` was renamed to [sample_motifs()] to create a more -#' consistent API. -#' @param cut.prob Numeric vector giving the probabilities that the search -#' graph is cut at a certain level. Its length should be the same as the size -#' of the motif (the `size` argument). +#' `graph.motifs.est()` was renamed to [sample_motifs()] to create a more consistent API. +#' @param cut.prob Numeric vector giving the probabilities that the search graph is cut at a certain level. +#' Its length should be the same as the size of the motif (the `size` argument). #' If `rep(0, size))`, the default, no cuts are made. #' @inheritParams sample_motifs #' @keywords internal @@ -67,11 +63,9 @@ graph.motifs.est <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.motifs()` was renamed to [motifs()] to create a more -#' consistent API. -#' @param cut.prob Numeric vector giving the probabilities that the search -#' graph is cut at a certain level. Its length should be the same as the size -#' of the motif (the `size` argument). +#' `graph.motifs()` was renamed to [motifs()] to create a more consistent API. +#' @param cut.prob Numeric vector giving the probabilities that the search graph is cut at a certain level. +#' Its length should be the same as the size of the motif (the `size` argument). #' If `rep(0, size))`, the default, no cuts are made. #' @inheritParams motifs #' @keywords internal @@ -87,8 +81,7 @@ graph.motifs <- function(graph, size = 3, cut.prob = rep(0, size)) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `dyad.census()` was renamed to [dyad_census()] to create a more -#' consistent API. +#' `dyad.census()` was renamed to [dyad_census()] to create a more consistent API. #' @inheritParams dyad_census #' @keywords internal #' @export @@ -121,40 +114,33 @@ dyad.census <- function(graph) { #' Graph motifs #' -#' Graph motifs are small connected induced subgraphs with a well-defined -#' structure. These functions search a graph for various motifs. +#' Graph motifs are small connected induced subgraphs with a well-defined structure. +#' These functions search a graph for various motifs. #' -#' `motifs()` searches a graph for motifs of a given size and returns a -#' numeric vector containing the number of different motifs. The order of -#' the motifs is defined by their isomorphism class, see -#' [isomorphism_class()]. +#' `motifs()` searches a graph for motifs of a given size and returns a numeric vector containing the number of different motifs. +#' The order of the motifs is defined by their isomorphism class, see [isomorphism_class()]. #' #' @param graph Graph object, the input graph. -#' @param size The size of the motif, currently sizes 3 and 4 are supported in -#' directed graphs and sizes 3 to 6 in undirected graphs. +#' @param size The size of the motif, currently sizes 3 and 4 are supported in directed graphs and sizes 3 to 6 in undirected graphs. #' @inheritParams rlang::args_dots_empty -#' @param cut.prob Numeric vector giving the probabilities that the search -#' graph is cut at a certain level. Its length should be the same as the size -#' of the motif (the `size` argument). +#' @param cut.prob Numeric vector giving the probabilities that the search graph is cut at a certain level. +#' Its length should be the same as the size of the motif (the `size` argument). #' If `NULL`, the default, no cuts are made. #' @param callback Optional callback function to call for each motif found. -#' The function should accept two arguments: `vids` (integer vector of vertex IDs -#' in the motif) and `isoclass` (the isomorphism class of the motif). +#' The function should accept two arguments: +#' `vids` (integer vector of vertex IDs in the motif) and `isoclass` (the isomorphism class of the motif). #' The function should return `FALSE` to continue the search or `TRUE` to stop it. #' If `NULL` (the default), motif counts are returned as a numeric vector. #' -#' **Important limitation:** Callback functions must NOT call any igraph -#' functions (including simple queries like `vcount()` or `ecount()`). Doing -#' so will cause R to crash due to reentrancy issues. Extract -#' any needed graph information before calling the function with a callback, or -#' use collector mode (the default) and process results afterward. -#' @return When `callback` is `NULL`, `motifs()` returns a numeric vector, -#' the number of occurrences of each motif in the graph. The motifs are ordered -#' by their isomorphism classes. Note that for unconnected subgraphs, which are -#' not considered to be motifs, the result will be `NA`. -#' -#' When `callback` is provided, the function returns `NULL` invisibly and calls -#' the callback function for each motif found. +#' **Important limitation:** Callback functions must NOT call any igraph functions (including simple queries like `vcount()` or `ecount()`). +#' Doing so will cause R to crash due to reentrancy issues. +#' Extract any needed graph information before calling the function with a callback, +#' or use collector mode (the default) and process results afterward. +#' @return When `callback` is `NULL`, `motifs()` returns a numeric vector, the number of occurrences of each motif in the graph. +#' The motifs are ordered by their isomorphism classes. +#' Note that for unconnected subgraphs, which are not considered to be motifs, the result will be `NA`. +#' +#' When `callback` is provided, the function returns `NULL` invisibly and calls the callback function for each motif found. #' @seealso [isomorphism_class()] #' #' @export @@ -246,18 +232,16 @@ motifs <- function( #' Graph motifs #' -#' Graph motifs are small connected induced subgraphs with a well-defined -#' structure. These functions search a graph for various motifs. +#' Graph motifs are small connected induced subgraphs with a well-defined structure. +#' These functions search a graph for various motifs. #' -#' `count_motifs()` calculates the total number of motifs of a given -#' size in graph. +#' `count_motifs()` calculates the total number of motifs of a given size in graph. #' #' @param graph Graph object, the input graph. #' @param size The size of the motif. #' @inheritParams rlang::args_dots_empty -#' @param cut.prob Numeric vector giving the probabilities that the search -#' graph is cut at a certain level. Its length should be the same as the size -#' of the motif (the `size` argument). +#' @param cut.prob Numeric vector giving the probabilities that the search graph is cut at a certain level. +#' Its length should be the same as the size of the motif (the `size` argument). #' If `NULL`, the default, no cuts are made. #' @return `count_motifs()` returns a numeric scalar. #' @seealso [isomorphism_class()] @@ -326,27 +310,23 @@ count_motifs <- function( #' Graph motifs #' -#' Graph motifs are small connected induced subgraphs with a well-defined -#' structure. These functions search a graph for various motifs. +#' Graph motifs are small connected induced subgraphs with a well-defined structure. +#' These functions search a graph for various motifs. #' -#' `sample_motifs()` estimates the total number of motifs of a given -#' size in a graph based on a sample. +#' `sample_motifs()` estimates the total number of motifs of a given size in a graph based on a sample. #' #' @param graph Graph object, the input graph. -#' @param size The size of the motif, currently size 3 and 4 are supported -#' in directed graphs and sizes 3-6 in undirected graphs. +#' @param size The size of the motif, currently size 3 and 4 are supported in directed graphs and sizes 3-6 in undirected graphs. #' @inheritParams rlang::args_dots_empty -#' @param cut.prob Numeric vector giving the probabilities that the search -#' graph is cut at a certain level. Its length should be the same as the size -#' of the motif (the `size` argument). +#' @param cut.prob Numeric vector giving the probabilities that the search graph is cut at a certain level. +#' Its length should be the same as the size of the motif (the `size` argument). #' If `NULL`, the default, no cuts are made. -#' @param sample.size The number of vertices to use as a starting point for -#' finding motifs. Only used if the `sample` argument is `NULL`. +#' @param sample.size The number of vertices to use as a starting point for finding motifs. +#' Only used if the `sample` argument is `NULL`. #' The default is `ceiling(vcount(graph) / 10)` . #' @param sample Vertices to use as a starting point for finding motifs. #' Default: `NULL`. -#' @return A numeric scalar, an estimate for the total number of motifs in -#' the graph. +#' @return A numeric scalar, an estimate for the total number of motifs in the graph. #' @seealso [isomorphism_class()] #' #' @export @@ -435,12 +415,13 @@ sample_motifs <- function( #' Dyad census of a graph #' -#' Classify dyads in a directed graphs. The relationship between each pair of -#' vertices is measured. It can be in three states: mutual, asymmetric or -#' non-existent. +#' Classify dyads in a directed graphs. +#' The relationship between each pair of vertices is measured. +#' It can be in three states: mutual, asymmetric or non-existent. #' #' -#' @param graph The input graph. A warning is given if it is not directed. +#' @param graph The input graph. +#' A warning is given if it is not directed. #' @return A named numeric vector with three elements: #' \describe{ #' \item{mut}{ @@ -454,8 +435,7 @@ sample_motifs <- function( #' } #' } #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso [triad_census()] for the same classification, but with -#' triples. +#' @seealso [triad_census()] for the same classification, but with triples. #' @references Holland, P.W. and Leinhardt, S. A Method for Detecting Structure #' in Sociometric Data. *American Journal of Sociology*, 76, 492--513. #' 1970. @@ -482,12 +462,10 @@ dyad_census <- function(graph) { #' Triad census, subgraphs with three vertices #' -#' This function counts the different induced subgraphs of three vertices in -#' a graph. +#' This function counts the different induced subgraphs of three vertices in a graph. #' #' Triad census was defined by David and Leinhardt (see References below). -#' Every triple of vertices (A, B, C) are classified into the 16 possible -#' states: +#' Every triple of vertices (A, B, C) are classified into the 16 possible states: #' \describe{ #' \item{003}{ #' A,B,C, the empty graph. @@ -539,13 +517,11 @@ dyad_census <- function(graph) { #' } #' } #' -#' This functions uses the RANDESU motif finder algorithm to find and count the -#' subgraphs, see [motifs()]. +#' This functions uses the RANDESU motif finder algorithm to find and count the subgraphs, see [motifs()]. #' -#' @param graph The input graph, it should be directed. An undirected graph -#' results a warning, and undefined results. -#' @return A numeric vector, the subgraph counts, in the order given in the -#' above description. +#' @param graph The input graph, it should be directed. +#' An undirected graph results a warning, and undefined results. +#' @return A numeric vector, the subgraph counts, in the order given in the above description. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @seealso [dyad_census()] for classifying binary relationships, #' [motifs()] for the underlying implementation. diff --git a/R/operators.R b/R/operators.R index e16c9378372..c544467272f 100644 --- a/R/operators.R +++ b/R/operators.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.intersection()` was renamed to [intersection()] to create a more -#' consistent API. +#' `graph.intersection()` was renamed to [intersection()] to create a more consistent API. #' @inheritParams intersection #' @keywords internal #' @export @@ -19,8 +18,7 @@ graph.intersection <- function(...) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.union()` was renamed to [union.igraph()] to create a more -#' consistent API. +#' `graph.union()` was renamed to [union.igraph()] to create a more consistent API. #' @inheritParams union.igraph #' @keywords internal #' @export @@ -35,8 +33,7 @@ graph.union <- function(..., byname = "auto") { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.difference()` was renamed to [difference()] to create a more -#' consistent API. +#' `graph.difference()` was renamed to [difference()] to create a more consistent API. #' @inheritParams difference #' @keywords internal #' @export @@ -51,8 +48,7 @@ graph.difference <- function(...) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.disjoint.union()` was renamed to [disjoint_union()] to create a more -#' consistent API. +#' `graph.disjoint.union()` was renamed to [disjoint_union()] to create a more consistent API. #' @inheritParams disjoint_union #' @keywords internal #' @export @@ -71,8 +67,7 @@ graph.disjoint.union <- function(...) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.compose()` was renamed to [compose()] to create a more -#' consistent API. +#' `graph.compose()` was renamed to [compose()] to create a more consistent API. #' @inheritParams compose #' @keywords internal #' @export @@ -87,8 +82,7 @@ graph.compose <- function(g1, g2, byname = "auto") { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.complementer()` was renamed to [complementer()] to create a more -#' consistent API. +#' `graph.complementer()` was renamed to [complementer()] to create a more consistent API. #' @inheritParams complementer #' @keywords internal #' @export @@ -203,11 +197,9 @@ combine.attrs <- function( attr } -# Historical behaviour for clashing attributes: a value present in a single -# input graph is copied as-is, otherwise each copy is kept side-by-side under a -# disambiguated `name_1`, `name_2`, ... name. Returns a named list to splice -# into the result; `getval` is the per-graph accessor closure from -# `combine.attrs()`. +# Historical behaviour for clashing attributes: a value present in a single input graph is copied as-is, +# otherwise each copy is kept side-by-side under a disambiguated `name_1`, `name_2`, ... name. +# Returns a named list to splice into the result; `getval` is the per-graph accessor closure from `combine.attrs()`. rename_attr_if_needed <- function(name, w, getval) { if (length(w) == 1) { stats::setNames(list(getval(w, name)), name) @@ -262,38 +254,33 @@ apply_one_combiner <- function(comb, x) { #' Disjoint union of graphs #' -#' The union of two or more graphs are created. The graphs are assumed to have -#' disjoint vertex sets. +#' The union of two or more graphs are created. +#' The graphs are assumed to have disjoint vertex sets. #' #' `disjoint_union()` creates a union of two or more disjoint graphs. -#' Thus first the vertices in the second, third, etc. graphs are relabeled to -#' have completely disjoint graphs. Then a simple union is created. This -#' function can also be used via the `%du%` operator. -#' -#' `disjoint_union()` handles graph, vertex and edge attributes. In -#' particular, it merges vertex and edge attributes using the [vctrs::vec_c()] -#' 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 -#' suffixes (`_1`, `_2`, ...). See [igraph-attribute-combination] for the -#' available combiners. -#' -#' Note that if both graphs have vertex names (i.e. a `name` vertex -#' attribute), then the concatenated vertex names might be non-unique in the -#' result. A warning is given if this happens. -#' -#' An error is generated if some input graphs are directed and others are -#' undirected. +#' Thus first the vertices in the second, third, etc. graphs are relabeled to have completely disjoint graphs. +#' Then a simple union is created. +#' This function can also be used via the `%du%` operator. +#' +#' `disjoint_union()` handles graph, vertex and edge attributes. +#' In particular, it merges vertex and edge attributes using the [vctrs::vec_c()] 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 suffixes (`_1`, `_2`, ...). +#' See [igraph-attribute-combination] for the available combiners. +#' +#' Note that if both graphs have vertex names (i.e. a `name` vertex attribute), +#' then the concatenated vertex names might be non-unique in the result. +#' A warning is given if this happens. +#' +#' An error is generated if some input graphs are directed and others are undirected. #' #' @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. -#' The default `NULL` uses the `graph.attr.comb` 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. +#' The default `NULL` uses the `graph.attr.comb` 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. #' @return A new graph object. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @export @@ -546,15 +533,12 @@ disjoint_union <- function( #' Union of two or more sets #' -#' This is an S3 generic function. See `methods("union")` -#' for the actual implementations for various S3 classes. Initially -#' it is implemented for igraph graphs and igraph vertex and edge -#' sequences. See -#' [union.igraph()], and -#' [union.igraph.vs()]. +#' This is an S3 generic function. +#' See `methods("union")` for the actual implementations for various S3 classes. +#' Initially it is implemented for igraph graphs and igraph vertex and edge sequences. +#' See [union.igraph()], and [union.igraph.vs()]. #' -#' @param ... Arguments, their number and interpretation depends on -#' the function that implements `union()`. +#' @param ... Arguments, their number and interpretation depends on the function that implements `union()`. #' @return Depends on the function that implements this method. #' #' @family functions for manipulating graph structure @@ -572,46 +556,39 @@ union.default <- function(...) { #' Union of graphs #' -#' The union of two or more graphs are created. The graphs may have identical -#' or overlapping vertex sets. +#' The union of two or more graphs are created. +#' The graphs may have identical or overlapping vertex sets. #' -#' `union()` creates the union of two or more graphs. Edges which are -#' included in at least one graph will be part of the new graph. This function -#' can be also used via the `%u%` operator. +#' `union()` creates the union of two or more graphs. +#' Edges which are included in at least one graph will be part of the new graph. +#' This function can be also used via the `%u%` operator. #' -#' If the `byname` argument is `TRUE` (or `auto` and all graphs -#' are named), then the operation is performed on symbolic vertex names instead -#' of the internal numeric vertex IDs. +#' If the `byname` argument is `TRUE` (or `auto` and all graphs are named), +#' then the operation is performed on symbolic vertex names instead of the internal numeric vertex IDs. #' -#' `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 -#' instead, e.g. by summing or by taking the first non-`NA` value. See -#' [igraph-attribute-combination] for the available combiners. +#' `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 instead, +#' e.g. by summing or by taking the first non-`NA` value. +#' See [igraph-attribute-combination] for the available combiners. #' -#' The `name` vertex attribute is treated specially if the operation is -#' performed based on symbolic vertex names. In this case `name` must be -#' present in all graphs, and it is not renamed in the result graph. +#' The `name` vertex attribute is treated specially if the operation is performed based on symbolic vertex names. +#' In this case `name` must be present in all graphs, and it is not renamed in the result graph. #' -#' An error is generated if some input graphs are directed and others are -#' undirected. +#' An error is generated if some input graphs are directed and others are undirected. #' #' @aliases %u% #' @param \dots Graph objects or lists of graph objects. -#' @param byname A Logical, or the character scalar `auto`. Whether -#' to perform the operation based on symbolic vertex names. If it is -#' `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 -#' [igraph_options()]). `"rename"` preserves the historical behaviour of -#' appending `_1`, `_2`, ... suffixes. See [igraph-attribute-combination] for -#' the available combiners. +#' @param byname A Logical, or the character scalar `auto`. +#' Whether to perform the operation based on symbolic vertex names. +#' If it is `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 [igraph_options()]). +#' `"rename"` preserves the historical behaviour of appending `_1`, `_2`, ... suffixes. +#' See [igraph-attribute-combination] for the available combiners. #' @return A new graph object. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @method union igraph @@ -653,15 +630,12 @@ union.igraph <- function( #' Intersection of two or more sets #' -#' This is an S3 generic function. See `methods("intersection")` -#' for the actual implementations for various S3 classes. Initially -#' it is implemented for igraph graphs and igraph vertex and edge -#' sequences. See -#' [intersection.igraph()], and -#' [intersection.igraph.vs()]. +#' This is an S3 generic function. +#' See `methods("intersection")` for the actual implementations for various S3 classes. +#' Initially it is implemented for igraph graphs and igraph vertex and edge sequences. +#' See [intersection.igraph()], and [intersection.igraph.vs()]. #' -#' @param ... Arguments, their number and interpretation depends on -#' the function that implements `intersection()`. +#' @param ... Arguments, their number and interpretation depends on the function that implements `intersection()`. #' @return Depends on the function that implements this method. #' #' @family functions for manipulating graph structure @@ -672,47 +646,37 @@ intersection <- function(...) { #' Intersection of graphs #' -#' The intersection of two or more graphs are created. The graphs may have -#' identical or overlapping vertex sets. +#' The intersection of two or more graphs are created. +#' The graphs may have identical or overlapping vertex sets. #' -#' `intersection()` creates the intersection of two or more graphs: -#' only edges present in all graphs will be included. The corresponding -#' operator is `%s%`. +#' `intersection()` creates the intersection of two or more graphs: only edges present in all graphs will be included. +#' The corresponding operator is `%s%`. #' -#' If the `byname` argument is `TRUE` (or `auto` and all graphs -#' are named), then the operation is performed on symbolic vertex names instead -#' of the internal numeric vertex IDs. +#' If the `byname` argument is `TRUE` (or `auto` and all graphs are named), +#' then the operation is performed on symbolic vertex names instead of the internal numeric vertex IDs. #' -#' `intersection()` 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 instead; see [igraph-attribute-combination] for the -#' available combiners. +#' `intersection()` 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 instead; +#' see [igraph-attribute-combination] for the available combiners. #' -#' The `name` vertex attribute is treated specially if the operation is -#' performed based on symbolic vertex names. In this case `name` must be -#' present in all graphs, and it is not renamed in the result graph. +#' The `name` vertex attribute is treated specially if the operation is performed based on symbolic vertex names. +#' In this case `name` must be present in all graphs, and it is not renamed in the result graph. #' -#' An error is generated if some input graphs are directed and others are -#' undirected. +#' An error is generated if some input graphs are directed and others are undirected. #' #' @aliases %s% #' @param \dots Graph objects or lists of graph objects. -#' @param byname A Logical, or the character scalar `auto`. Whether -#' to perform the operation based on symbolic vertex names. If it is -#' `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 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 -#' [igraph_options()]). See [igraph-attribute-combination] for the available -#' combiners. +#' @param byname A Logical, or the character scalar `auto`. +#' Whether to perform the operation based on symbolic vertex names. +#' If it is `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 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 [igraph_options()]). +#' See [igraph-attribute-combination] for the available combiners. #' @return A new graph object. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @method intersection igraph @@ -755,15 +719,12 @@ intersection.igraph <- function( #' Difference of two sets #' -#' This is an S3 generic function. See `methods("difference")` -#' for the actual implementations for various S3 classes. Initially -#' it is implemented for igraph graphs (difference of edges in two graphs), -#' and igraph vertex and edge sequences. See -#' [difference.igraph()], and -#' [difference.igraph.vs()]. +#' This is an S3 generic function. +#' See `methods("difference")` for the actual implementations for various S3 classes. +#' Initially it is implemented for igraph graphs (difference of edges in two graphs), and igraph vertex and edge sequences. +#' See [difference.igraph()], and [difference.igraph.vs()]. #' -#' @param ... Arguments, their number and interpretation depends on -#' the function that implements `difference()`. +#' @param ... Arguments, their number and interpretation depends on the function that implements `difference()`. #' @return Depends on the function that implements this method. #' #' @family functions for manipulating graph structure @@ -777,30 +738,27 @@ difference <- function(...) { #' #' The difference of two graphs are created. #' -#' `difference()` creates the difference of two graphs. Only edges -#' present in the first graph but not in the second will be be included in the -#' new graph. The corresponding operator is `%m%`. +#' `difference()` creates the difference of two graphs. +#' Only edges present in the first graph but not in the second will be be included in the new graph. +#' The corresponding operator is `%m%`. #' -#' If the `byname` argument is `TRUE` (or `auto` and the graphs -#' are all named), then the operation is performed based on symbolic vertex -#' names. Otherwise numeric vertex IDs are used. +#' If the `byname` argument is `TRUE` (or `auto` and the graphs are all named), +#' then the operation is performed based on symbolic vertex names. +#' Otherwise numeric vertex IDs are used. #' -#' `difference()` keeps all attributes (graph, vertex and edge) of the -#' first graph. +#' `difference()` keeps all attributes (graph, vertex and edge) of the first graph. #' -#' Note that `big` and `small` must both be directed or both be -#' undirected, otherwise an error message is given. +#' Note that `big` and `small` must both be directed or both be undirected, otherwise an error message is given. #' #' @aliases %m% -#' @param big The left hand side argument of the minus operator. A directed or -#' undirected graph. -#' @param small The right hand side argument of the minus operator. A directed -#' ot undirected graph. -#' @param byname A Logical, or the character scalar `auto`. Whether -#' to perform the operation based on symbolic vertex names. If it is -#' `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 big The left hand side argument of the minus operator. +#' A directed or undirected graph. +#' @param small The right hand side argument of the minus operator. +#' A directed ot undirected graph. +#' @param byname A Logical, or the character scalar `auto`. +#' Whether to perform the operation based on symbolic vertex names. +#' If it is `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 ... Ignored, included for S3 compatibility. #' @return A new graph object. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} @@ -870,15 +828,12 @@ difference.igraph <- function(big, small, byname = "auto", ...) { #' Complementer of a graph #' -#' A complementer graph contains all edges that were not present in the input -#' graph. +#' A complementer graph contains all edges that were not present in the input graph. #' -#' `complementer()` creates the complementer of a graph. Only edges -#' which are *not* present in the original graph will be included in the -#' new graph. +#' `complementer()` creates the complementer of a graph. +#' Only edges which are *not* present in the original graph will be included in the new graph. #' -#' `complementer()` keeps graph and vertex attriubutes, edge -#' attributes are lost. +#' `complementer()` keeps graph and vertex attriubutes, edge attributes are lost. #' #' @param graph The input graph, can be directed or undirected. #' @inheritParams rlang::args_dots_empty @@ -951,59 +906,51 @@ complementer <- function( #' #' Relational composition of two graph. #' -#' `compose()` creates the relational composition of two graphs. The -#' new graph will contain an (a,b) edge only if there is a vertex c, such that -#' edge (a,c) is included in the first graph and (c,b) is included in the -#' second graph. The corresponding operator is `%c%`. +#' `compose()` creates the relational composition of two graphs. +#' The new graph will contain an (a,b) edge only if there is a vertex c, +#' such that edge (a,c) is included in the first graph and (c,b) is included in the second graph. +#' The corresponding operator is `%c%`. #' -#' The function gives an error if one of the input graphs is directed and the -#' other is undirected. +#' The function gives an error if one of the input graphs is directed and the other is undirected. #' -#' If the `byname` argument is `TRUE` (or `auto` and the graphs -#' are all named), then the operation is performed based on symbolic vertex -#' names. Otherwise numeric vertex IDs are used. +#' If the `byname` argument is `TRUE` (or `auto` and the graphs are all named), +#' then the operation is performed based on symbolic vertex names. +#' Otherwise numeric vertex IDs are used. #' -#' `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 -#' instead; see [igraph-attribute-combination] for the available combiners. +#' `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 instead; +#' see [igraph-attribute-combination] for the available combiners. #' -#' The `name` vertex attribute is treated specially if the operation is -#' performed based on symbolic vertex names. In this case `name` must be -#' present in both graphs, and it is not renamed in the result graph. +#' The `name` vertex attribute is treated specially if the operation is performed based on symbolic vertex names. +#' In this case `name` must be present in both graphs, and it is not renamed in the result graph. #' -#' Note that an edge in the result graph corresponds to two edges in the input, -#' one in the first graph, one in the second. This mapping is not injective and -#' several edges in the result might correspond to the same edge in the first -#' (and/or the second) graph. The edge attributes in the result graph are -#' updated accordingly. +#' Note that an edge in the result graph corresponds to two edges in the input, one in the first graph, one in the second. +#' This mapping is not injective and several edges in the result might correspond to the same edge in the first (and/or the second) graph. +#' The edge attributes in the result graph are updated accordingly. #' -#' Also note that the function may generate multigraphs, if there are more than -#' one way to find edges (a,b) in g1 and (b,c) in g2 for an edge (a,c) in the -#' result. See [simplify()] if you want to get rid of the multiple -#' edges. +#' Also note that the function may generate multigraphs, +#' if there are more than one way to find edges (a,b) in g1 and (b,c) in g2 for an edge (a,c) in the result. +#' See [simplify()] if you want to get rid of the multiple edges. #' -#' The function may create loop edges, if edges (a,b) and (b,a) are present in -#' g1 and g2, respectively, then (a,a) is included in the result. See -#' [simplify()] if you want to get rid of the self-loops. +#' The function may create loop edges, if edges (a,b) and (b,a) are present in g1 and g2, respectively, +#' then (a,a) is included in the result. +#' See [simplify()] if you want to get rid of the self-loops. #' #' @aliases %c% #' @param g1 The first input graph. #' @param g2 The second input graph. #' @inheritParams rlang::args_dots_empty -#' @param byname A Logical, or the character scalar `auto`. Whether -#' to perform the operation based on symbolic vertex names. If it is -#' `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 -#' [igraph_options()]). See [igraph-attribute-combination] for the available -#' combiners. +#' @param byname A Logical, or the character scalar `auto`. +#' Whether to perform the operation based on symbolic vertex names. +#' If it is `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 [igraph_options()]). +#' See [igraph-attribute-combination] for the available combiners. #' @return A new graph object. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @family functions for manipulating graph structure @@ -1168,25 +1115,19 @@ compose <- function( #' Helper function for adding and deleting edges #' -#' This is a helper function that simplifies adding and deleting -#' edges to/from graphs. +#' This is a helper function that simplifies adding and deleting edges to/from graphs. #' #' `edges()` is an alias for `edge()`. #' #' @details -#' When adding edges via `+`, all unnamed arguments of -#' `edge()` (or `edges()`) are concatenated, and then passed to -#' [add_edges()]. They are interpreted as pairs of vertex IDs, -#' and an edge will added between each pair. Named arguments will be -#' used as edge attributes for the new edges. +#' When adding edges via `+`, all unnamed arguments of `edge()` (or `edges()`) are concatenated, and then passed to [add_edges()]. +#' They are interpreted as pairs of vertex IDs, and an edge will added between each pair. +#' Named arguments will be used as edge attributes for the new edges. #' -#' When deleting edges via `-`, all arguments of `edge()` (or -#' `edges()`) are concatenated via `c()` and passed to -#' [delete_edges()]. +#' When deleting edges via `-`, all arguments of `edge()` (or `edges()`) are concatenated via `c()` and passed to [delete_edges()]. #' #' @param ... See details below. -#' @return A special object that can be used with together with -#' igraph graphs and the plus and minus operators. +#' @return A special object that can be used with together with igraph graphs and the plus and minus operators. #' #' @family functions for manipulating graph structure #' @@ -1217,23 +1158,19 @@ edges <- edge #' Helper function for adding and deleting vertices #' -#' This is a helper function that simplifies adding and deleting -#' vertices to/from graphs. +#' This is a helper function that simplifies adding and deleting vertices to/from graphs. #' #' `vertices()` is an alias for `vertex()`. #' #' @details -#' When adding vertices via `+`, all unnamed arguments are interpreted -#' as vertex names of the new vertices. Named arguments are interpreted as -#' vertex attributes for the new vertices. +#' When adding vertices via `+`, all unnamed arguments are interpreted as vertex names of the new vertices. +#' Named arguments are interpreted as vertex attributes for the new vertices. #' -#' When deleting vertices via `-`, all arguments of `vertex()` (or -#' `vertices()`) are concatenated via `c()` and passed to -#' [delete_vertices()]. +#' When deleting vertices via `-`, +#' all arguments of `vertex()` (or `vertices()`) are concatenated via `c()` and passed to [delete_vertices()]. #' #' @param ... See details below. -#' @return A special object that can be used with together with -#' igraph graphs and the plus and minus operators. +#' @return A special object that can be used with together with igraph graphs and the plus and minus operators. #' #' @family functions for manipulating graph structure #' @@ -1270,19 +1207,15 @@ vertices <- vertex #' This function can be used to add or delete edges that form a path. #' #' @details -#' When adding edges via `+`, all unnamed arguments are -#' concatenated, and each element of a final vector is interpreted -#' as a vertex in the graph. For a vector of length \eqn{n+1}, \eqn{n} -#' edges are then added, from vertex 1 to vertex 2, from vertex 2 to vertex -#' 3, etc. Named arguments will be used as edge attributes for the new -#' edges. +#' When adding edges via `+`, all unnamed arguments are concatenated, +#' and each element of a final vector is interpreted as a vertex in the graph. +#' For a vector of length \eqn{n+1}, \eqn{n} edges are then added, from vertex 1 to vertex 2, from vertex 2 to vertex 3, +#' etc. Named arguments will be used as edge attributes for the new edges. #' -#' When deleting edges, all attributes are concatenated and then passed -#' to [delete_edges()]. +#' When deleting edges, all attributes are concatenated and then passed to [delete_edges()]. #' #' @param ... See details below. -#' @return A special object that can be used together with igraph -#' graphs and the plus and minus operators. +#' @return A special object that can be used together with igraph graphs and the plus and minus operators. #' #' @family functions for manipulating graph structure #' @@ -1311,8 +1244,7 @@ path <- function(...) { #' #' @details #' The plus operator can be used to add vertices or edges to graph. -#' The actual operation that is performed depends on the type of the -#' right hand side argument. +#' The actual operation that is performed depends on the type of the right hand side argument. #' #' - If is is another igraph graph object and they are both #' named graphs, then the union of the two graphs are calculated, @@ -1325,11 +1257,9 @@ path <- function(...) { #' - If it is a character scalar or vector, then it is interpreted as #' the names of the vertices to add to the graph. #' - If it is an object created with the [vertex()] or -#' [vertices()] function, then new vertices are added to the -#' graph. This form is appropriate when one wants to add some vertex -#' attributes as well. The operands of the `vertices()` function -#' specifies the number of vertices to add and their attributes as -#' well. +#' [vertices()] function, then new vertices are added to the graph. +#' This form is appropriate when one wants to add some vertex attributes as well. +#' The operands of the `vertices()` function specifies the number of vertices to add and their attributes as well. #' #' The unnamed arguments of `vertices()` are concatenated and #' used as the \sQuote{`name`} vertex attribute (i.e. vertex @@ -1340,18 +1270,15 @@ path <- function(...) { #' g <- g + vertex("bar", "foobar") #' g <- g + vertices("bar2", "foobar2", color=1:2, shape="rectangle")} #' -#' `vertex()` is just an alias to `vertices()`, and it is -#' provided for readability. The user should use it if a single vertex -#' is added to the graph. +#' `vertex()` is just an alias to `vertices()`, and it is provided for readability. +#' The user should use it if a single vertex is added to the graph. #' #' - If it is an object created with the [edge()] or -#' [edges()] function, then new edges will be added to the -#' graph. The new edges and possibly their attributes can be specified as -#' the arguments of the `edges()` function. +#' [edges()] function, then new edges will be added to the graph. +#' The new edges and possibly their attributes can be specified as the arguments of the `edges()` function. #' -#' The unnamed arguments of `edges()` are concatenated and used -#' as vertex IDs of the end points of the new edges. The named -#' arguments will be added as edge attributes. +#' The unnamed arguments of `edges()` are concatenated and used as vertex IDs of the end points of the new edges. +#' The named arguments will be added as edge attributes. #' #' Examples: \preformatted{ g <- make_empty_graph() + #' vertices(letters[1:10]) + @@ -1361,16 +1288,14 @@ path <- function(...) { #' g <- g + edges(c("bar", "foo", "foobar2", "bar2"), color="red", weight=1:2)} #' See more examples below. #' -#' `edge()` is just an alias to `edges()` and it is provided -#' for readability. The user should use it if a single edge is added to -#' the graph. +#' `edge()` is just an alias to `edges()` and it is provided for readability. +#' The user should use it if a single edge is added to the graph. #' #' - If it is an object created with the [path()] function, then -#' new edges that form a path are added. The edges and possibly their -#' attributes are specified as the arguments to the `path()` -#' function. The non-named arguments are concatenated and interpreted -#' as the vertex IDs along the path. The remaining arguments are added -#' as edge attributes. +#' new edges that form a path are added. +#' The edges and possibly their attributes are specified as the arguments to the `path()` function. +#' The non-named arguments are concatenated and interpreted as the vertex IDs along the path. +#' The remaining arguments are added as edge attributes. #' #' Examples: \preformatted{ g <- make_empty_graph() + vertices(letters[1:10]) #' g <- g + path("a", "b", "c", "d") @@ -1384,8 +1309,7 @@ path <- function(...) { #' For clarity, we suggest to always put the graph object on the left #' hand side of the operator: \preformatted{ graph <- make_empty_graph() + "foo" + "bar"} #' -#' @param e1 First argument, probably an igraph graph, but see details -#' below. +#' @param e1 First argument, probably an igraph graph, but see details below. #' @param e2 Second argument, see details below. #' #' @family functions for manipulating graph structure @@ -1475,9 +1399,8 @@ path <- function(...) { #' Delete vertices or edges from a graph #' #' @details -#' The minus operator (\sQuote{`-`}) can be used to remove vertices -#' or edges from the graph. The operation performed is selected based on -#' the type of the right hand side argument: +#' The minus operator (\sQuote{`-`}) can be used to remove vertices or edges from the graph. +#' The operation performed is selected based on the type of the right hand side argument: #' \itemize{ #' \item If it is an igraph graph object, then the difference of the #' two graphs is calculated, see [difference()]. @@ -1486,19 +1409,13 @@ path <- function(...) { #' deleted from the graph. Example: \preformatted{ g <- make_ring(10) #' V(g)$name <- letters[1:10] #' g <- g - c("a", "b")} -#' \item If `e2` is a vertex sequence (e.g. created by the -#' [V()] function), then these vertices will be deleted from -#' the graph. -#' \item If it is an edge sequence (e.g. created by the [E()] -#' function), then these edges will be deleted from the graph. -#' \item If it is an object created with the [vertex()] (or the -#' [vertices()]) function, then all arguments of [vertices()] are -#' concatenated and the result is interpreted as a vector of vertex -#' IDs. These vertices will be removed from the graph. -#' \item If it is an object created with the [edge()] (or the -#' [edges()]) function, then all arguments of [edges()] are -#' concatenated and then interpreted as edges to be removed from the -#' graph. +#' \item If `e2` is a vertex sequence (e.g. created by the [V()] function), then these vertices will be deleted from the graph. +#' \item If it is an edge sequence (e.g. created by the [E()] function), then these edges will be deleted from the graph. +#' \item If it is an object created with the [vertex()] (or the [vertices()]) function, then all arguments of [vertices()] are concatenated +#' and the result is interpreted as a vector of vertex IDs. +#' These vertices will be removed from the graph. +#' \item If it is an object created with the [edge()] (or the [edges()]) function, then all arguments of [edges()] are concatenated and +#' then interpreted as edges to be removed from the graph. #' Example: \preformatted{ g <- make_ring(10) #' V(g)$name <- letters[1:10] #' E(g)$name <- LETTERS[1:10] @@ -1556,14 +1473,12 @@ path <- function(...) { #' Replicate a graph multiple times #' -#' The new graph will contain the input graph the given number -#' of times, as unconnected components. +#' The new graph will contain the input graph the given number of times, as unconnected components. #' #' @param x The input graph. #' @param n Number of times to replicate it. #' @param mark Whether to mark the vertices with a `which` attribute, -#' an integer number denoting which replication the vertex is coming -#' from. +#' an integer number denoting which replication the vertex is coming from. #' @param ... Additional arguments to satisfy S3 requirements, #' currently ignored. #' @@ -1608,16 +1523,14 @@ rep.igraph <- function(x, n, mark = TRUE, ...) { #' Reverse edges in a graph #' -#' The new graph will contain the same vertices, edges and attributes as -#' the original graph, except that the direction of the edges selected by -#' their edge IDs in the `eids` argument will be reversed. When reversing -#' all edges, this operation is also known as graph transpose. +#' The new graph will contain the same vertices, edges and attributes as the original graph, +#' except that the direction of the edges selected by their edge IDs in the `eids` argument will be reversed. +#' When reversing all edges, this operation is also known as graph transpose. #' #' @param graph The input graph. -#' @param eids The edge IDs of the edges to reverse. The default `NULL` -#' reverses all edges. -#' @return The result graph where the direction of the edges with the given -#' IDs are reversed +#' @param eids The edge IDs of the edges to reverse. +#' The default `NULL` reverses all edges. +#' @return The result graph where the direction of the edges with the given IDs are reversed #' #' @examples #' diff --git a/R/other.R b/R/other.R index de822b9edbf..a36615a597f 100644 --- a/R/other.R +++ b/R/other.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `running.mean()` was renamed to [running_mean()] to create a more -#' consistent API. +#' `running.mean()` was renamed to [running_mean()] to create a more consistent API. #' @inheritParams running_mean #' @keywords internal #' @export @@ -19,8 +18,7 @@ running.mean <- function(v, binwidth) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `igraph.sample()` was renamed to [sample_seq()] to create a more -#' consistent API. +#' `igraph.sample()` was renamed to [sample_seq()] to create a more consistent API. #' @inheritParams sample_seq #' @keywords internal #' @export @@ -35,8 +33,7 @@ igraph.sample <- function(low, high, length) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `convex.hull()` was renamed to [convex_hull()] to create a more -#' consistent API. +#' `convex.hull()` was renamed to [convex_hull()] to create a more consistent API. #' @inheritParams convex_hull #' @keywords internal #' @export @@ -68,13 +65,11 @@ convex.hull <- function(data) { #' Running mean of a time series #' -#' `running_mean()` calculates the running mean in a vector with the given -#' bin width. +#' `running_mean()` calculates the running mean in a vector with the given bin width. #' -#' The running mean of `v` is a `w` vector of length -#' `length(v)-binwidth+1`. The first element of `w` ID the average of -#' the first `binwidth` elements of `v`, the second element of -#' `w` is the average of elements `2:(binwidth+1)`, etc. +#' The running mean of `v` is a `w` vector of length `length(v)-binwidth+1`. +#' The first element of `w` ID the average of the first `binwidth` elements of `v`, +#' the second element of `w` is the average of elements `2:(binwidth+1)`, etc. #' #' @param v The numeric vector. #' @param binwidth Numeric constant, the size of the bin, should be meaningful, @@ -104,12 +99,10 @@ running_mean <- function(v, binwidth) { #' Sampling a random integer sequence #' -#' This function provides a very efficient way to pull an integer random sample -#' sequence from an integer interval. +#' This function provides a very efficient way to pull an integer random sample sequence from an integer interval. #' -#' The algorithm runs in `O(length)` expected time, even if -#' `high-low` is big. It is much faster (but of course less general) than -#' the builtin `sample` function of R. +#' The algorithm runs in `O(length)` expected time, even if `high-low` is big. +#' It is much faster (but of course less general) than the builtin `sample` function of R. #' #' @param low The lower limit of the interval (inclusive). #' @param high The higher limit of the interval (inclusive). @@ -137,19 +130,16 @@ sample_seq <- function(low, high, length) { #' Common handler for vertex type arguments in igraph functions #' -#' This function takes the `types` and `graph` arguments from a -#' public igraph function call and validates the vertex type vector. +#' This function takes the `types` and `graph` arguments from a public igraph function call and validates the vertex type vector. #' -#' When the provided vertex types are NULL and the graph has a `types` -#' vertex attribute, then the value of this vertex attribute will be used as -#' vertex types. Non-logical vertex type vectors are coerced into logical -#' vectors after printing a warning. +#' When the provided vertex types are NULL and the graph has a `types` vertex attribute, +#' then the value of this vertex attribute will be used as vertex types. +#' Non-logical vertex type vectors are coerced into logical vectors after printing a warning. #' #' @param types the vertex types #' @param graph the graph #' @param required whether the graph has to be bipartite -#' @return A logical vector representing the resolved vertex type for each -#' vertex in the graph +#' @return A logical vector representing the resolved vertex type for each vertex in the graph #' @author Tamas Nepusz \email{ntamas@@gmail.com} #' @dev #' @@ -201,8 +191,7 @@ igraph.i.spMatrix <- function(M) { #' Convex hull of a set of vertices #' -#' Calculate the convex hull of a set of points, i.e. the covering polygon that -#' has the smallest area. +#' Calculate the convex hull of a set of points, i.e. the covering polygon that has the smallest area. #' #' #' @param data The data points, a numeric matrix with two columns. diff --git a/R/palette.R b/R/palette.R index 2063fbad590..18c9049f95d 100644 --- a/R/palette.R +++ b/R/palette.R @@ -23,14 +23,13 @@ #' Palette for categories #' -#' This is a color blind friendly palette from -#' . It has 8 colors. +#' This is a color blind friendly palette from . +#' It has 8 colors. #' -#' This is the suggested palette for visualizations where vertex colors -#' mark categories, e.g. community membership. +#' This is the suggested palette for visualizations where vertex colors mark categories, e.g. community membership. #' -#' @param n The number of colors in the palette. We simply take the first -#' `n` colors from the total 8. +#' @param n The number of colors in the palette. +#' We simply take the first `n` colors from the total 8. #' @return A character vector of RGB color codes. #' #' @section Examples: @@ -79,12 +78,11 @@ categorical_pal <- function(n) { #' This is the \sQuote{OrRd} palette from . #' It has at most nine colors. #' -#' Use this palette, if vertex colors mark some ordinal quantity, e.g. some -#' centrality measure, or some ordinal vertex covariate, like the age of -#' people, or their seniority level. +#' Use this palette, if vertex colors mark some ordinal quantity, e.g. some centrality measure, or some ordinal vertex covariate, +#' like the age of people, or their seniority level. #' -#' @param n The number of colors in the palette. The maximum is nine -#' currently. +#' @param n The number of colors in the palette. +#' The maximum is nine currently. #' @return A character vector of RGB color codes. #' #' @family palettes @@ -155,13 +153,11 @@ sequential_pal <- function(n) { #' This is the \sQuote{PuOr} palette from . #' It has at most eleven colors. #' -#' This is similar to [sequential_pal()], but it also puts -#' emphasis on the mid-range values, plus the the two extreme ends. -#' Use this palette, if you have such a quantity to mark with vertex -#' colors. +#' This is similar to [sequential_pal()], but it also puts emphasis on the mid-range values, plus the the two extreme ends. +#' Use this palette, if you have such a quantity to mark with vertex colors. #' -#' @param n The number of colors in the palette. The maximum is eleven -#' currently. +#' @param n The number of colors in the palette. +#' The maximum is eleven currently. #' @return A character vector of RGB color codes. #' #' @family palettes @@ -265,9 +261,8 @@ diverging_pal <- function(n) { #' The default R palette #' -#' This is the default R palette, to be able to reproduce the -#' colors of older igraph versions. Its colors are appropriate -#' for categories, but they are not very attractive. +#' This is the default R palette, to be able to reproduce the colors of older igraph versions. +#' Its colors are appropriate for categories, but they are not very attractive. #' #' @param n The number of colors to use, the maximum is eight. #' @return A character vector of color names. diff --git a/R/par.R b/R/par.R index 0091dacfc6c..6f9493c49c8 100644 --- a/R/par.R +++ b/R/par.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `igraph.options()` was renamed to [igraph_options()] to create a more -#' consistent API. +#' `igraph.options()` was renamed to [igraph_options()] to create a more consistent API. #' @inheritParams igraph_options #' @keywords internal #' @export @@ -19,8 +18,7 @@ igraph.options <- function(...) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `getIgraphOpt()` was renamed to [igraph_opt()] to create a more -#' consistent API. +#' `getIgraphOpt()` was renamed to [igraph_opt()] to create a more consistent API. #' @inheritParams igraph_opt #' @keywords internal #' @export @@ -104,17 +102,14 @@ igraph.pars.callbacks <- list("verbose" = igraph.pars.set.verbose) #' Parameters for the igraph package #' -#' igraph has some parameters which (usually) affect the behavior of many -#' functions. These can be set for the whole session via `igraph_options()`. +#' igraph has some parameters which (usually) affect the behavior of many functions. +#' These can be set for the whole session via `igraph_options()`. #' -#' The parameter values set via a call to the `igraph_options()` function -#' will remain in effect for the rest of the session, affecting the subsequent -#' behaviour of the other functions of the `igraph` package for which the -#' given parameters are relevant. +#' The parameter values set via a call to the `igraph_options()` function will remain in effect for the rest of the session, +#' affecting the subsequent behaviour of the other functions of the `igraph` package for which the given parameters are relevant. #' -#' This offers the possibility of customizing the functioning of the -#' `igraph` package, for instance by insertions of appropriate calls to -#' `igraph_options()` in a load hook for package \pkg{igraph}. +#' This offers the possibility of customizing the functioning of the `igraph` package, +#' for instance by insertions of appropriate calls to `igraph_options()` in a load hook for package \pkg{igraph}. #' #' The currently used parameters in alphabetical order: #' \describe{ @@ -145,10 +140,9 @@ igraph.pars.callbacks <- list("verbose" = igraph.pars.set.verbose) #' See [attribute.combination()] for details on this. #' } #' \item{graph.attr.comb}{ -#' 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 -#' name clash by appending `_1`, `_2`, ... suffixes. +#' 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 name clash by appending `_1`, `_2`, ... suffixes. #' See [attribute.combination()] for details on this. #' } #' \item{print.edge.attributes}{ @@ -166,12 +160,9 @@ igraph.pars.callbacks <- list("verbose" = igraph.pars.set.verbose) #' Logical constant, whether to print vertex attributes when printing graphs. Defaults to `FALSE`. #' } #' \item{print.style}{ -#' Character string controlling the visual style used by -#' [print.igraph()], [summary.igraph()], [print.igraph.vs()] and -#' [print.igraph.es()]. Possible values are `"cli"` (default, a -#' cli-styled output with section rules, Unicode arrows for edges and -#' typed attribute listings) and `"classic"` (the historical -#' `IGRAPH ... DNW-` header relied on by tutorials and parsers). +#' Character string controlling the visual style used by [print.igraph()], [summary.igraph()], [print.igraph.vs()] +#' and [print.igraph.es()]. +#' Possible values are `"cli"` (default, a cli-styled output with section rules, Unicode arrows for edges and typed attribute listings) and `"classic"` (the historical `IGRAPH ... DNW-` header relied on by tutorials and parsers). #' } #' \item{return.vs.es}{ #' Whether functions that return a set or sequence of vertices/edges @@ -195,14 +186,14 @@ igraph.pars.callbacks <- list("verbose" = igraph.pars.set.verbose) #' } #' } #' -#' @param \dots A list may be given as the only argument, or any number of -#' arguments may be in the `name=value` form, or no argument at all may be -#' given. See the Value and Details sections for explanation. +#' @param \dots A list may be given as the only argument, or any number of arguments may be in the `name=value` form, +#' or no argument at all may be given. +#' See the Value and Details sections for explanation. #' @return A list with the old values of the updated parameters, invisibly. #' Without any arguments, it returns the values of all options. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso Similar to [options()]. See [igraph_opt()] to retrieve the -#' value of a single option. +#' @seealso Similar to [options()]. +#' See [igraph_opt()] to retrieve the value of a single option. #' @keywords graphs #' @examples #' @@ -287,18 +278,16 @@ get_all_options <- function() { #' Query a single igraph parameter #' -#' Retrieve the current value of one igraph option set via -#' [igraph_options()]. +#' Retrieve the current value of one igraph option set via [igraph_options()]. #' #' @param x A character string holding an option name. #' @inheritParams rlang::args_dots_empty -#' @param default If the specified option is not set in the options list, this -#' value is returned. This facilitates retrieving an option and checking -#' whether it is set and setting it separately if not. -#' @return The current value set for option `x`, or `NULL` if the option is -#' unset. +#' @param default If the specified option is not set in the options list, this value is returned. +#' This facilitates retrieving an option and checking whether it is set and setting it separately if not. +#' @return The current value set for option `x`, or `NULL` if the option is unset. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso Similar to [getOption()]. See [igraph_options()] to set options. +#' @seealso Similar to [getOption()]. +#' See [igraph_options()] to set options. #' @keywords graphs #' @examples #' oldval <- igraph_opt("verbose") diff --git a/R/paths.R b/R/paths.R index 5ee7971e8ed..7790d4aa705 100644 --- a/R/paths.R +++ b/R/paths.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `path.length.hist()` was renamed to [distance_table()] to create a more -#' consistent API. +#' `path.length.hist()` was renamed to [distance_table()] to create a more consistent API. #' @inheritParams distance_table #' @keywords internal #' @export @@ -19,8 +18,7 @@ path.length.hist <- function(graph, directed = TRUE) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `maximum.cardinality.search()` was renamed to [max_cardinality()] to create a more -#' consistent API. +#' `maximum.cardinality.search()` was renamed to [max_cardinality()] to create a more consistent API. #' @inheritParams max_cardinality #' @keywords internal #' @export @@ -39,8 +37,7 @@ maximum.cardinality.search <- function(graph) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `is.dag()` was renamed to [is_dag()] to create a more -#' consistent API. +#' `is.dag()` was renamed to [is_dag()] to create a more consistent API. #' @inheritParams is_dag #' @keywords internal #' @export @@ -74,31 +71,28 @@ is.dag <- function(graph) { #' List all simple paths from one source #' -#' This function lists all simple paths from one source vertex to another -#' vertex or vertices. A path is simple if contains no repeated vertices. +#' This function lists all simple paths from one source vertex to another vertex or vertices. +#' A path is simple if contains no repeated vertices. #' -#' Note that potentially there are exponentially many paths between two -#' vertices of a graph, and you may run out of memory when using this -#' function, if your graph is lattice-like. +#' Note that potentially there are exponentially many paths between two vertices of a graph, +#' and you may run out of memory when using this function, if your graph is lattice-like. #' #' This function ignores multiple and loop edges. #' #' @param graph The input graph. #' @param from The source vertex. -#' @param to The target vertex of vertices. The default `NULL` selects all -#' vertices. +#' @param to The target vertex of vertices. +#' The default `NULL` selects all vertices. #' @inheritParams rlang::args_dots_empty -#' @param mode Character constant, gives whether the shortest paths to or -#' from the given vertices should be calculated for directed graphs. If -#' `out` then the shortest paths *from* the vertex, if `in` -#' then *to* it will be considered. If `all`, the default, then -#' the corresponding undirected graph will be used, i.e. not directed paths -#' are searched. This argument is ignored for undirected graphs. -#' @param cutoff Maximum length of the paths that are considered. If negative, -#' no cutoff is used. -#' @return A list of integer vectors, each integer vector is a path from -#' the source vertex to one of the target vertices. A path is given by its -#' vertex IDs. +#' @param mode Character constant, +#' gives whether the shortest paths to or from the given vertices should be calculated for directed graphs. +#' If `out` then the shortest paths *from* the vertex, if `in` then *to* it will be considered. +#' If `all`, the default, then the corresponding undirected graph will be used, i.e. not directed paths are searched. +#' This argument is ignored for undirected graphs. +#' @param cutoff Maximum length of the paths that are considered. +#' If negative, no cutoff is used. +#' @return A list of integer vectors, each integer vector is a path from the source vertex to one of the target vertices. +#' A path is given by its vertex IDs. #' @keywords graphs #' @examples #' @@ -181,14 +175,13 @@ all_simple_paths <- function( #' Directed acyclic graphs #' -#' This function tests whether the given graph is a DAG, a directed acyclic -#' graph. +#' This function tests whether the given graph is a DAG, a directed acyclic graph. #' -#' `is_dag()` checks whether there is a directed cycle in the graph. If not, -#' the graph is a DAG. +#' `is_dag()` checks whether there is a directed cycle in the graph. +#' If not, the graph is a DAG. #' -#' @param graph The input graph. It may be undirected, in which case -#' `FALSE` is reported. +#' @param graph The input graph. +#' It may be undirected, in which case `FALSE` is reported. #' @return A logical vector of length one. #' @author Tamas Nepusz \email{ntamas@@gmail.com} for the C code, Gabor Csardi #' \email{csardi.gabor@@gmail.com} for the R interface. @@ -212,8 +205,8 @@ is_dag <- function(graph) { #' #' This function tests whether the given graph is free of cycles. #' -#' This function looks for directed cycles in directed graphs and undirected -#' cycles in undirected graphs. Use [find_cycle()] to return a specific cycle. +#' This function looks for directed cycles in directed graphs and undirected cycles in undirected graphs. +#' Use [find_cycle()] to return a specific cycle. #' #' @param graph The input graph. #' @return A logical vector of length one. @@ -223,8 +216,7 @@ is_dag <- function(graph) { #' g <- make_graph(c(1, 2, 1, 3, 2, 4, 3, 4), directed = TRUE) #' is_acyclic(g) #' is_acyclic(as_undirected(g)) -#' @seealso [is_forest()] and [is_dag()] for functions specific to undirected -#' and directed graphs. +#' @seealso [is_forest()] and [is_dag()] for functions specific to undirected and directed graphs. #' @family cycles #' @family structural.properties #' @export @@ -236,25 +228,22 @@ is_acyclic <- function(graph) { #' Maximum cardinality search #' -#' Maximum cardinality search is a simple ordering a vertices that is useful in -#' determining the chordality of a graph. +#' Maximum cardinality search is a simple ordering a vertices that is useful in determining the chordality of a graph. #' -#' Maximum cardinality search visits the vertices in such an order that every -#' time the vertex with the most already visited neighbors is visited. Ties are -#' broken randomly. +#' Maximum cardinality search visits the vertices in such an order that every time the vertex with the most already visited neighbors is visited. +#' Ties are broken randomly. #' -#' The algorithm provides a simple basis for deciding whether a graph is -#' chordal, see References below, and also [is_chordal()]. +#' The algorithm provides a simple basis for deciding whether a graph is chordal, see References below, and also [is_chordal()]. #' #' @aliases max_cardinality -#' @param graph The input graph. It may be directed, but edge directions are -#' ignored, as the algorithm is defined for undirected graphs. +#' @param graph The input graph. +#' It may be directed, but edge directions are ignored, as the algorithm is defined for undirected graphs. #' @return A list with two components: #' \describe{ #' \item{alpha}{ -#' Numeric vector. The 1-based rank of each vertex in the graph -#' such that the vertex with rank 1 is visited first, -#' the vertex with rank 2 is visited second and so on. +#' Numeric vector. +#' The 1-based rank of each vertex in the graph such that the vertex with rank 1 is visited first, the vertex with rank 2 is visited second and +#' so on. #' } #' \item{alpham1}{ #' Numeric vector. The inverse of `alpha`. @@ -297,12 +286,10 @@ max_cardinality <- function(graph) { #' Eccentricity of the vertices in a graph #' -#' The eccentricity of a vertex is its shortest path distance from the farthest -#' other node in the graph. +#' The eccentricity of a vertex is its shortest path distance from the farthest other node in the graph. #' -#' The eccentricity of a vertex is calculated by measuring the shortest -#' distance from (or to) the vertex, to (or from) all vertices in the graph, -#' and taking the maximum. +#' The eccentricity of a vertex is calculated by measuring the shortest distance from (or to) the vertex, +#' to (or from) all vertices in the graph, and taking the maximum. #' #' This implementation ignores vertex pairs that are in different components. #' Isolate vertices have eccentricity zero. @@ -311,8 +298,7 @@ max_cardinality <- function(graph) { #' @param vids The vertices for which the eccentricity is calculated. #' @inheritParams distances #' @inheritParams rlang::args_dots_empty -#' @return `eccentricity()` returns a numeric vector, containing the -#' eccentricity score of each given vertex. +#' @return `eccentricity()` returns a numeric vector, containing the eccentricity score of each given vertex. #' @seealso [radius()] for a related concept, #' [distances()] for general shortest path calculations. #' @references Harary, F. Graph Theory. Reading, MA: Addison-Wesley, p. 35, @@ -356,23 +342,20 @@ eccentricity <- function( #' Radius of a graph #' -#' The eccentricity of a vertex is its distance from the farthest other node -#' in the graph. The smallest eccentricity in a graph is called its radius. +#' The eccentricity of a vertex is its distance from the farthest other node in the graph. +#' The smallest eccentricity in a graph is called its radius. #' -#' The eccentricity of a vertex is calculated by measuring the shortest -#' distance from (or to) the vertex, to (or from) all vertices in the -#' graph, and taking the maximum. +#' The eccentricity of a vertex is calculated by measuring the shortest distance from (or to) the vertex, +#' to (or from) all vertices in the graph, and taking the maximum. #' -#' This implementation ignores vertex pairs that are in different -#' components. Isolated vertices have eccentricity zero. +#' This implementation ignores vertex pairs that are in different components. +#' Isolated vertices have eccentricity zero. #' #' @param graph The input graph, it can be directed or undirected. #' @inheritParams eccentricity #' @inheritParams rlang::args_dots_empty #' @return A numeric scalar, the radius of the graph. -#' @seealso [eccentricity()] for the underlying -#' calculations, [distances] for general shortest path -#' calculations. +#' @seealso [eccentricity()] for the underlying calculations, [distances] for general shortest path calculations. #' @references Harary, F. Graph Theory. Reading, MA: Addison-Wesley, p. 35, #' 1994. #' @examples diff --git a/R/plot.R b/R/plot.R index 23a40118460..5eb0c49d0a2 100644 --- a/R/plot.R +++ b/R/plot.R @@ -21,58 +21,46 @@ #' Plotting of graphs #' -#' `plot.igraph()` is able to plot graphs to any R device. It is the -#' non-interactive companion of the `tkplot()` function. +#' `plot.igraph()` is able to plot graphs to any R device. +#' It is the non-interactive companion of the `tkplot()` function. #' -#' One convenient way to plot graphs is to plot with [tkplot()] -#' first, handtune the placement of the vertices, query the coordinates by the -#' [tk_coords()] function and use them with [plot()] to -#' plot the graph to any R device. +#' One convenient way to plot graphs is to plot with [tkplot()] first, handtune the placement of the vertices, +#' query the coordinates by the [tk_coords()] function and use them with [plot()] to plot the graph to any R device. #' #' @aliases plot.graph #' @param x The graph to plot. #' @param axes Logical, whether to plot axes, defaults to FALSE. -#' @param add Logical, whether to add the plot to the current device, or -#' delete the device's current contents first. -#' @param xlim The limits for the horizontal axis, it is unlikely that you want -#' to modify this. -#' @param ylim The limits for the vertical axis, it is unlikely that you want -#' to modify this. -#' @param mark.groups A list of vertex ID vectors. It is interpreted as a set -#' of vertex groups. Each vertex group is highlighted, by plotting a colored -#' smoothed polygon around and \dQuote{under} it. See the arguments below to -#' control the look of the polygons. -#' @param mark.shape A numeric scalar or vector. Controls the smoothness of the -#' vertex group marking polygons. This is basically the \sQuote{shape} -#' parameter of the [graphics::xspline()] function, its possible -#' values are between -1 and 1. If it is a vector, then a different value is -#' used for the different vertex groups. -#' @param mark.col A scalar or vector giving the colors of marking the -#' polygons, in any format accepted by [graphics::xspline()]; e.g. -#' numeric color IDs, symbolic color names, or colors in RGB. The default -#' `NULL` uses semi-transparent rainbow colors. -#' @param mark.border A scalar or vector giving the colors of the borders of -#' the vertex group marking polygons. If it is `NA`, then no border is -#' drawn. The default `NULL` uses rainbow colors. -#' @param mark.expand A numeric scalar or vector, the size of the border around -#' the marked vertex groups. It is in the same units as the vertex sizes. If a -#' vector is given, then different values are used for the different vertex -#' groups. -#' @param mark.lwd A numeric scalar or vector, the linewidth of the border around -#' the marked vertex groups. If a -#' vector is given, then different values are used for the different vertex -#' groups. -#' @param loop.size A numeric scalar that allows the user to scale the loop edges -#' of the network. The default loop size is 1. Larger values will produce larger -#' loops. -#' @param \dots Additional plotting parameters. See [igraph.plotting] for -#' the complete list. +#' @param add Logical, whether to add the plot to the current device, or delete the device's current contents first. +#' @param xlim The limits for the horizontal axis, it is unlikely that you want to modify this. +#' @param ylim The limits for the vertical axis, it is unlikely that you want to modify this. +#' @param mark.groups A list of vertex ID vectors. +#' It is interpreted as a set of vertex groups. +#' Each vertex group is highlighted, by plotting a colored smoothed polygon around and \dQuote{under} it. +#' See the arguments below to control the look of the polygons. +#' @param mark.shape A numeric scalar or vector. +#' Controls the smoothness of the vertex group marking polygons. +#' This is basically the \sQuote{shape} parameter of the [graphics::xspline()] function, +#' its possible values are between -1 and 1. If it is a vector, then a different value is used for the different vertex groups. +#' @param mark.col A scalar or vector giving the colors of marking the polygons, in any format accepted by [graphics::xspline()]; +#' e.g. numeric color IDs, symbolic color names, or colors in RGB. +#' The default `NULL` uses semi-transparent rainbow colors. +#' @param mark.border A scalar or vector giving the colors of the borders of the vertex group marking polygons. +#' If it is `NA`, then no border is drawn. +#' The default `NULL` uses rainbow colors. +#' @param mark.expand A numeric scalar or vector, the size of the border around the marked vertex groups. +#' It is in the same units as the vertex sizes. +#' If a vector is given, then different values are used for the different vertex groups. +#' @param mark.lwd A numeric scalar or vector, the linewidth of the border around the marked vertex groups. +#' If a vector is given, +#' then different values are used for the different vertex groups. +#' @param loop.size A numeric scalar that allows the user to scale the loop edges of the network. +#' The default loop size is 1. Larger values will produce larger loops. +#' @param \dots Additional plotting parameters. +#' See [igraph.plotting] for the complete list. #' @return Returns `NULL`, invisibly. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @seealso [layout()] for different layouts, -#' [igraph.plotting] for the detailed description of the plotting -#' parameters and [tkplot()] and [rglplot()] for other -#' graph plotting functions. +#' [igraph.plotting] for the detailed description of the plotting parameters and [tkplot()] and [rglplot()] for other graph plotting functions. #' @method plot igraph #' @export #' @rawNamespace export(plot.igraph) @@ -875,22 +863,19 @@ plot.igraph <- function( #' 3D plotting of graphs with OpenGL #' -#' Using the `rgl` package, `rglplot()` plots a graph in 3D. The plot -#' can be zoomed, rotated, shifted, etc. but the coordinates of the vertices is -#' fixed. +#' Using the `rgl` package, `rglplot()` plots a graph in 3D. +#' The plot can be zoomed, rotated, shifted, etc. but the coordinates of the vertices is fixed. #' -#' Note that `rglplot()` is considered to be highly experimental. It is not -#' very useful either. See [igraph.plotting] for the possible -#' arguments. +#' Note that `rglplot()` is considered to be highly experimental. +#' It is not very useful either. +#' See [igraph.plotting] for the possible arguments. #' #' @aliases rglplot.igraph #' @param x The graph to plot. -#' @param \dots Additional arguments, see [igraph.plotting] for the -#' details +#' @param \dots Additional arguments, see [igraph.plotting] for the details #' @return `NULL`, invisibly. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso [igraph.plotting], [plot.igraph()] for the 2D -#' version, [tkplot()] for interactive graph drawing in 2D. +#' @seealso [igraph.plotting], [plot.igraph()] for the 2D version, [tkplot()] for interactive graph drawing in 2D. #' @family plot #' @export #' @keywords graphs diff --git a/R/plot.common.R b/R/plot.common.R index 9fb2c5783f6..0a44a01ba20 100644 --- a/R/plot.common.R +++ b/R/plot.common.R @@ -3,89 +3,75 @@ #' The common bits of the three plotting functions `plot.igraph`, #' `tkplot` and `rglplot` are discussed in this manual page. #' -#' There are currently three different functions in the igraph package which -#' can draw graph in various ways: +#' There are currently three different functions in the igraph package which can draw graph in various ways: #' #' `plot.igraph` does simple non-interactive 2D plotting to R devices. -#' Actually it is an implementation of the [graphics::plot()] generic -#' function, so you can write `plot(graph)` instead of -#' `plot.igraph(graph)`. As it used the standard R devices it supports -#' every output format for which R has an output device. The list is quite -#' impressing: PostScript, PDF files, XFig files, SVG files, JPG, PNG and of -#' course you can plot to the screen as well using the default devices, or the -#' good-looking anti-aliased Cairo device. See [plot.igraph()] for -#' some more information. +#' Actually it is an implementation of the [graphics::plot()] generic function, +#' so you can write `plot(graph)` instead of `plot.igraph(graph)`. +#' As it used the standard R devices it supports every output format for which R has an output device. +#' The list is quite impressing: +#' PostScript, PDF files, XFig files, SVG files, JPG, PNG and of course you can plot to the screen as well using the default devices, +#' or the good-looking anti-aliased Cairo device. +#' See [plot.igraph()] for some more information. #' -#' [tkplot()] does interactive 2D plotting using the `tcltk` -#' package. It can only handle graphs of moderate size, a thousand vertices is -#' probably already too many. Some parameters of the plotted graph can be -#' changed interactively after issuing the `tkplot` command: the position, -#' color and size of the vertices and the color and width of the edges. See -#' [tkplot()] for details. +#' [tkplot()] does interactive 2D plotting using the `tcltk` package. +#' It can only handle graphs of moderate size, a thousand vertices is probably already too many. +#' Some parameters of the plotted graph can be changed interactively after issuing the `tkplot` command: the position, +#' color and size of the vertices and the color and width of the edges. +#' See [tkplot()] for details. #' -#' [rglplot()] is an experimental function to draw graphs in 3D using -#' OpenGL. See [rglplot()] for some more information. +#' [rglplot()] is an experimental function to draw graphs in 3D using OpenGL. +#' See [rglplot()] for some more information. #' #' Please also check the examples below. #' #' @aliases igraph.plotting #' @section How to specify graphical parameters: There are three ways to give -#' values to the parameters described below, in section 'Parameters'. We give -#' these three ways here in the order of their precedence. +#' values to the parameters described below, in section 'Parameters'. +#' We give these three ways here in the order of their precedence. #' -#' The first method is to supply named arguments to the plotting commands: -#' [plot.igraph()], [tkplot()] or rglplot()]. -#' Parameters for vertices start with prefix \sQuote{\code{vertex.}}, -#' parameters for edges have prefix \sQuote{\code{edge.}}, and global -#' parameters have no prefix. Eg. the color of the vertices can be given via -#' argument `vertex.color`, whereas `edge.color` sets the color of -#' the edges. `layout` gives the layout of the graphs. +#' The first method is to supply named arguments to the plotting commands: [plot.igraph()], [tkplot()] or rglplot()]. +#' Parameters for vertices start with prefix \sQuote{\code{vertex.}}, parameters for edges have prefix \sQuote{\code{edge.}}, +#' and global parameters have no prefix. +#' Eg. the color of the vertices can be given via argument `vertex.color`, whereas `edge.color` sets the color of the edges. +#' `layout` gives the layout of the graphs. #' #' The second way is to assign vertex, edge and graph attributes to the graph. -#' These attributes have no prefix, ie. the color of the vertices is taken from -#' the `color` vertex attribute and the color of the edges from the -#' `color` edge attribute. The layout of the graph is given by the -#' `layout` graph attribute. (Always assuming that the corresponding -#' command argument is not present.) Setting vertex and edge attributes are -#' handy if you want to assign a given \sQuote{look} to a graph, attributes are -#' saved with the graph is you save it with [base::save()] or in -#' GraphML format with [write_graph()], so the graph will have the -#' same look after loading it again. +#' These attributes have no prefix, ie. the color of the vertices is taken from the `color` vertex attribute +#' and the color of the edges from the `color` edge attribute. +#' The layout of the graph is given by the `layout` graph attribute. +#' (Always assuming that the corresponding command argument is not present.) +#' Setting vertex and edge attributes are handy if you want to assign a given \sQuote{look} to a graph, +#' attributes are saved with the graph is you save it with [base::save()] or in GraphML format with [write_graph()], +#' so the graph will have the same look after loading it again. #' -#' If a parameter is not given in the command line, and the corresponding -#' vertex/edge/graph attribute is also missing then the general igraph -#' parameters handled by [igraph_options()] are also checked. Vertex -#' parameters have prefix \sQuote{\code{vertex.}}, edge parameters are prefixed -#' with \sQuote{\code{edge.}}, general parameters like `layout` are -#' prefixed with \sQuote{\code{plot}}. These parameters are useful if you want -#' all or most of your graphs to have the same look, vertex size, vertex color, -#' etc. Then you don't need to set these at every plotting, and you also don't -#' need to assign vertex/edge attributes to every graph. +#' If a parameter is not given in the command line, +#' and the corresponding vertex/edge/graph attribute is also missing then the general igraph parameters handled by [igraph_options()] are also checked. +#' Vertex parameters have prefix \sQuote{\code{vertex.}}, edge parameters are prefixed with \sQuote{\code{edge.}}, +#' general parameters like `layout` are prefixed with \sQuote{\code{plot}}. +#' These parameters are useful +#' if you want all or most of your graphs to have the same look, vertex size, vertex color, +#' etc. Then you don't need to set these at every plotting, and you also don't need to assign vertex/edge attributes to every graph. #' -#' If the value of a parameter is not specified by any of the three ways -#' described here, its default valued is used, as given in the source code. +#' If the value of a parameter is not specified by any of the three ways described here, its default valued is used, +#' as given in the source code. #' -#' Different parameters can have different type, eg. vertex colors can be given -#' as a character vector with color names, or as an integer vector with the -#' color numbers from the current palette. Different types are valid for -#' different parameters, this is discussed in detail in the next section. It is -#' however always true that the parameter can always be a function object in -#' which it will be called with the graph as its single argument to get the -#' \dQuote{proper} value of the parameter. (If the function returns another -#' function object that will *not* be called again\dots) +#' Different parameters can have different type, eg. vertex colors can be given as a character vector with color names, +#' or as an integer vector with the color numbers from the current palette. +#' Different types are valid for different parameters, this is discussed in detail in the next section. +#' It is however always true that the parameter can always be a function object +#' in which it will be called with the graph as its single argument to get the \dQuote{proper} value of the parameter. +#' (If the function returns another function object that will *not* be called again\dots) #' @section The list of parameters: Vertex parameters first, note that the -#' \sQuote{\code{vertex.}} prefix needs to be added if they are used as an -#' argument or when setting via [igraph_options()]. The value of the -#' parameter may be scalar valid for every vertex or a vector with a separate -#' value for each vertex. (Shorter vectors are recycled.) +#' \sQuote{\code{vertex.}} prefix needs to be added if they are used as an argument or when setting via [igraph_options()]. +#' The value of the parameter may be scalar valid for every vertex or a vector with a separate value for each vertex. +#' (Shorter vectors are recycled.) #' \describe{ #' \item{size}{ -#' The size of the vertex, a numeric scalar or vector, -#' in the latter case each vertex sizes may differ. -#' This vertex sizes are scaled in order have about the same size of vertices -#' for a given value for all three plotting commands. -#' It does not need to be an integer number. The default value is 15. -#' This is big enough to place short labels on vertices. +#' The size of the vertex, a numeric scalar or vector, in the latter case each vertex sizes may differ. +#' This vertex sizes are scaled in order have about the same size of vertices for a given value for all three plotting commands. +#' It does not need to be an integer number. +#' The default value is 15. This is big enough to place short labels on vertices. #' If `size.scaling` is `TRUE`, `relative.size` is used to scale the size appropriately. #' } #' \item{size2}{ @@ -97,18 +83,15 @@ #' The default is 15. #' } #' \item{color}{ -#' The fill color of the vertex. If it is -#' numeric then the current palette is used, see -#' [grDevices::palette()]. If it is a character vector then it may -#' either contain integer values, named colors or RGB specified colors with -#' three or four bytes. All strings starting with \sQuote{\code{#}} are assumed -#' to be RGB color specifications. It is possible to mix named color and RGB -#' colors. Note that [tkplot()] ignores the fourth byte (alpha -#' channel) in the RGB color specification. +#' The fill color of the vertex. +#' If it is numeric then the current palette is used, see [grDevices::palette()]. +#' If it is a character vector then it may either contain integer values, named colors or RGB specified colors with three or four bytes. +#' All strings starting with \sQuote{\code{#}} are assumed to be RGB color specifications. +#' It is possible to mix named color and RGB colors. +#' Note that [tkplot()] ignores the fourth byte (alpha channel) in the RGB color specification. #' -#' For `plot.igraph` and integer values, the default igraph palette is -#' used (see the \sQuote{palette} parameter below. Note that this is different -#' from the R palette. +#' For `plot.igraph` and integer values, the default igraph palette is used (see the \sQuote{palette} parameter below. +#' Note that this is different from the R palette. #' #' If you don't want (some) vertices to have any color, supply `NA` as the #' color name. @@ -126,23 +109,16 @@ #' The width of the frame of the vertices. The default value is 1. #' } #' \item{shape}{ -#' The shape of the vertex, currently \dQuote{\code{circle}}, -#' \dQuote{\code{square}}, \dQuote{\code{csquare}}, \dQuote{\code{rectangle}}, -#' \dQuote{\code{crectangle}}, \dQuote{\code{vrectangle}}, \dQuote{\code{pie}} -#' (see [vertex.shape.pie()]), \sQuote{\code{sphere}}, and -#' \dQuote{\code{none}} are supported, and only by the -#' [plot.igraph()] command. \dQuote{\code{none}} does not draw the -#' vertices at all, although vertex label are plotted (if given). See -#' [shapes()] for details about vertex shapes and -#' [vertex.shape.pie()] for using pie charts as vertices. +#' The shape of the vertex, currently \dQuote{\code{circle}}, \dQuote{\code{square}}, \dQuote{\code{csquare}}, \dQuote{\code{rectangle}}, +#' \dQuote{\code{crectangle}}, \dQuote{\code{vrectangle}}, \dQuote{\code{pie}} (see [vertex.shape.pie()]), \sQuote{\code{sphere}}, +#' and \dQuote{\code{none}} are supported, and only by the [plot.igraph()] command. +#' \dQuote{\code{none}} does not draw the vertices at all, although vertex label are plotted (if given). +#' See [shapes()] for details about vertex shapes and [vertex.shape.pie()] for using pie charts as vertices. #' -#' The \dQuote{\code{sphere}} vertex shape plots vertices as 3D ray-traced -#' spheres, in the given color and size. This produces a raster image and it is -#' only supported with some graphics devices. On some devices raster -#' transparency is not supported and the spheres do not have a transparent -#' background. See [dev.capabilities] and the -#' \sQuote{\code{rasterImage}} capability to check that your device is -#' supported. +#' The \dQuote{\code{sphere}} vertex shape plots vertices as 3D ray-traced spheres, in the given color and size. +#' This produces a raster image and it is only supported with some graphics devices. +#' On some devices raster transparency is not supported and the spheres do not have a transparent background. +#' See [dev.capabilities] and the \sQuote{\code{rasterImage}} capability to check that your device is supported. #' #' By default vertices are drawn as circles. #' } @@ -151,28 +127,24 @@ #' Specify `NA` to omit vertex labels. The default vertex labels are the vertex IDs. #' } #' \item{label.family}{ -#' The -#' font family to be used for vertex labels. As different plotting commands -#' can used different fonts, they interpret this parameter different ways. The -#' basic notation is, however, understood by both [plot.igraph()] and -#' [tkplot()]. [rglplot()] does not support fonts at all -#' right now, it ignores this parameter completely. +#' The font family to be used for vertex labels. +#' As different plotting commands can used different fonts, they interpret this parameter different ways. +#' The basic notation is, however, understood by both [plot.igraph()] and [tkplot()]. +#' [rglplot()] does not support fonts at all right now, it ignores this parameter completely. #' #' For [plot.igraph()] this parameter is simply passed to #' [graphics::text()] as argument `family`. #' -#' For [tkplot()] some conversion is performed. If this parameter is -#' the name of an existing Tk font, then that font is used and the -#' `label.font` and `label.cex` parameters are ignored completely. If -#' it is one of the base families (serif, sans, mono) then Times, Helvetica or -#' Courier fonts are used, there are guaranteed to exist on all systems. For -#' the \sQuote{symbol} base family we used the symbol font is available, -#' otherwise the first font which has \sQuote{symbol} in its name. If the -#' parameter is not a name of the base families and it is also not a named Tk -#' font then we pass it to [tcltk::tkfont.create()] and hope the user -#' knows what she is doing. The `label.font` and `label.cex` -#' parameters are also passed to [tcltk::tkfont.create()] in this -#' case. +#' For [tkplot()] some conversion is performed. +#' If this parameter is the name of an existing Tk font, then that font is used and the `label.font` +#' and `label.cex` parameters are ignored completely. +#' If it is one of the base families (serif, sans, mono) then Times, Helvetica or Courier fonts are used, +#' there are guaranteed to exist on all systems. +#' For the \sQuote{symbol} base family we used the symbol font is available, otherwise the first font +#' which has \sQuote{symbol} in its name. +#' If the parameter is not a name of the base families and it is also not a named Tk font then we pass it to [tcltk::tkfont.create()] +#' and hope the user knows what she is doing. +#' The `label.font` and `label.cex` parameters are also passed to [tcltk::tkfont.create()] in this case. #' #' The default value is \sQuote{serif}. #' } @@ -238,18 +210,16 @@ #' If TRUE, `relative.size` is used to scale both appropriately with `relative.size`. #' } #' \item{relative.size}{ -#' The relative size of the smallest and largest vertices as percentage of -#' the plotting region. When all vertices have the same size, then by default -#' the relative size observed in the plot will be equal to -#' \code{relative.size[2]}. +#' The relative size of the smallest and largest vertices as percentage of the plotting region. +#' When all vertices have the same size, then by default the relative size observed in the plot will be equal to \code{relative.size[2]}. #' The default value is \code{c(.01,.025)} (1\% and 2.5\% respectively). #' #' Only used if `size.scaling` is TRUE`. #' } #' } #' -#' Edge parameters require to add the \sQuote{\code{edge.}} prefix when used as -#' arguments or set by [igraph_options()]. The edge parameters: +#' Edge parameters require to add the \sQuote{\code{edge.}} prefix when used as arguments or set by [igraph_options()]. +#' The edge parameters: #' \describe{ #' \item{color}{ #' The color of the edges, see the `color` vertex parameter for the possible values. @@ -265,12 +235,10 @@ #' The width of the arrows. The default value is 1. #' } #' \item{lty}{ -#' The line type for the edges. Almost the -#' same format is accepted as for the standard graphics -#' [graphics::par()], 0 and \dQuote{blank} mean no edges, 1 and -#' \dQuote{solid} are for solid lines, the other possible values are: 2 -#' (\dQuote{dashed}), 3 (\dQuote{dotted}), 4 (\dQuote{dotdash}), 5 -#' (\dQuote{longdash}), 6 (\dQuote{twodash}). +#' The line type for the edges. +#' Almost the same format is accepted as for the standard graphics [graphics::par()], 0 and \dQuote{blank} mean no edges, 1 +#' and \dQuote{solid} are for solid lines, the other possible values are: 2 (\dQuote{dashed}), 3 (\dQuote{dotted}), 4 (\dQuote{dotdash}), +#' 5 (\dQuote{longdash}), 6 (\dQuote{twodash}). #' #' [tkplot()] also accepts standard Tk line type strings, it does not #' however support \dQuote{blank} lines, instead of type \sQuote{0} type @@ -492,8 +460,7 @@ NULL #' @description #' `r lifecycle::badge("deprecated")` #' -#' `autocurve.edges()` was renamed to [curve_multiple()] to create a more -#' consistent API. +#' `autocurve.edges()` was renamed to [curve_multiple()] to create a more consistent API. #' @inheritParams curve_multiple #' @keywords internal #' @export @@ -698,23 +665,19 @@ i.postprocess.layout <- function(maybe_layout) { #' Optimal edge curvature when plotting graphs #' -#' If graphs have multiple edges, then drawing them as straight lines does not -#' show them when plotting the graphs; they will be on top of each other. One -#' solution is to bend the edges, with diffenent curvature, so that all of them -#' are visible. +#' If graphs have multiple edges, then drawing them as straight lines does not show them when plotting the graphs; +#' they will be on top of each other. +#' One solution is to bend the edges, with diffenent curvature, so that all of them are visible. #' -#' `curve_multiple()` calculates the optimal `edge.curved` vector for -#' plotting a graph with multiple edges, so that all edges are visible. +#' `curve_multiple()` calculates the optimal `edge.curved` vector for plotting a graph with multiple edges, so that all edges are visible. #' #' @param graph The input graph. #' @inheritParams rlang::args_dots_empty -#' @param start The curvature at the two extreme edges. All edges will have a -#' curvature between `-start` and `start`, spaced equally. +#' @param start The curvature at the two extreme edges. +#' All edges will have a curvature between `-start` and `start`, spaced equally. #' @return A numeric vector, its length is the number of edges in the graph. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso [igraph.plotting] for all plotting parameters, -#' [plot.igraph()], [tkplot()] and [rglplot()] -#' for plotting functions. +#' @seealso [igraph.plotting] for all plotting parameters, [plot.igraph()], [tkplot()] and [rglplot()] for plotting functions. #' @family plot.common #' @export #' @importFrom stats ave @@ -4991,13 +4954,11 @@ i.default.values[["plot"]] <- i.plot.default #' Using pie charts as vertices in graph plots #' -#' More complex vertex images can be used to express addtional information -#' about vertices. E.g. pie charts can be used as vertices, to denote vertex -#' classes, fuzzy classification of vertices, etc. +#' More complex vertex images can be used to express addtional information about vertices. +#' E.g. pie charts can be used as vertices, to denote vertex classes, fuzzy classification of vertices, etc. #' -#' The vertex shape \sQuote{pie} makes igraph draw a pie chart for every -#' vertex. There are some extra graphical vertex parameters that specify how -#' the pie charts will look like: +#' The vertex shape \sQuote{pie} makes igraph draw a pie chart for every vertex. +#' There are some extra graphical vertex parameters that specify how the pie charts will look like: #' \describe{ #' \item{pie}{ #' Numeric vector, gives the sizes of the pie slices. diff --git a/R/plot.shapes.R b/R/plot.shapes.R index dc1eb672675..ccac47a1149 100644 --- a/R/plot.shapes.R +++ b/R/plot.shapes.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `igraph.shape.noplot()` was renamed to [shape_noplot()] to create a more -#' consistent API. +#' `igraph.shape.noplot()` was renamed to [shape_noplot()] to create a more consistent API. #' @inheritParams shape_noplot #' @keywords internal #' @export @@ -19,8 +18,7 @@ igraph.shape.noplot <- function(coords, v = NULL, params) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `igraph.shape.noclip()` was renamed to [shape_noclip()] to create a more -#' consistent API. +#' `igraph.shape.noclip()` was renamed to [shape_noclip()] to create a more consistent API. #' @inheritParams shape_noclip #' @keywords internal #' @export @@ -40,8 +38,7 @@ igraph.shape.noclip <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `vertex.shapes()` was renamed to [shapes()] to create a more -#' consistent API. +#' `vertex.shapes()` was renamed to [shapes()] to create a more consistent API. #' @inheritParams shapes #' @keywords internal #' @export @@ -56,8 +53,7 @@ vertex.shapes <- function(shape = NULL) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `add.vertex.shape()` was renamed to [add_shape()] to create a more -#' consistent API. +#' `add.vertex.shape()` was renamed to [add_shape()] to create a more consistent API. #' @inheritParams add_shape #' @keywords internal #' @export @@ -149,15 +145,13 @@ add.vertex.shape <- function( #' Various vertex shapes when plotting igraph graphs #' -#' Starting from version 0.5.1 igraph supports different -#' vertex shapes when plotting graphs. +#' Starting from version 0.5.1 igraph supports different vertex shapes when plotting graphs. #' #' @details -#' In igraph a vertex shape is defined by two functions: 1) provides -#' information about the size of the shape for clipping the edges and 2) -#' plots the shape if requested. These functions are called \dQuote{shape -#' functions} in the rest of this manual page. The first one is the -#' clipping function and the second is the plotting function. +#' In igraph a vertex shape is defined by two functions: 1) provides information about the size of the shape for clipping the edges and 2) plots the shape +#' if requested. +#' These functions are called \dQuote{shape functions} in the rest of this manual page. +#' The first one is the clipping function and the second is the plotting function. #' #' The clipping function has the following arguments: #' \describe{ @@ -184,11 +178,9 @@ add.vertex.shape <- function( #' } #' } #' -#' The clipping function should return a matrix -#' with the same number of rows as the `el` arguments. -#' If `end` is `both` then the matrix must have four -#' columns, otherwise two. The matrix contains the modified coordinates, -#' with the clipping applied. +#' The clipping function should return a matrix with the same number of rows as the `el` arguments. +#' If `end` is `both` then the matrix must have four columns, otherwise two. +#' The matrix contains the modified coordinates, with the clipping applied. #' #' The plotting function has the following arguments: #' \describe{ @@ -205,55 +197,41 @@ add.vertex.shape <- function( #' #' The return value of the plotting function is not used. #' -#' `shapes()` can be used to list the names of all installed -#' vertex shapes, by calling it without arguments, or setting the -#' `shape` argument to `NULL`. If a shape name is given, then -#' the clipping and plotting functions of that shape are returned in a -#' named list. +#' `shapes()` can be used to list the names of all installed vertex shapes, by calling it without arguments, +#' or setting the `shape` argument to `NULL`. +#' If a shape name is given, then the clipping and plotting functions of that shape are returned in a named list. #' -#' `add_shape()` can be used to add new vertex shapes to -#' igraph. For this one must give the clipping and plotting functions of -#' the new shape. It is also possible to list the plot/vertex/edge -#' parameters, in the `parameters` argument, that the clipping -#' and/or plotting functions can make use of. An example would be a -#' generic regular polygon shape, which can have a parameter for the -#' number of sides. +#' `add_shape()` can be used to add new vertex shapes to igraph. +#' For this one must give the clipping and plotting functions of the new shape. +#' It is also possible to list the plot/vertex/edge parameters, in the `parameters` argument, +#' that the clipping and/or plotting functions can make use of. +#' An example would be a generic regular polygon shape, which can have a parameter for the number of sides. #' -#' `shape_noclip()` is a very simple clipping function that the -#' user can use in their own shape definitions. It does no clipping, the -#' edges will be drawn exactly until the listed vertex position -#' coordinates. +#' `shape_noclip()` is a very simple clipping function that the user can use in their own shape definitions. +#' It does no clipping, the edges will be drawn exactly until the listed vertex position coordinates. #' -#' `shape_noplot()` is a very simple (and probably not very -#' useful) plotting function, that does not plot anything. +#' `shape_noplot()` is a very simple (and probably not very useful) plotting function, that does not plot anything. #' #' @aliases igraph.vertex.shapes #' -#' @param shape Character scalar, name of a vertex shape. If it is -#' `NULL` for `shapes()`, then the names of all defined -#' vertex shapes are returned. -#' @param clip An R function object, the clipping function. The default -#' `NULL` uses `shape_noclip`. -#' @param plot An R function object, the plotting function. The default -#' `NULL` uses `shape_noplot`. -#' @param parameters Named list, additional plot/vertex/edge -#' parameters. The element named define the new parameters, and the -#' elements themselves define their default values. -#' Vertex parameters should have a prefix -#' \sQuote{`vertex.`}, edge parameters a prefix -#' \sQuote{`edge.`}. Other general plotting parameters should have -#' a prefix \sQuote{`plot.`}. See Details below. -#' @param coords,el,params,end,v See parameters of the clipping/plotting -#' functions below. -#' @return `shapes()` returns a character vector if the -#' `shape` argument is `NULL`. It returns a named list with -#' entries named \sQuote{clip} and \sQuote{plot}, both of them R -#' functions. +#' @param shape Character scalar, name of a vertex shape. +#' If it is `NULL` for `shapes()`, then the names of all defined vertex shapes are returned. +#' @param clip An R function object, the clipping function. +#' The default `NULL` uses `shape_noclip`. +#' @param plot An R function object, the plotting function. +#' The default `NULL` uses `shape_noplot`. +#' @param parameters Named list, additional plot/vertex/edge parameters. +#' The element named define the new parameters, and the elements themselves define their default values. +#' Vertex parameters should have a prefix \sQuote{`vertex.`}, edge parameters a prefix \sQuote{`edge.`}. +#' Other general plotting parameters should have a prefix \sQuote{`plot.`}. +#' See Details below. +#' @param coords,el,params,end,v See parameters of the clipping/plotting functions below. +#' @return `shapes()` returns a character vector if the `shape` argument is `NULL`. +#' It returns a named list with entries named \sQuote{clip} and \sQuote{plot}, both of them R functions. #' #' `add_shape()` returns `TRUE`, invisibly. #' -#' `shape_noclip()` returns the appropriate columns of its -#' `coords` argument. +#' `shape_noclip()` returns the appropriate columns of its `coords` argument. #' @family plot.shapes #' @export #' diff --git a/R/print.R b/R/print.R index 95c23c48439..b3a02d9a3d3 100644 --- a/R/print.R +++ b/R/print.R @@ -286,10 +286,9 @@ } } -# Print the "single index" (`[[`) edge detail view: one row per edge with -# tail/head names, their raw numeric ids (tid/hid) and one column per atomic -# edge attribute. If any attribute is list-valued, the frame can't hold it, so -# fall back to a per-attribute named list sliced to the selected edges. +# Print the "single index" (`[[`) edge detail view: one row per edge with tail/head names, +# their raw numeric ids (tid/hid) and one column per atomic edge attribute. +# If any attribute is list-valued, the frame can't hold it, so fall back to a per-attribute named list sliced to the selected edges. print_edge_detail <- function(graph, edges) { ea <- edge_attr(graph) if (all(vapply(ea, is.atomic, logical(1)))) { @@ -505,80 +504,64 @@ print_all <- function(object, ...) { #' Print graphs to the terminal #' -#' These functions attempt to print a graph to the terminal in a human readable -#' form. +#' These functions attempt to print a graph to the terminal in a human readable form. #' -#' `summary.igraph` prints the number of vertices, edges and whether the -#' graph is directed. +#' `summary.igraph` prints the number of vertices, edges and whether the graph is directed. #' -#' `print_all()` prints the same information, and also lists the edges, and -#' optionally graph, vertex and/or edge attributes. +#' `print_all()` prints the same information, and also lists the edges, and optionally graph, vertex and/or edge attributes. #' -#' `print.igraph()` behaves either as `summary.igraph` or -#' `print_all()` depending on the `full` argument. See also the -#' \sQuote{print.full} igraph option and [igraph_opt()]. +#' `print.igraph()` behaves either as `summary.igraph` or `print_all()` depending on the `full` argument. +#' See also the \sQuote{print.full} igraph option and [igraph_opt()]. #' -#' The graph summary printed by `summary.igraph` (and `print.igraph()` -#' and `print_all()`) consists of one or more lines. The first line contains -#' the basic properties of the graph, and the rest contains its attributes. +#' The graph summary printed by `summary.igraph` (and `print.igraph()` and `print_all()`) consists of one or more lines. +#' The first line contains the basic properties of the graph, and the rest contains its attributes. #' Here is an example, a small star graph with weighted directed edges and named #' vertices: \preformatted{ IGRAPH badcafe DNW- 10 9 -- In-star #' + attr: name (g/c), mode (g/c), center (g/n), name (v/c), #' weight (e/n) } -#' The first line always -#' starts with `IGRAPH`, showing you that the object is an igraph graph. -#' Then a seven character code is printed, this the first seven characters -#' of the unique ID of the graph. See [graph_id()] for more. -#' Then a four letter long code string is printed. The first letter -#' distinguishes between directed (\sQuote{`D`}) and undirected -#' (\sQuote{`U`}) graphs. The second letter is \sQuote{`N`} for named -#' graphs, i.e. graphs with the `name` vertex attribute set. The third -#' letter is \sQuote{`W`} for weighted graphs, i.e. graphs with the -#' `weight` edge attribute set. The fourth letter is \sQuote{`B`} for -#' bipartite graphs, i.e. for graphs with the `type` vertex attribute set. +#' The first line always starts with `IGRAPH`, showing you that the object is an igraph graph. +#' Then a seven character code is printed, this the first seven characters of the unique ID of the graph. +#' See [graph_id()] for more. +#' Then a four letter long code string is printed. +#' The first letter distinguishes between directed (\sQuote{`D`}) and undirected (\sQuote{`U`}) graphs. +#' The second letter is \sQuote{`N`} for named graphs, i.e. graphs with the `name` vertex attribute set. +#' The third letter is \sQuote{`W`} for weighted graphs, i.e. graphs with the `weight` edge attribute set. +#' The fourth letter is \sQuote{`B`} for bipartite graphs, i.e. for graphs with the `type` vertex attribute set. #' #' This is followed by the number of vertices and edges, then two dashes. #' #' Finally, after two dashes, the name of the graph is printed, if it has one, #' i.e. if the `name` graph attribute is set. #' -#' From the second line, the attributes of the graph are listed, separated by a -#' comma. After the attribute names, the kind of the attribute -- graph -#' (\sQuote{`g`}), vertex (\sQuote{`v`}) or edge (\sQuote{`e`}) -#' -- is denoted, and the type of the attribute as well, character -#' (\sQuote{`c`}), numeric (\sQuote{`n`}), logical -#' (\sQuote{`l`}), or other (\sQuote{`x`}). +#' From the second line, the attributes of the graph are listed, separated by a comma. +#' After the attribute names, the kind of the attribute -- graph (\sQuote{`g`}), vertex (\sQuote{`v`}) or edge (\sQuote{`e`}) -- is denoted, +#' and the type of the attribute as well, character (\sQuote{`c`}), numeric (\sQuote{`n`}), logical (\sQuote{`l`}), or other (\sQuote{`x`}). #' -#' As of igraph 0.4 `print_all()` and `print.igraph()` use the -#' `max.print` option, see [base::options()] for details. +#' As of igraph 0.4 `print_all()` and `print.igraph()` use the `max.print` option, see [base::options()] for details. #' -#' As of igraph 1.1.1, the `str.igraph` function is defunct, use -#' `print_all()`. +#' As of igraph 1.1.1, the `str.igraph` function is defunct, use `print_all()`. #' -#' Output style is controlled by the `print.style` igraph option. The default -#' `"cli"` produces cli-styled output with section rules, typed attribute -#' listings and Unicode arrows for edges. Set -#' `igraph_options(print.style = "classic")` for the historical -#' `IGRAPH ... DNW-` header relied on by parsers and tutorials. +#' Output style is controlled by the `print.style` igraph option. +#' The default `"cli"` produces cli-styled output with section rules, typed attribute listings and Unicode arrows for edges. +#' Set `igraph_options(print.style = "classic")` for the historical `IGRAPH ... DNW-` header relied on by parsers and tutorials. #' #' @aliases print.igraph print_all summary.igraph str.igraph #' @param x The graph to print. -#' @param full Logical, whether to print the graph structure itself as -#' well. The default `NULL` uses the `print.full` igraph option. -#' @param graph.attributes Logical, whether to print graph attributes. The -#' default `NULL` uses the `print.graph.attributes` igraph option. -#' @param vertex.attributes Logical, whether to print vertex -#' attributes. The default `NULL` uses the `print.vertex.attributes` igraph -#' option. -#' @param edge.attributes Logical, whether to print edge attributes. The -#' default `NULL` uses the `print.edge.attributes` igraph option. +#' @param full Logical, whether to print the graph structure itself as well. +#' The default `NULL` uses the `print.full` igraph option. +#' @param graph.attributes Logical, whether to print graph attributes. +#' The default `NULL` uses the `print.graph.attributes` igraph option. +#' @param vertex.attributes Logical, whether to print vertex attributes. +#' The default `NULL` uses the `print.vertex.attributes` igraph option. +#' @param edge.attributes Logical, whether to print edge attributes. +#' The default `NULL` uses the `print.edge.attributes` igraph option. #' @param names Logical, whether to print symbolic vertex names (i.e. #' the `name` vertex attribute) or vertex IDs. -#' @param max.lines The maximum number of lines to use. The rest of the -#' output will be truncated. If not given, the `auto.print.lines` igraph -#' option applies; `NULL` prints all lines. -#' @param id Whether to print the graph ID. The default `NULL` uses the -#' `print.id` igraph option. +#' @param max.lines The maximum number of lines to use. +#' The rest of the output will be truncated. +#' If not given, the `auto.print.lines` igraph option applies; `NULL` prints all lines. +#' @param id Whether to print the graph ID. +#' The default `NULL` uses the `print.id` igraph option. #' @param object The graph of which the summary will be printed. #' @param \dots Additional agruments. #' @return All these functions return the graph invisibly. @@ -720,8 +703,8 @@ is_cli_style <- function() { identical(igraph_opt("print.style"), "cli") } -# Emit a cli section rule. The leading blank line separates this section from -# the previous one; `blank = FALSE` omits it for the first (header) rule. +# Emit a cli section rule. +# The leading blank line separates this section from the previous one; `blank = FALSE` omits it for the first (header) rule. cli_section <- function(title, right = NULL, blank = TRUE) { rule <- if (is.null(right)) { cli::rule(left = title) @@ -746,10 +729,9 @@ print_cli_lines <- function(x, max.lines, omitted_footer) { } } -# Format edge endpoints as "tail head " strings. Endpoints are not -# padded to a common width, so each edge reads with a single space around the -# delimiter; the trailing space yields two spaces between edges once print() -# adds its own single-space separator. +# Format edge endpoints as "tail head " strings. +# Endpoints are not padded to a common width, so each edge reads with a single space around the delimiter; +# the trailing space yields two spaces between edges once print() adds its own single-space separator. format_cli_edge_endpoints <- function(endpoints, arrow) { paste0(endpoints[, 1], " ", arrow, " ", endpoints[, 2], " ") } @@ -853,9 +835,9 @@ print_igraph_attr_summary_cli <- function(x) { cli_section("Attributes") arrow <- if (cli::is_utf8_output()) "\u2192" else "->" - # Style names and type codes via cli's semantic classes (`.field`, `.cls`) - # rather than hand-picked colors, so cli's theme owns the palette and it - # respects NO_COLOR / non-tty output. `.cls` also supplies the `<...>`. + # Style names and type codes via cli's semantic classes (`.field`, `.cls`) rather than hand-picked colors, + # so cli's theme owns the palette and it respects NO_COLOR / non-tty output. + # `.cls` also supplies the `<...>`. format_line <- function(label, names, codes) { labels <- vapply(codes, attr_label_cli, character(1)) parts <- vapply( diff --git a/R/printr.R b/R/printr.R index 7f5294859a8..6c255a17cd8 100644 --- a/R/printr.R +++ b/R/printr.R @@ -1,7 +1,7 @@ #' Create a printer callback function #' -#' A printer callback function is a function can performs the actual -#' printing. It has a number of subcommands, that are called by +#' A printer callback function is a function can performs the actual printing. +#' It has a number of subcommands, that are called by #' the `printer` package, in a form \preformatted{ #' printer_callback("subcommand", argument1, argument2, ...) #' } See the examples below. @@ -63,17 +63,15 @@ print_head_foot <- function(head_foot) { #' Print the only the head of an R object #' -#' @param x The object to print, or a callback function. See -#' [printer_callback()] for details. -#' @param max_lines Maximum number of lines to print, *not* -#' including the header and the footer. +#' @param x The object to print, or a callback function. +#' See [printer_callback()] for details. +#' @param max_lines Maximum number of lines to print, *not* including the header and the footer. #' @param header The header, if a function, then it will be called, #' otherwise printed using `cat`. #' @param footer The footer, if a function, then it will be called, #' otherwise printed using `cat`. -#' @param omitted_footer Footer that is only printed if anything -#' is omitted from the printout. If a function, then it will be called, -#' otherwise printed using `cat`. +#' @param omitted_footer Footer that is only printed if anything is omitted from the printout. +#' If a function, then it will be called, otherwise printed using `cat`. #' @param ... Extra arguments to pass to `print()`. #' @return `x`, invisibly. #' @@ -136,7 +134,8 @@ head_print_callback <- function( minw <- x("min_width") ow <- getOption("width", 80) - ## Max number of items we can print. This is an upper bound. + ## Max number of items we can print. + ## This is an upper bound. can_max <- min(floor(ow / minw) * max_lines, len) if (can_max == 0) { return() @@ -189,8 +188,8 @@ head_print_callback <- function( #' #' @param ... Passed to the printing function. #' @param .indent Character scalar, indent the printout with this. -#' @param .printer The printing function. The default `NULL` uses -#' [print]. +#' @param .printer The printing function. +#' The default `NULL` uses [print]. #' @return The first element in `...`, invisibly. #' #' @export diff --git a/R/random_walk.R b/R/random_walk.R index c4c958db8dc..0f8b3d9d38f 100644 --- a/R/random_walk.R +++ b/R/random_walk.R @@ -1,13 +1,12 @@ #' Random walk on a graph #' -#' `random_walk()` performs a random walk on the graph and returns the -#' vertices that the random walk passed through. `random_edge_walk()` -#' is the same but returns the edges that that random walk passed through. +#' `random_walk()` performs a random walk on the graph and returns the vertices that the random walk passed through. +#' `random_edge_walk()` is the same but returns the edges that that random walk passed through. #' -#' Do a random walk. From the given start vertex, take the given number of -#' steps, choosing an edge from the actual vertex uniformly randomly. Edge -#' directions are observed in directed graphs (see the `mode` argument -#' as well). Multiple and loop edges are also observed. +#' Do a random walk. +#' From the given start vertex, take the given number of steps, choosing an edge from the actual vertex uniformly randomly. +#' Edge directions are observed in directed graphs (see the `mode` argument as well). +#' Multiple and loop edges are also observed. #' #' For igraph < 1.6.0, `random_walk()` counted steps differently, #' and returned a sequence of length `steps` instead of `steps + 1`. @@ -17,21 +16,19 @@ #' @param start The start vertex. #' @param steps The number of steps to make. #' @inheritParams rlang::args_dots_empty -#' @param weights The edge weights. Larger edge weights increase the -#' probability that an edge is selected by the random walker. In other -#' words, larger edge weights correspond to stronger connections. The -#' \sQuote{weight} edge attribute is used if present. Supply -#' \sQuote{`NA`} here if you want to ignore the \sQuote{weight} edge -#' attribute. -#' @param mode How to follow directed edges. `"out"` steps along the -#' edge direction, `"in"` is opposite to that. `"all"` ignores -#' edge directions. This argument is ignored for undirected graphs. -#' @param stuck What to do if the random walk gets stuck. `"return"` -#' returns the partial walk, `"error"` raises an error. -#' @return For `random_walk()`, a vertex sequence of length `steps + 1` -#' containing the vertices along the walk, starting with `start`. -#' For `random_edge_walk()`, an edge sequence of length `steps` containing -#' the edges along the walk. +#' @param weights The edge weights. +#' Larger edge weights increase the probability that an edge is selected by the random walker. +#' In other words, larger edge weights correspond to stronger connections. +#' The \sQuote{weight} edge attribute is used if present. +#' Supply \sQuote{`NA`} here if you want to ignore the \sQuote{weight} edge attribute. +#' @param mode How to follow directed edges. +#' `"out"` steps along the edge direction, `"in"` is opposite to that. +#' `"all"` ignores edge directions. +#' This argument is ignored for undirected graphs. +#' @param stuck What to do if the random walk gets stuck. +#' `"return"` returns the partial walk, `"error"` raises an error. +#' @return For `random_walk()`, a vertex sequence of length `steps + 1` containing the vertices along the walk, starting with `start`. +#' For `random_edge_walk()`, an edge sequence of length `steps` containing the edges along the walk. #' @family random_walk #' @export #' @examples diff --git a/R/rewire.R b/R/rewire.R index 775e449d68a..3f21a0e48b2 100644 --- a/R/rewire.R +++ b/R/rewire.R @@ -50,14 +50,12 @@ rewire <- function(graph, with) { #' Graph rewiring while preserving the degree distribution #' -#' This function can be used together with [rewire()] to -#' randomly rewire the edges while preserving the original graph's degree -#' distribution. +#' This function can be used together with [rewire()] to randomly rewire the edges +#' while preserving the original graph's degree distribution. #' -#' The rewiring algorithm chooses two arbitrary edges in each step ((a,b) -#' and (c,d)) and substitutes them with (a,d) and (c,b), if they not -#' already exists in the graph. The algorithm does not create multiple -#' edges. +#' The rewiring algorithm chooses two arbitrary edges in each step ((a,b) and (c,d)) and substitutes them with (a,d) and (c,b), +#' if they not already exists in the graph. +#' The algorithm does not create multiple edges. #' #' @param loops Whether to allow destroying and creating loop edges. #' @param niter Number of rewiring trials to perform. @@ -96,21 +94,18 @@ rewire_keeping_degseq <- function(graph, loops, niter) { #' Rewires the endpoints of the edges of a graph to a random vertex #' #' This function can be used together with [rewire()]. -#' This method rewires the endpoints of the edges with a constant probability -#' uniformly randomly to a new vertex in a graph. +#' This method rewires the endpoints of the edges with a constant probability uniformly randomly to a new vertex in a graph. #' #' Note that this method might create graphs with multiple and/or loop edges. #' #' @param prob The rewiring probability, a real number between zero and one. #' @inheritParams rlang::args_dots_empty -#' @param loops Logical, whether loop edges are allowed in the rewired -#' graph. -#' @param multiple Logical, whether multiple edges are allowed in the -#' generated graph. -#' @param mode Character string, specifies which endpoint of the edges to rewire -#' in directed graphs. \sQuote{all} rewires both endpoints, \sQuote{in} rewires -#' the start (tail) of each directed edge, \sQuote{out} rewires the end (head) -#' of each directed edge. Ignored for undirected graphs. +#' @param loops Logical, whether loop edges are allowed in the rewired graph. +#' @param multiple Logical, whether multiple edges are allowed in the generated graph. +#' @param mode Character string, specifies which endpoint of the edges to rewire in directed graphs. +#' \sQuote{all} rewires both endpoints, \sQuote{in} rewires the start (tail) of each directed edge, +#' \sQuote{out} rewires the end (head) of each directed edge. +#' Ignored for undirected graphs. #' #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @family rewiring functions diff --git a/R/scan.R b/R/scan.R index a719650c8d1..814de229752 100644 --- a/R/scan.R +++ b/R/scan.R @@ -23,59 +23,45 @@ #' Compute local scan statistics on graphs #' -#' The scan statistic is a summary of the locality statistics that is -#' computed from the local neighborhood of each vertex. The -#' `local_scan()` function computes the local statistics for each vertex -#' for a given neighborhood size and the statistic function. +#' The scan statistic is a summary of the locality statistics that is computed from the local neighborhood of each vertex. +#' The `local_scan()` function computes the local statistics for each vertex for a given neighborhood size and the statistic function. #' -#' See the given reference below for the details on the local scan -#' statistics. +#' See the given reference below for the details on the local scan statistics. #' #' `local_scan()` calculates exact local scan statistics. #' -#' If `graph.them` is `NULL`, then `local_scan()` computes the -#' \sQuote{us} variant of the scan statistics. Otherwise, -#' `graph.them` should be an igraph object and the \sQuote{them} -#' variant is computed using `graph.us` to extract the neighborhood -#' information, and applying `FUN` on these neighborhoods in -#' `graph.them`. +#' If `graph.them` is `NULL`, then `local_scan()` computes the \sQuote{us} variant of the scan statistics. +#' Otherwise, +#' `graph.them` should be an igraph object and the \sQuote{them} variant is computed using `graph.us` to extract the neighborhood information, +#' and applying `FUN` on these neighborhoods in `graph.them`. #' -#' @param graph.us,graph An igraph object, the graph for which the scan -#' statistics will be computed +#' @param graph.us,graph An igraph object, the graph for which the scan statistics will be computed #' @param graph.them An igraph object on which the \sQuote{them} statistics is computed, #' i.e. the neighborhoods calculated from `graph.us` are evaluated on `graph.them`. #' Default: `NULL`. -#' @param k An integer scalar, the size of the local neighborhood for each -#' vertex. Should be non-negative. -#' @param FUN Character, a function name, or a function object itself, for -#' computing the local statistic in each neighborhood. If `NULL`(the -#' default value), `ecount()` is used for unweighted graphs (if -#' `weighted=FALSE`) and a function that computes the sum of edge -#' weights is used for weighted graphs (if `weighted=TRUE`). This -#' argument is ignored if `k` is zero. -#' @param weighted Logical, TRUE if the edge weights should be used -#' for computation of the scan statistic. If TRUE, the graph should be -#' weighted. Note that this argument is ignored if `FUN` is not -#' `NULL`, `"ecount"` and `"sumweights"`. -#' @param mode Character scalar, the kind of neighborhoods to use for the -#' calculation. One of \sQuote{`out`}, \sQuote{`in`}, -#' \sQuote{`all`} or \sQuote{`total`}. This argument is ignored -#' for undirected graphs. -#' @param neighborhoods A list of neighborhoods, one for each vertex, or -#' `NULL`. If it is not `NULL`, then the function is evaluated on -#' the induced subgraphs specified by these neighborhoods. +#' @param k An integer scalar, the size of the local neighborhood for each vertex. +#' Should be non-negative. +#' @param FUN Character, a function name, or a function object itself, for computing the local statistic in each neighborhood. +#' If `NULL`(the default value), +#' `ecount()` is used for unweighted graphs (if `weighted=FALSE`) and a function that computes the sum of edge weights is used for weighted graphs (if `weighted=TRUE`). +#' This argument is ignored if `k` is zero. +#' @param weighted Logical, TRUE if the edge weights should be used for computation of the scan statistic. +#' If TRUE, the graph should be weighted. +#' Note that this argument is ignored if `FUN` is not `NULL`, `"ecount"` and `"sumweights"`. +#' @param mode Character scalar, the kind of neighborhoods to use for the calculation. +#' One of \sQuote{`out`}, \sQuote{`in`}, \sQuote{`all`} or \sQuote{`total`}. +#' This argument is ignored for undirected graphs. +#' @param neighborhoods A list of neighborhoods, one for each vertex, or `NULL`. +#' If it is not `NULL`, then the function is evaluated on the induced subgraphs specified by these neighborhoods. #' -#' In theory this could be useful if the same `graph.us` graph is used -#' for multiple `graph.them` arguments. Then the neighborhoods can be -#' calculated on `graph.us` and used with multiple graphs. In -#' practice, this is currently slower than simply using `graph.them` -#' multiple times. -#' @param weights Numeric vector, edge weights to use for the scan instead of the edge attribute weight. If `NULL` (the default) the edge weight attribute is used. -#' @param \dots Arguments passed to `FUN`, the function that computes -#' the local statistics. -#' @return For `local_scan()` typically a numeric vector containing the -#' computed local statistics for each vertex. In general a list or vector -#' of objects, as returned by `FUN`. +#' In theory this could be useful if the same `graph.us` graph is used for multiple `graph.them` arguments. +#' Then the neighborhoods can be calculated on `graph.us` and used with multiple graphs. +#' In practice, this is currently slower than simply using `graph.them` multiple times. +#' @param weights Numeric vector, edge weights to use for the scan instead of the edge attribute weight. +#' If `NULL` (the default) the edge weight attribute is used. +#' @param \dots Arguments passed to `FUN`, the function that computes the local statistics. +#' @return For `local_scan()` typically a numeric vector containing the computed local statistics for each vertex. +#' In general a list or vector of objects, as returned by `FUN`. #' #' @references Priebe, C. E., Conroy, J. M., Marchette, D. J., Park, #' Y. (2005). Scan Statistics on Enron Graphs. *Computational and @@ -310,22 +296,17 @@ local_scan <- function( #' Scan statistics on a time series of graphs #' #' Calculate scan statistics on a time series of graphs. -#' This is done by calculating the local scan statistics for -#' each graph and each vertex, and then normalizing across the -#' vertices and across the time steps. +#' This is done by calculating the local scan statistics for each graph and each vertex, +#' and then normalizing across the vertices and across the time steps. #' -#' @param graphs A list of igraph graph objects. They must be all directed -#' or all undirected and they must have the same number of vertices. -#' @param tau The number of previous time steps to consider for the -#' time-dependent normalization for individual vertices. In other words, -#' the current locality statistics of each vertex will be compared to this -#' many previous time steps of the same vertex to decide whether it is -#' significantly larger. -#' @param ell The number of previous time steps to consider -#' for the aggregated scan statistics. This is essentially a smoothing -#' parameter. -#' @param locality Whether to calculate the \sQuote{us} or \sQuote{them} -#' statistics. +#' @param graphs A list of igraph graph objects. +#' They must be all directed or all undirected and they must have the same number of vertices. +#' @param tau The number of previous time steps to consider for the time-dependent normalization for individual vertices. +#' In other words, +#' the current locality statistics of each vertex will be compared to this many previous time steps of the same vertex to decide whether it is significantly larger. +#' @param ell The number of previous time steps to consider for the aggregated scan statistics. +#' This is essentially a smoothing parameter. +#' @param locality Whether to calculate the \sQuote{us} or \sQuote{them} statistics. #' @param ... Extra arguments are passed to [local_scan()]. #' @return A list with entries: #' \describe{ diff --git a/R/sgm.R b/R/sgm.R index 29e6cf93453..3025361f602 100644 --- a/R/sgm.R +++ b/R/sgm.R @@ -34,40 +34,31 @@ solve_LSAP <- function(x, maximum = FALSE) { #' Match Graphs given a seeding of vertex correspondences #' -#' Given two adjacency matrices `A` and `B` of the same size, match -#' the two graphs with the help of `m` seed vertex pairs which correspond -#' to the first `m` rows (and columns) of the adjacency matrices. +#' Given two adjacency matrices `A` and `B` of the same size, +#' match the two graphs with the help of `m` seed vertex pairs +#' which correspond to the first `m` rows (and columns) of the adjacency matrices. #' -#' The approximate graph matching problem is to find a bijection between the -#' vertices of two graphs , such that the number of edge disagreements between -#' the corresponding vertex pairs is minimized. For seeded graph matching, part -#' of the bijection that consist of known correspondences (the seeds) is known -#' and the problem task is to complete the bijection by estimating the -#' permutation matrix that permutes the rows and columns of the adjacency -#' matrix of the second graph. +#' The approximate graph matching problem is to find a bijection between the vertices of two graphs , such that the number of edge disagreements between the corresponding vertex pairs is minimized. +#' For seeded graph matching, +#' part of the bijection that consist of known correspondences (the seeds) is known and the problem task is to complete the bijection by estimating the permutation matrix that permutes the rows and columns of the adjacency matrix of the second graph. #' -#' It is assumed that for the two supplied adjacency matrices `A` and -#' `B`, both of size \eqn{n\times n}{n*n}, the first \eqn{m} rows(and -#' columns) of `A` and `B` correspond to the same vertices in both -#' graphs. That is, the \eqn{n \times n}{n*n} permutation matrix that defines -#' the bijection is \eqn{I_{m} \bigoplus P} for a \eqn{(n-m)\times +#' It is assumed that for the two supplied adjacency matrices `A` and `B`, both of size \eqn{n\times n}{n*n}, +#' the first \eqn{m} rows(and columns) of `A` and `B` correspond to the same vertices in both graphs. +#' That is, the \eqn{n \times n}{n*n} permutation matrix that defines the bijection is \eqn{I_{m} \bigoplus P} for a \eqn{(n-m)\times #' (n-m)}{(n-m)*(n-m)} permutation matrix \eqn{P} and \eqn{m} times \eqn{m} -#' identity matrix \eqn{I_{m}}. The function `match_vertices()` estimates -#' the permutation matrix \eqn{P} via an optimization algorithm based on the -#' Frank-Wolfe algorithm. +#' identity matrix \eqn{I_{m}}. +#' The function `match_vertices()` estimates the permutation matrix \eqn{P} via an optimization algorithm based on the Frank-Wolfe algorithm. #' #' See references for further details. #' #' @aliases seeded.graph.match #' @param A a numeric matrix, the adjacency matrix of the first graph #' @param B a numeric matrix, the adjacency matrix of the second graph -#' @param m The number of seeds. The first `m` vertices of both graphs are -#' matched. -#' @param start a numeric matrix, the permutation matrix estimate is -#' initialized with `start` +#' @param m The number of seeds. +#' The first `m` vertices of both graphs are matched. +#' @param start a numeric matrix, the permutation matrix estimate is initialized with `start` #' @param iteration The number of iterations for the Frank-Wolfe algorithm -#' @return A numeric matrix which is the permutation matrix that determines the -#' bijection between the graphs of `A` and `B` +#' @return A numeric matrix which is the permutation matrix that determines the bijection between the graphs of `A` and `B` #' @author Vince Lyzinski #' @seealso #' [sample_correlated_gnp()],[sample_correlated_gnp_pair()] diff --git a/R/similarity.R b/R/similarity.R index 1b4b2313b15..e82e6d531e8 100644 --- a/R/similarity.R +++ b/R/similarity.R @@ -1,43 +1,36 @@ #' Similarity measures of two vertices #' -#' These functions calculates similarity scores for vertices based on their -#' connection patterns. +#' These functions calculates similarity scores for vertices based on their connection patterns. #' #' @details -#' The Jaccard similarity coefficient of two vertices is the number of common -#' neighbors divided by the number of vertices that are neighbors of at least -#' one of the two vertices being considered. The `jaccard` method -#' calculates the pairwise Jaccard similarities for some (or all) of the -#' vertices. +#' The Jaccard similarity coefficient of two vertices is the number of common neighbors divided by the number of vertices that are neighbors of at least one of the two vertices being considered. +#' The `jaccard` method calculates the pairwise Jaccard similarities for some (or all) of the vertices. #' -#' The Dice similarity coefficient of two vertices is twice the number of -#' common neighbors divided by the sum of the degrees of the vertices. -#' Methof `dice` calculates the pairwise Dice similarities for some -#' (or all) of the vertices. +#' The Dice similarity coefficient of two vertices is twice the number of common neighbors divided by the sum of the degrees of the vertices. +#' Methof `dice` calculates the pairwise Dice similarities for some (or all) of the vertices. #' -#' The inverse log-weighted similarity of two vertices is the number of their -#' common neighbors, weighted by the inverse logarithm of their degrees. It is -#' based on the assumption that two vertices should be considered more similar -#' if they share a low-degree common neighbor, since high-degree common -#' neighbors are more likely to appear even by pure chance. Isolated vertices -#' will have zero similarity to any other vertex. Self-similarities are not -#' calculated. See the following paper for more details: Lada A. Adamic and -#' Eytan Adar: Friends and neighbors on the Web. Social Networks, -#' 25(3):211-230, 2003. +#' The inverse log-weighted similarity of two vertices is the number of their common neighbors, +#' weighted by the inverse logarithm of their degrees. +#' It is based on the assumption that two vertices should be considered more similar +#' if they share a low-degree common neighbor, +#' since high-degree common neighbors are more likely to appear even by pure chance. +#' Isolated vertices will have zero similarity to any other vertex. +#' Self-similarities are not calculated. +#' See the following paper for more details: +#' Lada A. Adamic and Eytan Adar: Friends and neighbors on the Web. +#' Social Networks, 25(3):211-230, 2003. #' #' @param graph The input graph. -#' @param vids The vertex IDs for which the similarity is calculated. The -#' default `NULL` selects all vertices. +#' @param vids The vertex IDs for which the similarity is calculated. +#' The default `NULL` selects all vertices. #' @inheritParams rlang::args_dots_empty #' @param mode The type of neighboring vertices to use for the calculation, #' possible values: \sQuote{`out`}, \sQuote{`in`}, #' \sQuote{`all`}. -#' @param loops Whether to include vertices themselves in the neighbor -#' sets. +#' @param loops Whether to include vertices themselves in the neighbor sets. #' @param method The method to use. -#' @return A `length(vids)` by `length(vids)` numeric matrix -#' containing the similarity scores. This argument is ignored by the -#' `invlogweighted` method. +#' @return A `length(vids)` by `length(vids)` numeric matrix containing the similarity scores. +#' This argument is ignored by the `invlogweighted` method. #' @author Tamas Nepusz \email{ntamas@@gmail.com} and Gabor Csardi #' \email{csardi.gabor@@gmail.com} for the manual page. #' @references Lada A. Adamic and Eytan Adar: Friends and neighbors on the Web. diff --git a/R/simple.R b/R/simple.R index 9276307ac24..07b251b5e2e 100644 --- a/R/simple.R +++ b/R/simple.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `is.simple()` was renamed to [is_simple()] to create a more -#' consistent API. +#' `is.simple()` was renamed to [is_simple()] to create a more consistent API. #' @inheritParams is_simple #' @keywords internal #' @export @@ -41,44 +40,35 @@ is.simple <- function(graph) { #' #' Simple graphs are graphs which do not contain loop and multiple edges. #' -#' A loop edge is an edge for which the two endpoints are the same -#' vertex. Two edges are multiple edges if they have exactly the same two -#' endpoints (for directed graphs order does matter). A graph is simple is -#' it does not contain loop edges and multiple edges. +#' A loop edge is an edge for which the two endpoints are the same vertex. +#' Two edges are multiple edges if they have exactly the same two endpoints (for directed graphs order does matter). +#' A graph is simple is it does not contain loop edges and multiple edges. #' #' `is_simple()` checks whether a graph is simple. #' -#' `simplify()` removes the loop and/or multiple edges from a graph. If -#' both `remove.loops` and `remove.multiple` are `TRUE` the -#' function returns a simple graph. If the graph is already simple, it is -#' returned unchanged. +#' `simplify()` removes the loop and/or multiple edges from a graph. +#' If both `remove.loops` and `remove.multiple` are `TRUE` the function returns a simple graph. +#' If the graph is already simple, it is returned unchanged. #' -#' `simplify_and_colorize()` constructs a new, simple graph from a graph and -#' also sets a `color` attribute on both the vertices and the edges. -#' The colors of the vertices represent the number of self-loops that were -#' originally incident on them, while the colors of the edges represent the -#' multiplicities of the same edges in the original graph. This allows one to -#' take into account the edge multiplicities and the number of loop edges in -#' the VF2 isomorphism algorithm. Other graph, vertex and edge attributes from -#' the original graph are discarded as the primary purpose of this function is -#' to facilitate the usage of multigraphs with the VF2 algorithm. +#' `simplify_and_colorize()` constructs a new, +#' simple graph from a graph and also sets a `color` attribute on both the vertices and the edges. +#' The colors of the vertices represent the number of self-loops that were originally incident on them, +#' while the colors of the edges represent the multiplicities of the same edges in the original graph. +#' This allows one to take into account the edge multiplicities and the number of loop edges in the VF2 isomorphism algorithm. +#' Other graph, +#' vertex and edge attributes from the original graph are discarded as the primary purpose of this function is to facilitate the usage of multigraphs with the VF2 algorithm. #' #' @aliases simplify #' @param graph The graph to work on. #' @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 -#' `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. The default `NULL` uses -#' the `edge.attr.comb` igraph option. -#' @return a graph object with the loop and/or multiple edges removed; the -#' input graph is returned unchanged if it is already simple. +#' @param remove.multiple Logical, whether the multiple edges are to be removed. +#' @param edge.attr.comb 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. +#' The default `NULL` uses the `edge.attr.comb` igraph option. +#' @return a graph object with the loop and/or multiple edges removed; the input graph is returned unchanged if it is already simple. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso [which_loop()], [which_multiple()] and -#' [count_multiple()], [delete_edges()], -#' [delete_vertices()] +#' @seealso [which_loop()], [which_multiple()] and [count_multiple()], [delete_edges()], [delete_vertices()] #' @keywords graphs #' @examples #' @@ -97,31 +87,23 @@ simplify <- function( remove.loops = TRUE, edge.attr.comb = NULL ) { - # There was a short-circuit here -- `if (is_simple(graph)) return(graph)` -- - # on the grounds that a graph with no loops and no multiple edges has - # nothing for simplify_impl() to remove. That is true of its *structure* and - # false of its attributes: `edge.attr.comb` does not only combine attributes - # across merged edges, it decides which survive at all, and an attribute the - # combination list does not name is dropped even when every group has one - # member. The default list ends in `"ignore"`, so `simplify(g)` on a simple - # graph is meant to keep `weight` and drop everything else, and - # `edge.attr.comb = "ignore"` is meant to leave no edge attributes at all. + # There was a short-circuit here -- `if (is_simple(graph)) return(graph)` -- on the grounds that a graph with no loops and no multiple edges has nothing for simplify_impl() to remove. + # That is true of its *structure* and false of its attributes: `edge.attr.comb` does not only combine attributes across merged edges, + # it decides which survive at all, and an attribute the combination list does not name is dropped even when every group has one member. + # The default list ends in `"ignore"`, so `simplify(g)` on a simple graph is meant to keep `weight` and drop everything else, + # and `edge.attr.comb = "ignore"` is meant to leave no edge attributes at all. # Returning `graph` untouched silently kept them both. # - # Guarding the short-circuit on the graph having no edge attributes does not - # fix it, which is the part worth remembering: `is_simple()` populates the - # C core's property cache, and `simplify.c` has a cache fast path of its own - # that returns early without applying `edge_comb` once the cache says there - # is nothing to remove. So merely *asking* whether the graph is simple - # changes what simplifying it does. On 2.3.3 that made the result depend on - # whether anything had happened to touch the cache first; the short-circuit - # made the cache-warm answer the only answer. + # Guarding the short-circuit on the graph having no edge attributes does not fix it, which is the part worth remembering: + # `is_simple()` populates the C core's property cache, + # and `simplify.c` has a cache fast path of its own that returns early without applying `edge_comb` once the cache says there is nothing to remove. + # So merely *asking* whether the graph is simple changes what simplifying it does. + # On 2.3.3 that made the result depend on whether anything had happened to touch the cache first; + # the short-circuit made the cache-warm answer the only answer. # - # The check therefore lives at the call site that wants it -- - # `graph_from_literal_i()`, which is what #824 and #1981 were about, and - # which simplifies a graph it has only just built from the formula, before - # any attribute is set on it. Everywhere else `simplify()` goes through - # `simplify_impl()` as it always did. + # The check therefore lives at the call site that wants it -- `graph_from_literal_i()`, which is what #824 and #1981 were about, + # and which simplifies a graph it has only just built from the formula, before any attribute is set on it. + # Everywhere else `simplify()` goes through `simplify_impl()` as it always did. if (is.null(edge.attr.comb)) { edge.attr.comb <- igraph_opt("edge.attr.comb") } diff --git a/R/sir.R b/R/sir.R index efc2d8056c3..58a0a54447e 100644 --- a/R/sir.R +++ b/R/sir.R @@ -23,55 +23,49 @@ #' SIR model on graphs #' -#' Run simulations for an SIR (susceptible-infected-recovered) model, on a -#' graph +#' Run simulations for an SIR (susceptible-infected-recovered) model, on a graph #' -#' The SIR model is a simple model from epidemiology. The individuals of the -#' population might be in three states: susceptible, infected and recovered. -#' Recovered people are assumed to be immune to the disease. Susceptibles -#' become infected with a rate that depends on their number of infected -#' neighbors. Infected people become recovered with a constant rate. +#' The SIR model is a simple model from epidemiology. +#' The individuals of the population might be in three states: susceptible, infected and recovered. +#' Recovered people are assumed to be immune to the disease. +#' Susceptibles become infected with a rate that depends on their number of infected neighbors. +#' Infected people become recovered with a constant rate. #' -#' The function `sir()` simulates the model. This function runs multiple -#' simulations, all starting with a single uniformly randomly chosen infected -#' individual. A simulation is stopped when no infected individuals are left. +#' The function `sir()` simulates the model. +#' This function runs multiple simulations, all starting with a single uniformly randomly chosen infected individual. +#' A simulation is stopped when no infected individuals are left. #' -#' Function `time_bins()` bins the simulation steps, using the -#' Freedman-Diaconis heuristics to determine the bin width. +#' Function `time_bins()` bins the simulation steps, using the Freedman-Diaconis heuristics to determine the bin width. #' -#' Function `median` and `quantile` calculate the median and -#' quantiles of the results, respectively, in bins calculated with -#' `time_bins()`. +#' Function `median` and `quantile` calculate the median and quantiles of the results, respectively, in bins calculated with `time_bins()`. #' #' @aliases median.sir quantile.sir -#' @param graph The graph to run the model on. If directed, then edge -#' directions are ignored and a warning is given. -#' @param beta Non-negative scalar. The rate of infection of an individual that -#' is susceptible and has a single infected neighbor. The infection rate of a -#' susceptible individual with n infected neighbors is n times beta. Formally -#' this is the rate parameter of an exponential distribution. -#' @param gamma Positive scalar. The rate of recovery of an infected -#' individual. Formally, this is the rate parameter of an exponential -#' distribution. -#' @param \dots For `sir()` and `time_bins()`, these dots must be empty. For -#' `median.sir()` and `quantile.sir()`, unused, present for S3 method -#' consistency. +#' @param graph The graph to run the model on. +#' If directed, then edge directions are ignored and a warning is given. +#' @param beta Non-negative scalar. +#' The rate of infection of an individual that is susceptible and has a single infected neighbor. +#' The infection rate of a susceptible individual with n infected neighbors is n times beta. +#' Formally this is the rate parameter of an exponential distribution. +#' @param gamma Positive scalar. +#' The rate of recovery of an infected individual. +#' Formally, this is the rate parameter of an exponential distribution. +#' @param \dots For `sir()` and `time_bins()`, these dots must be empty. +#' For `median.sir()` and `quantile.sir()`, unused, present for S3 method consistency. #' @param no.sim Integer scalar, the number simulation runs to perform. #' @param x A `sir` object, returned by the `sir()` function. #' @param middle Logical, whether to return the middle of the time bins, #' or the boundaries. -#' @param na.rm Logical, whether to ignore `NA` values. `sir` -#' objects do not contain any `NA` values currently, so this argument is -#' effectively ignored. -#' @param comp Character scalar. The component to calculate the quantile of. -#' `NI` is infected agents, `NS` is susceptibles, `NR` stands -#' for recovered. -#' @param prob Numeric vector of probabilities, in \[0,1\], they specify the -#' quantiles to calculate. -#' @return For `sir()` the results are returned in an object of class -#' \sQuote{`sir`}, which is a list, with one element for each simulation. -#' Each simulation is itself a list with the following elements. They are all -#' numeric vectors, with equal length: +#' @param na.rm Logical, whether to ignore `NA` values. +#' `sir` objects do not contain any `NA` values currently, +#' so this argument is effectively ignored. +#' @param comp Character scalar. +#' The component to calculate the quantile of. +#' `NI` is infected agents, `NS` is susceptibles, `NR` stands for recovered. +#' @param prob Numeric vector of probabilities, in \[0,1\], they specify the quantiles to calculate. +#' @return For `sir()` the results are returned in an object of class \sQuote{`sir`}, which is a list, +#' with one element for each simulation. +#' Each simulation is itself a list with the following elements. +#' They are all numeric vectors, with equal length: #' \describe{ #' \item{times}{ #' The times of the events. @@ -87,16 +81,13 @@ #' } #' } #' -#' Function `time_bins()` returns a numeric vector, the middle or the -#' boundaries of the time bins, depending on the `middle` argument. +#' Function `time_bins()` returns a numeric vector, the middle or the boundaries of the time bins, depending on the `middle` argument. #' -#' `median` returns a list of three named numeric vectors, `NS`, -#' `NI` and `NR`. The names within the vectors are created from the -#' time bins. +#' `median` returns a list of three named numeric vectors, `NS`, `NI` and `NR`. +#' The names within the vectors are created from the time bins. #' -#' `quantile` returns the same vector as `median` (but only one, the -#' one requested) if only one quantile is requested. If multiple quantiles are -#' requested, then a list of these vectors is returned, one for each quantile. +#' `quantile` returns the same vector as `median` (but only one, the one requested) if only one quantile is requested. +#' If multiple quantiles are requested, then a list of these vectors is returned, one for each quantile. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com}. Eric Kolaczyk #' () wrote the initial version in R. #' @seealso [plot.sir()] to conveniently plot the results diff --git a/R/sparsedf.R b/R/sparsedf.R index 3d4ffd22d55..b5807d5f14e 100644 --- a/R/sparsedf.R +++ b/R/sparsedf.R @@ -19,9 +19,8 @@ # ################################################################### -# This is a sparse data frame. It is like a regular data frame, -# but it allows for some columns to be constant, and then it -# stores that column more economically. +# This is a sparse data frame. +# It is like a regular data frame, but it allows for some columns to be constant, and then it stores that column more economically. sdf <- function(..., row.names = NULL, NROW = NULL) { cols <- list(...) diff --git a/R/stochastic_matrix.R b/R/stochastic_matrix.R index 9b920f8d756..dd63f653b8b 100644 --- a/R/stochastic_matrix.R +++ b/R/stochastic_matrix.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `get.stochastic()` was renamed to [stochastic_matrix()] to create a more -#' consistent API. +#' `get.stochastic()` was renamed to [stochastic_matrix()] to create a more consistent API. #' @inheritParams stochastic_matrix #' @keywords internal #' @export @@ -42,23 +41,21 @@ get.stochastic <- function( #' #' Retrieves the stochastic matrix of a graph of class `igraph`. #' -#' Let \eqn{M} be an \eqn{n \times n}{n x n} adjacency matrix with real -#' non-negative entries. Let us define \eqn{D = \textrm{diag}(\sum_{i}M_{1i}, +#' Let \eqn{M} be an \eqn{n \times n}{n x n} adjacency matrix with real non-negative entries. +#' Let us define \eqn{D = \textrm{diag}(\sum_{i}M_{1i}, #' \dots, \sum_{i}M_{ni})}{D=diag( sum(M[1,i], i), ..., sum(M[n,i], i) )} #' -#' The (row) stochastic matrix is defined as \deqn{W = D^{-1}M,}{W = inv(D) M,} -#' where it is assumed that \eqn{D} is non-singular. Column stochastic -#' matrices are defined in a symmetric way. +#' The (row) stochastic matrix is defined as \deqn{W = D^{-1}M,}{W = inv(D) M,} where it is assumed that \eqn{D} is non-singular. +#' Column stochastic matrices are defined in a symmetric way. #' -#' @param graph The input graph. Must be of class `igraph`. +#' @param graph The input graph. +#' Must be of class `igraph`. #' @inheritParams rlang::args_dots_empty -#' @param column.wise If `FALSE`, then the rows of the stochastic matrix -#' sum up to one; otherwise it is the columns. -#' @param sparse Logical, whether to return a sparse matrix. The -#' `Matrix` package is needed for sparse matrices. The default `NULL` uses -#' the `sparsematrices` igraph option. -#' @return A regular matrix or a matrix of class `Matrix` if a -#' `sparse` argument was `TRUE`. +#' @param column.wise If `FALSE`, then the rows of the stochastic matrix sum up to one; otherwise it is the columns. +#' @param sparse Logical, whether to return a sparse matrix. +#' The `Matrix` package is needed for sparse matrices. +#' The default `NULL` uses the `sparsematrices` igraph option. +#' @return A regular matrix or a matrix of class `Matrix` if a `sparse` argument was `TRUE`. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @seealso [as_adjacency_matrix()] #' @export diff --git a/R/structural-properties.R b/R/structural-properties.R index 6206c631c40..22cb5132957 100644 --- a/R/structural-properties.R +++ b/R/structural-properties.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `get.shortest.paths()` was renamed to [shortest_paths()] to create a more -#' consistent API. +#' `get.shortest.paths()` was renamed to [shortest_paths()] to create a more consistent API. #' @inheritParams shortest_paths #' @keywords internal #' @export @@ -39,8 +38,7 @@ get.shortest.paths <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `get.all.shortest.paths()` was renamed to [all_shortest_paths()] to create a more -#' consistent API. +#' `get.all.shortest.paths()` was renamed to [all_shortest_paths()] to create a more consistent API. #' @inheritParams all_shortest_paths #' @keywords internal #' @export @@ -71,8 +69,7 @@ get.all.shortest.paths <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `get.diameter()` was renamed to [get_diameter()] to create a more -#' consistent API. +#' `get.diameter()` was renamed to [get_diameter()] to create a more consistent API. #' @inheritParams get_diameter #' @keywords internal #' @export @@ -97,8 +94,7 @@ get.diameter <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `unfold.tree()` was renamed to [unfold_tree()] to create a more -#' consistent API. +#' `unfold.tree()` was renamed to [unfold_tree()] to create a more consistent API. #' @inheritParams unfold_tree #' @keywords internal #' @export @@ -113,8 +109,7 @@ unfold.tree <- function(graph, mode = c("all", "out", "in", "total"), roots) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `topological.sort()` was renamed to [topo_sort()] to create a more -#' consistent API. +#' `topological.sort()` was renamed to [topo_sort()] to create a more consistent API. #' @inheritParams topo_sort #' @keywords internal #' @export @@ -129,8 +124,7 @@ topological.sort <- function(graph, mode = c("out", "all", "in")) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `shortest.paths()` was renamed to [distances()] to create a more -#' consistent API. +#' `shortest.paths()` was renamed to [distances()] to create a more consistent API. #' @inheritParams distances #' @keywords internal #' @export @@ -167,8 +161,7 @@ shortest.paths <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `neighborhood.size()` was renamed to [ego_size()] to create a more -#' consistent API. +#' `neighborhood.size()` was renamed to [ego_size()] to create a more consistent API. #' @inheritParams ego_size #' @keywords internal #' @export @@ -195,8 +188,7 @@ neighborhood.size <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `maximum.bipartite.matching()` was renamed to [max_bipartite_match()] to create a more -#' consistent API. +#' `maximum.bipartite.matching()` was renamed to [max_bipartite_match()] to create a more consistent API. #' @inheritParams max_bipartite_match #' @keywords internal #' @export @@ -225,8 +217,7 @@ maximum.bipartite.matching <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `is.mutual()` was renamed to [which_mutual()] to create a more -#' consistent API. +#' `is.mutual()` was renamed to [which_mutual()] to create a more consistent API. #' @inheritParams which_mutual #' @keywords internal #' @export @@ -241,8 +232,7 @@ is.mutual <- function(graph, eids = E(graph), loops = TRUE) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `is.multiple()` was renamed to [which_multiple()] to create a more -#' consistent API. +#' `is.multiple()` was renamed to [which_multiple()] to create a more consistent API. #' @inheritParams which_multiple #' @keywords internal #' @export @@ -257,8 +247,7 @@ is.multiple <- function(graph, eids = E(graph)) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `is.maximal.matching()` was renamed to [is_max_matching()] to create a more -#' consistent API. +#' `is.maximal.matching()` was renamed to [is_max_matching()] to create a more consistent API. #' @inheritParams is_max_matching #' @keywords internal #' @export @@ -277,8 +266,7 @@ is.maximal.matching <- function(graph, matching, types = NULL) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `is.matching()` was renamed to [is_matching()] to create a more -#' consistent API. +#' `is.matching()` was renamed to [is_matching()] to create a more consistent API. #' @inheritParams is_matching #' @keywords internal #' @export @@ -293,8 +281,7 @@ is.matching <- function(graph, matching, types = NULL) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `is.loop()` was renamed to [which_loop()] to create a more -#' consistent API. +#' `is.loop()` was renamed to [which_loop()] to create a more consistent API. #' @inheritParams which_loop #' @keywords internal #' @export @@ -309,8 +296,7 @@ is.loop <- function(graph, eids = E(graph)) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `is.connected()` was renamed to [is_connected()] to create a more -#' consistent API. +#' `is.connected()` was renamed to [is_connected()] to create a more consistent API. #' @inheritParams is_connected #' @keywords internal #' @export @@ -325,8 +311,7 @@ is.connected <- function(graph, mode = c("weak", "strong")) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `induced.subgraph()` was renamed to [induced_subgraph()] to create a more -#' consistent API. +#' `induced.subgraph()` was renamed to [induced_subgraph()] to create a more consistent API. #' @inheritParams induced_subgraph #' @keywords internal #' @export @@ -345,8 +330,7 @@ induced.subgraph <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `has.multiple()` was renamed to [any_multiple()] to create a more -#' consistent API. +#' `has.multiple()` was renamed to [any_multiple()] to create a more consistent API. #' @inheritParams any_multiple #' @keywords internal #' @export @@ -361,8 +345,7 @@ has.multiple <- function(graph) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.neighborhood()` was renamed to [make_ego_graph()] to create a more -#' consistent API. +#' `graph.neighborhood()` was renamed to [make_ego_graph()] to create a more consistent API. #' @inheritParams make_ego_graph #' @keywords internal #' @export @@ -389,8 +372,7 @@ graph.neighborhood <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.laplacian()` was renamed to [laplacian_matrix()] to create a more -#' consistent API. +#' `graph.laplacian()` was renamed to [laplacian_matrix()] to create a more consistent API. #' @inheritParams laplacian_matrix #' @keywords internal #' @export @@ -415,8 +397,7 @@ graph.laplacian <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.knn()` was renamed to [knn()] to create a more -#' consistent API. +#' `graph.knn()` was renamed to [knn()] to create a more consistent API. #' @inheritParams knn #' @keywords internal #' @export @@ -443,8 +424,7 @@ graph.knn <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.dfs()` was renamed to [dfs()] to create a more -#' consistent API. +#' `graph.dfs()` was renamed to [dfs()] to create a more consistent API. #' @param father Logical, whether to return the father of the vertices. #' @inheritParams dfs #' @keywords internal @@ -488,8 +468,7 @@ graph.dfs <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.density()` was renamed to [edge_density()] to create a more -#' consistent API. +#' `graph.density()` was renamed to [edge_density()] to create a more consistent API. #' @inheritParams edge_density #' @keywords internal #' @export @@ -504,8 +483,7 @@ graph.density <- function(graph, loops = FALSE) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.coreness()` was renamed to [coreness()] to create a more -#' consistent API. +#' `graph.coreness()` was renamed to [coreness()] to create a more consistent API. #' @inheritParams coreness #' @keywords internal #' @export @@ -520,8 +498,7 @@ graph.coreness <- function(graph, mode = c("all", "out", "in")) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.bfs()` was renamed to [bfs()] to create a more -#' consistent API. +#' `graph.bfs()` was renamed to [bfs()] to create a more consistent API. #' @inheritParams bfs #' @param father Logical, whether to return the father of the vertices. #' @keywords internal @@ -569,8 +546,7 @@ graph.bfs <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `farthest.nodes()` was renamed to [farthest_vertices()] to create a more -#' consistent API. +#' `farthest.nodes()` was renamed to [farthest_vertices()] to create a more consistent API. #' @inheritParams farthest_vertices #' @keywords internal #' @export @@ -595,8 +571,7 @@ farthest.nodes <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `degree.distribution()` was renamed to [degree_distribution()] to create a more -#' consistent API. +#' `degree.distribution()` was renamed to [degree_distribution()] to create a more consistent API. #' @inheritParams degree_distribution #' @keywords internal #' @export @@ -615,8 +590,7 @@ degree.distribution <- function(graph, cumulative = FALSE, ...) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `count.multiple()` was renamed to [count_multiple()] to create a more -#' consistent API. +#' `count.multiple()` was renamed to [count_multiple()] to create a more consistent API. #' @inheritParams count_multiple #' @keywords internal #' @export @@ -631,8 +605,7 @@ count.multiple <- function(graph, eids = E(graph)) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `clusters()` was renamed to [components()] to create a more -#' consistent API. +#' `clusters()` was renamed to [components()] to create a more consistent API. #' @inheritParams components #' @keywords internal #' @export @@ -647,8 +620,7 @@ clusters <- function(graph, mode = c("weak", "strong")) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `average.path.length()` was renamed to [mean_distance()] to create a more -#' consistent API. +#' `average.path.length()` was renamed to [mean_distance()] to create a more consistent API. #' @inheritParams mean_distance #' @keywords internal #' @export @@ -700,28 +672,22 @@ average.path.length <- function( #' #' The diameter is calculated by using a breadth-first search like method. #' -#' `get_diameter()` returns a path with the actual diameter. If there are -#' many shortest paths of the length of the diameter, then it returns the first -#' one found. +#' `get_diameter()` returns a path with the actual diameter. +#' If there are many shortest paths of the length of the diameter, then it returns the first one found. #' -#' `farthest_vertices()` returns two vertex IDs, the vertices which are -#' connected by the diameter path. +#' `farthest_vertices()` returns two vertex IDs, the vertices which are connected by the diameter path. #' #' @param graph The graph to analyze. #' @inheritParams rlang::args_dots_empty -#' @param directed Logical, whether directed or undirected paths are to be -#' considered. This is ignored for undirected graphs. -#' @param unconnected Logical, what to do if the graph is unconnected. If -#' FALSE, the function will return a number that is one larger the largest -#' possible diameter, which is always the number of vertices. If TRUE, the -#' diameters of the connected components will be calculated and the largest one -#' will be returned. -#' @param weights Optional positive weight vector for calculating weighted -#' distances. If the graph has a `weight` edge attribute, then this is -#' used by default. -#' @return A numeric constant for `diameter()`, a numeric vector for -#' `get_diameter()`. `farthest_vertices()` returns a list with two -#' entries: +#' @param directed Logical, whether directed or undirected paths are to be considered. +#' This is ignored for undirected graphs. +#' @param unconnected Logical, what to do if the graph is unconnected. +#' If FALSE, the function will return a number that is one larger the largest possible diameter, which is always the number of vertices. +#' If TRUE, the diameters of the connected components will be calculated and the largest one will be returned. +#' @param weights Optional positive weight vector for calculating weighted distances. +#' If the graph has a `weight` edge attribute, then this is used by default. +#' @return A numeric constant for `diameter()`, a numeric vector for `get_diameter()`. +#' `farthest_vertices()` returns a list with two entries: #' \describe{ #' \item{`vertices`}{ #' The two vertices that are the farthest. @@ -1037,31 +1003,27 @@ mean_distance <- function( #' Degree and degree distribution of the vertices #' -#' The degree of a vertex is its most basic structural property, the number of -#' its adjacent edges. +#' The degree of a vertex is its most basic structural property, the number of its adjacent edges. #' #' #' @param graph The graph to analyze. #' @param v The IDs of vertices of which the degree will be calculated. #' The default `NULL` selects all vertices. -#' @param mode Character string, \dQuote{out} for out-degree, \dQuote{in} for -#' in-degree or \dQuote{total} for the sum of the two. For undirected graphs -#' this argument is ignored. \dQuote{all} is a synonym of \dQuote{total}. +#' @param mode Character string, \dQuote{out} for out-degree, \dQuote{in} for in-degree or \dQuote{total} for the sum of the two. +#' For undirected graphs this argument is ignored. +#' \dQuote{all} is a synonym of \dQuote{total}. #' @param loops Logical; whether the loop edges are also counted. -#' @param normalized Logical, whether to normalize the degree. If -#' `TRUE` then the result is divided by \eqn{n-1}, where \eqn{n} is the -#' number of vertices in the graph. +#' @param normalized Logical, whether to normalize the degree. +#' If `TRUE` then the result is divided by \eqn{n-1}, +#' where \eqn{n} is the number of vertices in the graph. #' @inheritParams rlang::args_dots_empty -#' @return For `degree()` a numeric vector of the same length as argument -#' `v`. +#' @return For `degree()` a numeric vector of the same length as argument `v`. #' -#' For `degree_distribution()` a numeric vector of the same length as the -#' maximum degree plus one. The first element is the relative frequency zero -#' degree vertices, the second vertices with degree one, etc. +#' For `degree_distribution()` a numeric vector of the same length as the maximum degree plus one. +#' The first element is the relative frequency zero degree vertices, the second vertices with degree one, etc. #' -#' For `max_degree()`, the largest degree in the graph. When no vertices are -#' selected, or when the input is the null graph, zero is returned as this -#' is the smallest possible degree. +#' For `max_degree()`, the largest degree in the graph. +#' When no vertices are selected, or when the input is the null graph, zero is returned as this is the smallest possible degree. #' #' For `mean_degree()`, the average degree in the graph as a single number. #' For graphs with no vertices, `NaN` is returned. @@ -1220,8 +1182,7 @@ mean_degree <- function( } #' @rdname degree -#' @param cumulative Logical; whether the cumulative degree distribution is to -#' be calculated. +#' @param cumulative Logical; whether the cumulative degree distribution is to be calculated. #' @export #' @importFrom graphics hist degree_distribution <- function(graph, cumulative = FALSE, ...) { @@ -1240,121 +1201,93 @@ degree_distribution <- function(graph, cumulative = FALSE, ...) { #' Shortest (directed or undirected) paths between vertices #' -#' `distances()` calculates the length of all the shortest paths from -#' or to the vertices in the network. `shortest_paths()` calculates one -#' shortest path (the path itself, and not just its length) from or to the -#' given vertex. -#' -#' The shortest path, or geodesic between two pair of vertices is a path with -#' the minimal number of vertices. The functions documented in this manual page -#' all calculate shortest paths between vertex pairs. -#' -#' `distances()` calculates the lengths of pairwise shortest paths from -#' a set of vertices (`from`) to another set of vertices (`to`). It -#' uses different algorithms, depending on the `algorithm` argument and -#' the `weight` edge attribute of the graph. The implemented algorithms -#' are breadth-first search (\sQuote{`unweighted`}), this only works for -#' unweighted graphs; the Dijkstra algorithm (\sQuote{`dijkstra`}), this -#' works for graphs with non-negative edge weights; the Bellman-Ford algorithm -#' (\sQuote{`bellman-ford`}); Johnson's algorithm -#' (\sQuote{`johnson`}); and a faster version of the Floyd-Warshall algorithm -#' with expected quadratic running time (\sQuote{`floyd-warshall`}). The latter -#' three algorithms work with arbitrary -#' edge weights, but (naturally) only for graphs that don't have a negative -#' cycle. Note that a negative-weight edge in an undirected graph implies -#' such a cycle. Johnson's algorithm performs better than the Bellman-Ford -#' one when many source (and target) vertices are given, with all-pairs -#' shortest path length calculations being the typical use case. -#' -#' igraph can choose automatically between algorithms, and chooses the most -#' efficient one that is appropriate for the supplied weights (if any). For -#' automatic algorithm selection, supply \sQuote{`automatic`} as the -#' `algorithm` argument. (This is also the default.) -#' -#' `shortest_paths()` calculates a single shortest path (i.e. the path -#' itself, not just its length) between the source vertex given in `from`, -#' to the target vertices given in `to`. `shortest_paths()` uses -#' breadth-first search for unweighted graphs and Dijkstra's algorithm for -#' weighted graphs. The latter only works if the edge weights are non-negative. -#' -#' `all_shortest_paths()` calculates *all* shortest paths between -#' pairs of vertices, including several shortest paths of the same length. -#' More precisely, it computerd all shortest path starting at `from`, and -#' ending at any vertex given in `to`. It uses a breadth-first search for -#' unweighted graphs and Dijkstra's algorithm for weighted ones. The latter -#' only supports non-negative edge weights. Caution: in multigraphs, the -#' result size is exponentially large in the number of vertex pairs with -#' multiple edges between them. -#' -#' `mean_distance()` calculates the average path length in a graph, by -#' calculating the shortest paths between all pairs of vertices (both ways for -#' directed graphs). It uses a breadth-first search for unweighted graphs and -#' Dijkstra's algorithm for weighted ones. The latter only supports non-negative -#' edge weights. -#' -#' `distance_table()` calculates a histogram, by calculating the shortest -#' path length between each pair of vertices. For directed graphs both -#' directions are considered, so every pair of vertices appears twice in the -#' histogram. +#' `distances()` calculates the length of all the shortest paths from or to the vertices in the network. +#' `shortest_paths()` calculates one shortest path (the path itself, and not just its length) from or to the given vertex. +#' +#' The shortest path, or geodesic between two pair of vertices is a path with the minimal number of vertices. +#' The functions documented in this manual page all calculate shortest paths between vertex pairs. +#' +#' `distances()` calculates the lengths of pairwise shortest paths from a set of vertices (`from`) to another set of vertices (`to`). +#' It uses different algorithms, depending on the `algorithm` argument and the `weight` edge attribute of the graph. +#' The implemented algorithms are breadth-first search (\sQuote{`unweighted`}), this only works for unweighted graphs; +#' the Dijkstra algorithm (\sQuote{`dijkstra`}), this works for graphs with non-negative edge weights; +#' the Bellman-Ford algorithm (\sQuote{`bellman-ford`}); Johnson's algorithm (\sQuote{`johnson`}); +#' and a faster version of the Floyd-Warshall algorithm with expected quadratic running time (\sQuote{`floyd-warshall`}). +#' The latter three algorithms work with arbitrary edge weights, but (naturally) only for graphs that don't have a negative cycle. +#' Note that a negative-weight edge in an undirected graph implies such a cycle. +#' Johnson's algorithm performs better than the Bellman-Ford one when many source (and target) vertices are given, +#' with all-pairs shortest path length calculations being the typical use case. +#' +#' igraph can choose automatically between algorithms, +#' and chooses the most efficient one that is appropriate for the supplied weights (if any). +#' For automatic algorithm selection, supply \sQuote{`automatic`} as the `algorithm` argument. +#' (This is also the default.) +#' +#' `shortest_paths()` calculates a single shortest path (i.e. the path itself, not just its length) between the source vertex given in `from`, +#' to the target vertices given in `to`. +#' `shortest_paths()` uses breadth-first search for unweighted graphs and Dijkstra's algorithm for weighted graphs. +#' The latter only works if the edge weights are non-negative. +#' +#' `all_shortest_paths()` calculates *all* shortest paths between pairs of vertices, including several shortest paths of the same length. +#' More precisely, it computerd all shortest path starting at `from`, and ending at any vertex given in `to`. +#' It uses a breadth-first search for unweighted graphs and Dijkstra's algorithm for weighted ones. +#' The latter only supports non-negative edge weights. +#' Caution: in multigraphs, the result size is exponentially large in the number of vertex pairs with multiple edges between them. +#' +#' `mean_distance()` calculates the average path length in a graph, +#' by calculating the shortest paths between all pairs of vertices (both ways for directed graphs). +#' It uses a breadth-first search for unweighted graphs and Dijkstra's algorithm for weighted ones. +#' The latter only supports non-negative edge weights. +#' +#' `distance_table()` calculates a histogram, by calculating the shortest path length between each pair of vertices. +#' For directed graphs both directions are considered, so every pair of vertices appears twice in the histogram. #' #' @param graph The graph to work on. -#' @param v Numeric vector, the vertices from which the shortest paths will be -#' calculated. The default `NULL` selects all vertices. -#' @param to Numeric vector, the vertices to which the shortest paths will be -#' calculated. The default `NULL` includes all vertices. Note that for -#' `distances()` every vertex must be included here at most once. (This -#' is not required for `shortest_paths()`. +#' @param v Numeric vector, the vertices from which the shortest paths will be calculated. +#' The default `NULL` selects all vertices. +#' @param to Numeric vector, the vertices to which the shortest paths will be calculated. +#' The default `NULL` includes all vertices. +#' Note that for `distances()` every vertex must be included here at most once. +#' (This is not required for `shortest_paths()`. #' @inheritParams rlang::args_dots_empty -#' @param mode Character constant, gives whether the shortest paths to or from -#' the given vertices should be calculated for directed graphs. If `out` -#' then the shortest paths *from* the vertex, if `in` then *to* -#' it will be considered. If `all`, the default, then the graph is treated -#' as undirected, i.e. edge directions are not taken into account. This -#' argument is ignored for undirected graphs. -#' @param weights Possibly a numeric vector giving edge weights. If this is -#' `NULL` and the graph has a `weight` edge attribute, then the -#' attribute is used. If this is `NA` then no weights are used (even if -#' the graph has a `weight` attribute). In a weighted graph, the length -#' of a path is the sum of the weights of its constituent edges. -#' @param algorithm Which algorithm to use for the calculation. By default -#' igraph tries to select the fastest suitable algorithm. If there are no -#' weights, then an unweighted breadth-first search is used, otherwise if all -#' weights are positive, then Dijkstra's algorithm is used. If there are -#' negative weights and we do the calculation for more than 100 sources, then -#' Johnson's algorithm is used. Otherwise the Bellman-Ford algorithm is used. -#' You can override igraph's choice by explicitly giving this parameter. Note -#' that the igraph C core might still override your choice in obvious cases, -#' i.e. if there are no edge weights, then the unweighted algorithm will be -#' used, regardless of this argument. +#' @param mode Character constant, +#' gives whether the shortest paths to or from the given vertices should be calculated for directed graphs. +#' If `out` then the shortest paths *from* the vertex, if `in` then *to* it will be considered. +#' If `all`, the default, then the graph is treated as undirected, i.e. edge directions are not taken into account. +#' This argument is ignored for undirected graphs. +#' @param weights Possibly a numeric vector giving edge weights. +#' If this is `NULL` and the graph has a `weight` edge attribute, then the attribute is used. +#' If this is `NA` then no weights are used (even if the graph has a `weight` attribute). +#' In a weighted graph, the length of a path is the sum of the weights of its constituent edges. +#' @param algorithm Which algorithm to use for the calculation. +#' By default igraph tries to select the fastest suitable algorithm. +#' If there are no weights, then an unweighted breadth-first search is used, otherwise if all weights are positive, +#' then Dijkstra's algorithm is used. +#' If there are negative weights and we do the calculation for more than 100 sources, then Johnson's algorithm is used. +#' Otherwise the Bellman-Ford algorithm is used. +#' You can override igraph's choice by explicitly giving this parameter. +#' Note that the igraph C core might still override your choice in obvious cases, i.e. if there are no edge weights, +#' then the unweighted algorithm will be used, regardless of this argument. #' @param details Whether to provide additional details in the result. -#' Functions accepting this argument (like `mean_distance()`) return -#' additional information like the number of disconnected vertex pairs in -#' the result when this parameter is set to `TRUE`. -#' @param unconnected What to do if the graph is unconnected (not -#' strongly connected if directed paths are considered). If TRUE, only -#' the lengths of the existing paths are considered and averaged; if -#' FALSE, the length of the missing paths are considered as having infinite -#' length, making the mean distance infinite as well. -#' @return For `distances()` a numeric matrix with `length(to)` -#' columns and `length(v)` rows. The shortest path length from a vertex to -#' itself is always zero. For unreachable vertices `Inf` is included. +#' Functions accepting this argument (like `mean_distance()`) return additional information like the number of disconnected vertex pairs in the result +#' when this parameter is set to `TRUE`. +#' @param unconnected What to do if the graph is unconnected (not strongly connected if directed paths are considered). +#' If TRUE, only the lengths of the existing paths are considered and averaged; if FALSE, +#' the length of the missing paths are considered as having infinite length, making the mean distance infinite as well. +#' @return For `distances()` a numeric matrix with `length(to)` columns and `length(v)` rows. +#' The shortest path length from a vertex to itself is always zero. +#' For unreachable vertices `Inf` is included. #' #' For `shortest_paths()` a named list with four entries is returned: #' \item{vpath}{This itself is a list, of length `length(to)`; list -#' element `i` contains the vertex IDs on the path from vertex `from` -#' to vertex `to[i]` (or the other way for directed graphs depending on -#' the `mode` argument). The vector also contains `from` and `i` -#' as the first and last elements. If `from` is the same as `i` then -#' it is only included once. If there is no path between two vertices then a -#' numeric vector of length zero is returned as the list element. If this -#' output is not requested in the `output` argument, then it will be -#' `NULL`.} \item{epath}{This is a list similar to `vpath`, but the -#' vectors of the list contain the edge IDs along the shortest paths, instead -#' of the vertex IDs. This entry is set to `NULL` if it is not requested -#' in the `output` argument.} \item{predecessors}{Numeric vector, the -#' predecessor of each vertex in the `to` argument, or `NULL` if it -#' was not requested.} \item{inbound_edges}{Numeric vector, the inbound edge -#' for each vertex, or `NULL`, if it was not requested.} +#' element `i` contains the vertex IDs on the path from vertex `from` to vertex `to[i]` (or the other way for directed graphs depending on the `mode` argument). +#' The vector also contains `from` and `i` as the first and last elements. +#' If `from` is the same as `i` then it is only included once. +#' If there is no path between two vertices then a numeric vector of length zero is returned as the list element. +#' If this output is not requested in the `output` argument, then it will be `NULL`.} +#' \item{epath}{This is a list similar to `vpath`, but the vectors of the list contain the edge IDs along the shortest paths, instead of the vertex IDs. This entry is set to `NULL` if it is not requested in the `output` argument.} +#' \item{predecessors}{Numeric vector, the predecessor of each vertex in the `to` argument, or `NULL` if it was not requested.} +#' \item{inbound_edges}{Numeric vector, the inbound edge for each vertex, or `NULL`, if it was not requested.} #' #' For `all_shortest_paths()` a list is returned: #' \describe{ @@ -1563,27 +1496,21 @@ distances <- function( } #' @rdname distances -#' @param from Numeric constant, the vertex from or to the shortest paths will -#' be calculated. Note that right now this is not a vector of vertex IDs, but -#' only a single vertex. +#' @param from Numeric constant, the vertex from or to the shortest paths will be calculated. +#' Note that right now this is not a vector of vertex IDs, but only a single vertex. #' @param output Character scalar, defines how to report the shortest paths. -#' \dQuote{vpath} means that the vertices along the paths are reported, this -#' form was used prior to igraph version 0.6. \dQuote{epath} means that the -#' edges along the paths are reported. \dQuote{both} means that both forms are -#' returned, in a named list with components \dQuote{vpath} and \dQuote{epath}. -#' @param predecessors Logical, whether to return the predecessor vertex -#' for each vertex. The predecessor of vertex `i` in the tree is the -#' vertex from which vertex `i` was reached. The predecessor of the start -#' vertex (in the `from` argument) is itself by definition. If the -#' predecessor is zero, it means that the given vertex was not reached from the -#' source during the search. Note that the search terminates if all the -#' vertices in `to` are reached. -#' @param inbound.edges Logical, whether to return the inbound edge for -#' each vertex. The inbound edge of vertex `i` in the tree is the edge via -#' which vertex `i` was reached. The start vertex and vertices that were -#' not reached during the search will have zero in the corresponding entry of -#' the vector. Note that the search terminates if all the vertices in `to` -#' are reached. +#' \dQuote{vpath} means that the vertices along the paths are reported, +#' this form was used prior to igraph version 0.6. \dQuote{epath} means that the edges along the paths are reported. +#' \dQuote{both} means that both forms are returned, in a named list with components \dQuote{vpath} and \dQuote{epath}. +#' @param predecessors Logical, whether to return the predecessor vertex for each vertex. +#' The predecessor of vertex `i` in the tree is the vertex from which vertex `i` was reached. +#' The predecessor of the start vertex (in the `from` argument) is itself by definition. +#' If the predecessor is zero, it means that the given vertex was not reached from the source during the search. +#' Note that the search terminates if all the vertices in `to` are reached. +#' @param inbound.edges Logical, whether to return the inbound edge for each vertex. +#' The inbound edge of vertex `i` in the tree is the edge via which vertex `i` was reached. +#' The start vertex and vertices that were not reached during the search will have zero in the corresponding entry of the vector. +#' Note that the search terminates if all the vertices in `to` are reached. #' @inheritParams rlang::args_dots_empty #' @export shortest_paths <- function( @@ -1837,15 +1764,14 @@ all_shortest_paths <- function( #' Find the \eqn{k} shortest paths between two vertices #' -#' Finds the \eqn{k} shortest paths between the given source and target -#' vertex in order of increasing length. Currently this function uses -#' Yen's algorithm. +#' Finds the \eqn{k} shortest paths between the given source and target vertex in order of increasing length. +#' Currently this function uses Yen's algorithm. #' #' @param graph The input graph. #' @param from The source vertex of the shortest paths. #' @param to The target vertex of the shortest paths. -#' @param k The number of paths to find. They will be returned in order of -#' increasing length. +#' @param k The number of paths to find. +#' They will be returned in order of increasing length. #' @inheritParams rlang::args_dots_empty #' @inheritParams shortest_paths #' @return A named list with two components is returned: @@ -1887,21 +1813,20 @@ k_shortest_paths <- function( #' In- or out- component of a vertex #' -#' Finds all vertices reachable from a given vertex, or the opposite: all -#' vertices from which a given vertex is reachable via a directed path. +#' Finds all vertices reachable from a given vertex, or the opposite: +#' all vertices from which a given vertex is reachable via a directed path. #' #' A breadth-first search is conducted starting from vertex `v`. #' #' @param graph The graph to analyze. #' @param v The vertex to start the search from. #' @inheritParams rlang::args_dots_empty -#' @param mode Character string, either \dQuote{in}, \dQuote{out} or -#' \dQuote{all}. If \dQuote{in} all vertices from which `v` is reachable -#' are listed. If \dQuote{out} all vertices reachable from `v` are -#' returned. If \dQuote{all} returns the union of these. It is ignored for -#' undirected graphs. -#' @return Numeric vector, the IDs of the vertices in the same component as -#' `v`. +#' @param mode Character string, either \dQuote{in}, \dQuote{out} or \dQuote{all}. +#' If \dQuote{in} all vertices from which `v` is reachable are listed. +#' If \dQuote{out} all vertices reachable from `v` are returned. +#' If \dQuote{all} returns the union of these. +#' It is ignored for undirected graphs. +#' @return Numeric vector, the IDs of the vertices in the same component as `v`. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @seealso [components()] #' @family structural.properties @@ -1976,21 +1901,18 @@ subcomponent <- function( #' Subgraph of a graph #' -#' `subgraph()` creates a subgraph of a graph, containing only the specified -#' vertices and all the edges among them. +#' `subgraph()` creates a subgraph of a graph, containing only the specified vertices and all the edges among them. #' -#' `induced_subgraph()` calculates the induced subgraph of a set of vertices -#' in a graph. This means that exactly the specified vertices and all the edges -#' between them will be kept in the result graph. +#' `induced_subgraph()` calculates the induced subgraph of a set of vertices in a graph. +#' This means that exactly the specified vertices and all the edges between them will be kept in the result graph. #' -#' `subgraph_from_edges()` calculates the subgraph of a graph. For this function -#' one can specify the vertices and edges to keep. This function will be -#' renamed to `subgraph()` in the next major version of igraph. +#' `subgraph_from_edges()` calculates the subgraph of a graph. +#' For this function one can specify the vertices and edges to keep. +#' This function will be renamed to `subgraph()` in the next major version of igraph. #' -#' The `subgraph()` function currently does the same as `induced_subgraph()` -#' (assuming \sQuote{`auto`} as the `impl` argument), but this behaviour -#' is deprecated. In the next major version, `subgraph()` will overtake the -#' functionality of `subgraph_from_edges()`. +#' The `subgraph()` function currently does the same as `induced_subgraph()` (assuming \sQuote{`auto`} as the `impl` argument), +#' but this behaviour is deprecated. +#' In the next major version, `subgraph()` will overtake the functionality of `subgraph_from_edges()`. #' #' @aliases subgraph_from_edges #' @param graph The original graph. @@ -2010,17 +1932,13 @@ subgraph <- function(graph, vids) { } #' @rdname subgraph -#' @param vids Numeric vector, the vertices of the original graph which will -#' form the subgraph. +#' @param vids Numeric vector, the vertices of the original graph which will form the subgraph. #' @inheritParams rlang::args_dots_empty -#' @param impl Character scalar, to choose between two implementation of the -#' subgraph calculation. \sQuote{`copy_and_delete`} copies the graph -#' first, and then deletes the vertices and edges that are not included in the -#' result graph. \sQuote{`create_from_scratch`} searches for all vertices -#' and edges that must be kept and then uses them to create the graph from -#' scratch. \sQuote{`auto`} chooses between the two implementations -#' automatically, using heuristics based on the size of the original and the -#' result graph. +#' @param impl Character scalar, to choose between two implementation of the subgraph calculation. +#' \sQuote{`copy_and_delete`} copies the graph first, and then deletes the vertices and edges that are not included in the result graph. +#' \sQuote{`create_from_scratch`} searches for all vertices and edges that must be kept and then uses them to create the graph from scratch. +#' \sQuote{`auto`} chooses between the two implementations automatically, +#' using heuristics based on the size of the original and the result graph. #' @export induced_subgraph <- function( graph, @@ -2081,8 +1999,7 @@ induced_subgraph <- function( #' @rdname subgraph #' @param eids The edge IDs of the edges that will be kept in the result graph. #' @inheritParams rlang::args_dots_empty -#' @param delete.vertices Logical, whether to remove vertices that do -#' not have any adjacent edges in `eids`. +#' @param delete.vertices Logical, whether to remove vertices that do not have any adjacent edges in `eids`. #' @export subgraph_from_edges <- function( graph, @@ -2146,8 +2063,7 @@ subgraph_from_edges <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `subgraph.edges()` was renamed to [subgraph_from_edges()] to create a more -#' consistent API. +#' `subgraph.edges()` was renamed to [subgraph_from_edges()] to create a more consistent API. #' @inheritParams subgraph_from_edges #' @keywords internal #' @export @@ -2168,33 +2084,28 @@ subgraph.edges <- function(graph, eids, delete.vertices = TRUE) { #' Transitivity of a graph #' -#' Transitivity measures the probability that the adjacent vertices of a vertex -#' are connected. This is sometimes also called the clustering coefficient. +#' Transitivity measures the probability that the adjacent vertices of a vertex are connected. +#' This is sometimes also called the clustering coefficient. #' -#' Note that there are essentially two classes of transitivity measures, one is -#' a vertex-level, the other a graph level property. +#' Note that there are essentially two classes of transitivity measures, one is a vertex-level, the other a graph level property. #' -#' There are several generalizations of transitivity to weighted graphs, here -#' we use the definition by A. Barrat, this is a local vertex-level quantity, -#' its formula is +#' There are several generalizations of transitivity to weighted graphs, here we use the definition by A. Barrat, +#' this is a local vertex-level quantity, its formula is #' #' \deqn{C_i^w=\frac{1}{s_i(k_i-1)}\sum_{j,h}\frac{w_{ij}+w_{ih}}{2}a_{ij}a_{ih}a_{jh}}{ #' weighted C_i = 1/s_i 1/(k_i-1) sum( (w_ij+w_ih)/2 a_ij a_ih a_jh, j, h)} #' -#' \eqn{s_i}{s_i} is the strength of vertex \eqn{i}{i}, see -#' [strength()], \eqn{a_{ij}}{a_ij} are elements of the -#' adjacency matrix, \eqn{k_i}{k_i} is the vertex degree, \eqn{w_{ij}}{w_ij} -#' are the weights. +#' \eqn{s_i}{s_i} is the strength of vertex \eqn{i}{i}, see [strength()], \eqn{a_{ij}}{a_ij} are elements of the adjacency matrix, +#' \eqn{k_i}{k_i} is the vertex degree, \eqn{w_{ij}}{w_ij} are the weights. #' -#' This formula gives back the normal not-weighted local transitivity if all -#' the edge weights are the same. +#' This formula gives back the normal not-weighted local transitivity if all the edge weights are the same. #' -#' The `barrat` type of transitivity does not work for graphs with -#' multiple and/or loop edges. If you want to calculate it for a directed -#' graph, call [as_undirected()] with the `collapse` mode first. +#' The `barrat` type of transitivity does not work for graphs with multiple and/or loop edges. +#' If you want to calculate it for a directed graph, call [as_undirected()] with the `collapse` mode first. #' #' @param graph The graph to analyze. -#' @param type The type of the transitivity to calculate. Possible values: +#' @param type The type of the transitivity to calculate. +#' Possible values: #' \describe{ #' \item{"global"}{ #' The global transitivity of an undirected graph. @@ -2226,28 +2137,22 @@ subgraph.edges <- function(graph, eids, delete.vertices = TRUE) { #' } #' @inheritParams rlang::args_dots_empty #' @param vids The vertex IDs for the local transitivity will be calculated. -#' This will be ignored for global transitivity types. The default value is -#' `NULL`, in this case all vertices are considered. It is slightly faster -#' to supply `NULL` here than `V(graph)`. -#' @param weights Optional weights for weighted transitivity. It is ignored for -#' other transitivity measures. If it is `NULL` (the default) and the -#' graph has a `weight` edge attribute, then it is used automatically. -#' @param isolates Character scalar, for local versions of transitivity, it -#' defines how to treat vertices with degree zero and one. -#' If it is \sQuote{`NaN`} then their local transitivity is -#' reported as `NaN` and they are not included in the averaging, for the -#' transitivity types that calculate an average. If there are no vertices with -#' degree two or higher, then the averaging will still result `NaN`. If it -#' is \sQuote{`zero`}, then we report 0 transitivity for them, and they -#' are included in the averaging, if an average is calculated. -#' For the global transitivity, it controls how to handle graphs with -#' no connected triplets: `NaN` or zero will be returned according to -#' the respective setting. -#' @return For \sQuote{`global`} a single number, or `NaN` if there -#' are no connected triples in the graph. -#' -#' For \sQuote{`local`} a vector of transitivity scores, one for each -#' vertex in \sQuote{`vids`}. +#' This will be ignored for global transitivity types. +#' The default value is `NULL`, in this case all vertices are considered. +#' It is slightly faster to supply `NULL` here than `V(graph)`. +#' @param weights Optional weights for weighted transitivity. +#' It is ignored for other transitivity measures. +#' If it is `NULL` (the default) and the graph has a `weight` edge attribute, then it is used automatically. +#' @param isolates Character scalar, for local versions of transitivity, it defines how to treat vertices with degree zero and one. +#' If it is \sQuote{`NaN`} then their local transitivity is reported as `NaN` and they are not included in the averaging, +#' for the transitivity types that calculate an average. +#' If there are no vertices with degree two or higher, then the averaging will still result `NaN`. +#' If it is \sQuote{`zero`}, then we report 0 transitivity for them, and they are included in the averaging, if an average is calculated. +#' For the global transitivity, it controls how to handle graphs with no connected triplets: +#' `NaN` or zero will be returned according to the respective setting. +#' @return For \sQuote{`global`} a single number, or `NaN` if there are no connected triples in the graph. +#' +#' For \sQuote{`local`} a vector of transitivity scores, one for each vertex in \sQuote{`vids`}. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @references Wasserman, S., and Faust, K. (1994). *Social Network #' Analysis: Methods and Applications.* Cambridge: Cambridge University Press. @@ -2444,33 +2349,30 @@ transitivity <- function( #' Burt's constraint #' -#' Given a graph, `constraint()` calculates Burt's constraint for each -#' vertex. +#' Given a graph, `constraint()` calculates Burt's constraint for each vertex. #' -#' Burt's constraint is higher if ego has less, or mutually -#' stronger related (i.e. more redundant) contacts. Burt's measure of -#' constraint, \eqn{C_i}{C[i]}, of vertex \eqn{i}'s ego network -#' \eqn{V_i}{V[i]}, is defined for directed and valued graphs, +#' Burt's constraint is higher if ego has less, or mutually stronger related (i.e. more redundant) contacts. +#' Burt's measure of constraint, \eqn{C_i}{C[i]}, of vertex \eqn{i}'s ego network \eqn{V_i}{V[i]}, +#' is defined for directed and valued graphs, #' \deqn{C_i=\sum_{j \in V_i \setminus \{i\}} (p_{ij}+\sum_{q \in V_i #' \setminus \{i,j\}} p_{iq} p_{qj})^2}{ #' C[i] = sum( [sum( p[i,j] + p[i,q] p[q,j], q in V[i], q != i,j )]^2, j in #' V[i], j != i). #' } -#' for a graph of order (i.e. number of vertices) \eqn{N}, where -#' proportional tie strengths are defined as +#' for a graph of order (i.e. number of vertices) \eqn{N}, where proportional tie strengths are defined as #' \deqn{p_{ij} = \frac{a_{ij}+a_{ji}}{\sum_{k \in V_i \setminus \{i\}}(a_{ik}+a_{ki})},}{ #' p[i,j]=(a[i,j]+a[j,i]) / sum(a[i,k]+a[k,i], k in V[i], k != i), #' } -#' \eqn{a_{ij}}{a[i,j]} are elements of \eqn{A} and the latter being the -#' graph adjacency matrix. For isolated vertices, constraint is undefined. +#' \eqn{a_{ij}}{a[i,j]} are elements of \eqn{A} and the latter being the graph adjacency matrix. +#' For isolated vertices, constraint is undefined. #' #' @param graph A graph object, the input graph. #' @param nodes The vertices for which the constraint will be calculated. #' The default `NULL` selects all vertices. #' @inheritParams rlang::args_dots_empty -#' @param weights The weights of the edges. If this is `NULL` and there is -#' a `weight` edge attribute this is used. If there is no such edge -#' attribute all edges will have the same weight. +#' @param weights The weights of the edges. +#' If this is `NULL` and there is a `weight` edge attribute this is used. +#' If there is no such edge attribute all edges will have the same weight. #' @return A numeric vector of constraint scores #' @author Jeroen Bruggeman #' () @@ -2554,20 +2456,18 @@ constraint <- function( #' #' Calculates the reciprocity of a directed graph. #' -#' The measure of reciprocity defines the proportion of mutual connections, in -#' a directed graph. It is most commonly defined as the probability that the -#' opposite counterpart of a directed edge is also included in the graph. Or in -#' adjacency matrix notation: +#' The measure of reciprocity defines the proportion of mutual connections, in a directed graph. +#' It is most commonly defined as the probability that the opposite counterpart of a directed edge is also included in the graph. +#' Or in adjacency matrix notation: #' \eqn{1 - \left(\sum_{i,j} |A_{ij} - A_{ji}|\right) / \left(2\sum_{i,j} A_{ij}\right)}{1 - (sum_ij |A_ij - A_ji|) / (2 sum_ij A_ij)}. #' This measure is calculated if the `mode` argument is `default`. #' -#' Prior to igraph version 0.6, another measure was implemented, defined as the -#' probability of mutual connection between a vertex pair, if we know that -#' there is a (possibly non-mutual) connection between them. In other words, -#' (unordered) vertex pairs are classified into three groups: (1) -#' not-connected, (2) non-reciprocally connected, (3) reciprocally connected. -#' The result is the size of group (3), divided by the sum of group sizes -#' (2)+(3). This measure is calculated if `mode` is `ratio`. +#' Prior to igraph version 0.6, another measure was implemented, defined as the probability of mutual connection between a vertex pair, +#' if we know that there is a (possibly non-mutual) connection between them. +#' In other words, (unordered) vertex pairs are classified into three groups: (1) not-connected, (2) non-reciprocally connected, +#' (3) reciprocally connected. +#' The result is the size of group (3), divided by the sum of group sizes (2)+(3). +#' This measure is calculated if `mode` is `ratio`. #' #' @param graph The graph object. #' @inheritParams rlang::args_dots_empty @@ -2637,25 +2537,21 @@ reciprocity <- function( #' Graph density #' -#' The density of a graph is the ratio of the actual number of edges and the -#' largest possible number of edges in the graph, assuming that no multi-edges -#' are present. +#' The density of a graph is the ratio of the actual number of edges and the largest possible number of edges in the graph, +#' assuming that no multi-edges are present. #' -#' The concept of density is ill-defined for multigraphs. Note that this function -#' does not check whether the graph has multi-edges and will return meaningless -#' results for such graphs. +#' The concept of density is ill-defined for multigraphs. +#' Note that this function does not check whether the graph has multi-edges and will return meaningless results for such graphs. #' #' @param graph The input graph. #' @inheritParams rlang::args_dots_empty #' @param loops Logical, whether loop edges may exist in the graph. -#' This affects the calculation of the largest possible number of edges in the -#' graph. If this parameter is set to FALSE yet the graph contains self-loops, -#' the result will not be meaningful. -#' @return A real constant. This function returns `NaN` (=0.0/0.0) for an -#' empty graph with zero vertices. +#' This affects the calculation of the largest possible number of edges in the graph. +#' If this parameter is set to FALSE yet the graph contains self-loops, the result will not be meaningful. +#' @return A real constant. +#' This function returns `NaN` (=0.0/0.0) for an empty graph with zero vertices. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso [vcount()], [ecount()], [simplify()] -#' to get rid of the multiple and/or loop edges. +#' @seealso [vcount()], [ecount()], [simplify()] to get rid of the multiple and/or loop edges. #' @references Wasserman, S., and Faust, K. (1994). Social Network Analysis: #' Methods and Applications. Cambridge: Cambridge University Press. #' @family structural.properties @@ -2794,46 +2690,39 @@ neighborhood_size <- ego_size #' Neighborhood of graph vertices #' -#' These functions find the vertices not farther than a given limit from -#' another fixed vertex, these are called the neighborhood of the vertex. -#' Note that `ego()` and `neighborhood()`, -#' `ego_size()` and `neighborhood_size()`, -#' `make_ego_graph()` and `make_neighborhood()_graph()`, +#' These functions find the vertices not farther than a given limit from another fixed vertex, +#' these are called the neighborhood of the vertex. +#' Note that `ego()` and `neighborhood()`, `ego_size()` and `neighborhood_size()`, `make_ego_graph()` and `make_neighborhood()_graph()`, #' are synonyms (aliases). #' -#' The neighborhood of a given order `r` of a vertex `v` includes all -#' vertices which are closer to `v` than the order. I.e. order 0 is always -#' `v` itself, order 1 is `v` plus its immediate neighbors, order 2 -#' is order 1 plus the immediate neighbors of the vertices in order 1, etc. +#' The neighborhood of a given order `r` of a vertex `v` includes all vertices which are closer to `v` than the order. +#' I.e. order 0 is always `v` itself, order 1 is `v` plus its immediate neighbors, +#' order 2 is order 1 plus the immediate neighbors of the vertices in order 1, etc. #' #' `ego_size()`/`neighborhood_size()` (synonyms) returns the size of the neighborhoods of the given order, #' for each given vertex. #' -#' `ego()`/`neighborhood()` (synonyms) returns the vertices belonging to the neighborhoods of the given -#' order, for each given vertex. +#' `ego()`/`neighborhood()` (synonyms) returns the vertices belonging to the neighborhoods of the given order, for each given vertex. #' -#' `make_ego_graph()`/`make_neighborhood()_graph()` (synonyms) is creates (sub)graphs from all neighborhoods of -#' the given vertices with the given order parameter. This function preserves -#' the vertex, edge and graph attributes. +#' `make_ego_graph()`/`make_neighborhood()_graph()` (synonyms) is creates (sub)graphs from all neighborhoods of the given vertices with the given order parameter. +#' This function preserves the vertex, edge and graph attributes. #' -#' `connect()` creates a new graph by connecting each vertex to -#' all other vertices in its neighborhood. +#' `connect()` creates a new graph by connecting each vertex to all other vertices in its neighborhood. #' #' @aliases neighborhood ego_graph #' @aliases connect ego_size ego #' @param graph The input graph. -#' @param order Integer giving the order of the neighborhood. Negative values -#' indicate an infinite order. +#' @param order Integer giving the order of the neighborhood. +#' Negative values indicate an infinite order. #' @param nodes The vertices for which the calculation is performed. #' The default `NULL` selects all vertices. #' @inheritParams rlang::args_dots_empty -#' @param mode Character constant, it specifies how to use the direction of -#' the edges if a directed graph is analyzed. For \sQuote{out} only the -#' outgoing edges are followed, so all vertices reachable from the source -#' vertex in at most `order` steps are counted. For \sQuote{"in"} all -#' vertices from which the source vertex is reachable in at most `order` -#' steps are counted. \sQuote{"all"} ignores the direction of the edges. This -#' argument is ignored for undirected graphs. +#' @param mode Character constant, it specifies how to use the direction of the edges if a directed graph is analyzed. +#' For \sQuote{out} only the outgoing edges are followed, +#' so all vertices reachable from the source vertex in at most `order` steps are counted. +#' For \sQuote{"in"} all vertices from which the source vertex is reachable in at most `order` steps are counted. +#' \sQuote{"all"} ignores the direction of the edges. +#' This argument is ignored for undirected graphs. #' @param mindist The minimum distance to include the vertex in the result. #' @return #' \itemize{ @@ -3033,24 +2922,21 @@ make_neighborhood_graph <- make_ego_graph #' K-core decomposition of graphs #' -#' The k-core of graph is a maximal subgraph in which each vertex has at least -#' degree k. The coreness of a vertex is k if it belongs to the k-core but not -#' to the (k+1)-core. +#' The k-core of graph is a maximal subgraph in which each vertex has at least degree k. +#' The coreness of a vertex is k if it belongs to the k-core but not to the (k+1)-core. #' -#' The k-core of a graph is the maximal subgraph in which every vertex has at -#' least degree k. The cores of a graph form layers: the (k+1)-core is always a -#' subgraph of the k-core. +#' The k-core of a graph is the maximal subgraph in which every vertex has at least degree k. +#' The cores of a graph form layers: the (k+1)-core is always a subgraph of the k-core. #' #' This function calculates the coreness for each vertex. #' #' @param graph The input graph, it can be directed or undirected #' @inheritParams rlang::args_dots_empty -#' @param mode The type of the core in directed graphs. Character constant, -#' possible values: `in`: in-cores are computed, `out`: out-cores are -#' computed, `all`: the corresponding undirected graph is considered. This -#' argument is ignored for undirected graphs. -#' @return Numeric vector of integer numbers giving the coreness of each -#' vertex. +#' @param mode The type of the core in directed graphs. +#' Character constant, possible values: `in`: in-cores are computed, `out`: out-cores are computed, `all`: +#' the corresponding undirected graph is considered. +#' This argument is ignored for undirected graphs. +#' @return Numeric vector of integer numbers giving the coreness of each vertex. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @seealso [degree()] #' @references Vladimir Batagelj, Matjaz Zaversnik: An O(m) Algorithm for Cores @@ -3122,24 +3008,21 @@ coreness <- function( #' Topological sorting of vertices in a graph #' -#' A topological sorting of a directed acyclic graph is a linear ordering of -#' its nodes where each node comes before all nodes to which it has edges. +#' A topological sorting of a directed acyclic graph is a linear ordering of its nodes +#' where each node comes before all nodes to which it has edges. #' -#' Every DAG has at least one topological sort, and may have many. This -#' function returns a possible topological sort among them. If the graph is not -#' acyclic (it has at least one cycle), a partial topological sort is returned -#' and a warning is issued. +#' Every DAG has at least one topological sort, and may have many. +#' This function returns a possible topological sort among them. +#' If the graph is not acyclic (it has at least one cycle), a partial topological sort is returned and a warning is issued. #' #' @param graph The input graph, should be directed #' @inheritParams rlang::args_dots_empty -#' @param mode Specifies how to use the direction of the edges. For -#' \dQuote{`out`}, the sorting order ensures that each node comes before -#' all nodes to which it has edges, so nodes with no incoming edges go first. -#' For \dQuote{`in`}, it is quite the opposite: each node comes before all -#' nodes from which it receives edges. Nodes with no outgoing edges go first. -#' @return A vertex sequence (by default, but see the `return.vs.es` -#' option of [igraph_options()]) containing vertices in -#' topologically sorted order. +#' @param mode Specifies how to use the direction of the edges. +#' For \dQuote{`out`}, +#' the sorting order ensures that each node comes before all nodes to which it has edges, so nodes with no incoming edges go first. +#' For \dQuote{`in`}, it is quite the opposite: each node comes before all nodes from which it receives edges. +#' Nodes with no outgoing edges go first. +#' @return A vertex sequence (by default, but see the `return.vs.es` option of [igraph_options()]) containing vertices in topologically sorted order. #' @author Tamas Nepusz \email{ntamas@@gmail.com} and Gabor Csardi #' \email{csardi.gabor@@gmail.com} for the R interface #' @keywords graphs @@ -3200,31 +3083,24 @@ topo_sort <- function( #' Finding a feedback arc set in a graph #' -#' A feedback arc set of a graph is a subset of edges whose removal breaks all -#' cycles in the graph. +#' A feedback arc set of a graph is a subset of edges whose removal breaks all cycles in the graph. #' -#' Feedback arc sets are typically used in directed graphs. The removal of a -#' feedback arc set of a directed graph ensures that the remaining graph is a -#' directed acyclic graph (DAG). For undirected graphs, the removal of a feedback -#' arc set ensures that the remaining graph is a forest (i.e. every connected -#' component is a tree). +#' Feedback arc sets are typically used in directed graphs. +#' The removal of a feedback arc set of a directed graph ensures that the remaining graph is a directed acyclic graph (DAG). +#' For undirected graphs, +#' the removal of a feedback arc set ensures that the remaining graph is a forest (i.e. every connected component is a tree). #' #' @param graph The input graph #' @inheritParams rlang::args_dots_empty -#' @param weights Potential edge weights. If the graph has an edge -#' attribute called \sQuote{`weight`}, and this argument is -#' `NULL`, then the edge attribute is used automatically. The goal of -#' the feedback arc set problem is to find a feedback arc set with the smallest -#' total weight. -#' @param algo Specifies the algorithm to use. \dQuote{`exact_ip`} solves -#' the feedback arc set problem with an exact integer programming algorithm that -#' guarantees that the total weight of the removed edges is as small as possible. -#' \dQuote{`approx_eades`} uses a fast (linear-time) approximation -#' algorithm from Eades, Lin and Smyth. \dQuote{`exact`} is an alias to -#' \dQuote{`exact_ip`} while \dQuote{`approx`} is an alias to -#' \dQuote{`approx_eades`}. -#' @return An edge sequence (by default, but see the `return.vs.es` option -#' of [igraph_options()]) containing the feedback arc set. +#' @param weights Potential edge weights. +#' If the graph has an edge attribute called \sQuote{`weight`}, and this argument is `NULL`, +#' then the edge attribute is used automatically. +#' The goal of the feedback arc set problem is to find a feedback arc set with the smallest total weight. +#' @param algo Specifies the algorithm to use. +#' \dQuote{`exact_ip`} solves the feedback arc set problem with an exact integer programming algorithm that guarantees that the total weight of the removed edges is as small as possible. +#' \dQuote{`approx_eades`} uses a fast (linear-time) approximation algorithm from Eades, Lin and Smyth. +#' \dQuote{`exact`} is an alias to \dQuote{`exact_ip`} while \dQuote{`approx`} is an alias to \dQuote{`approx_eades`}. +#' @return An edge sequence (by default, but see the `return.vs.es` option of [igraph_options()]) containing the feedback arc set. #' @references Peter Eades, Xuemin Lin and W.F.Smyth: A fast and effective #' heuristic for the feedback arc set problem. *Information Processing Letters* #' 47:6, pp. 319-323, 1993 @@ -3292,22 +3168,19 @@ feedback_arc_set <- function( #' @description #' `r lifecycle::badge("experimental")` #' -#' A feedback vertex set of a graph is a subset of vertices whose removal breaks -#' all cycles in the graph. Finding a _minimum_ feedback vertex set is an -#' NP-complete problem, both on directed and undirected graphs. +#' A feedback vertex set of a graph is a subset of vertices whose removal breaks all cycles in the graph. +#' Finding a _minimum_ feedback vertex set is an NP-complete problem, both on directed and undirected graphs. #' #' @param graph The input graph #' @inheritParams rlang::args_dots_empty -#' @param weights Potential vertex weights. If the graph has a vertex -#' attribute called \sQuote{`weight`}, and this argument is -#' `NULL`, then the vertex attribute is used automatically. The goal of -#' the feedback vertex set problem is to find a feedback vertex set with -#' the smallest total weight. -#' @param algo Specifies the algorithm to use. Currently, \dQuote{`exact_ip`}, -#' which solves the feedback vertex set problem with an exact integer -#' programming approach, is the only option. -#' @return A vertex sequence (by default, but see the `return.vs.es` option -#' of [igraph_options()]) containing the feedback vertex set. +#' @param weights Potential vertex weights. +#' If the graph has a vertex attribute called \sQuote{`weight`}, and this argument is `NULL`, +#' then the vertex attribute is used automatically. +#' The goal of the feedback vertex set problem is to find a feedback vertex set with the smallest total weight. +#' @param algo Specifies the algorithm to use. +#' Currently, \dQuote{`exact_ip`}, which solves the feedback vertex set problem with an exact integer programming approach, +#' is the only option. +#' @return A vertex sequence (by default, but see the `return.vs.es` option of [igraph_options()]) containing the feedback vertex set. #' @keywords graphs #' @family structural.properties #' @family cycles @@ -3370,17 +3243,16 @@ feedback_vertex_set <- function( #' #' The girth of a graph is the length of the shortest circle in it. #' -#' The current implementation works for undirected graphs only, directed graphs -#' are treated as undirected graphs. Loop edges and multiple edges are ignored. +#' The current implementation works for undirected graphs only, directed graphs are treated as undirected graphs. +#' Loop edges and multiple edges are ignored. #' If the graph is a forest (i.e. acyclic), then `Inf` is returned. #' -#' This implementation is based on Alon Itai and Michael Rodeh: Finding a -#' minimum circuit in a graph *Proceedings of the ninth annual ACM -#' symposium on Theory of computing*, 1-10, 1977. The first implementation of -#' this function was done by Keith Briggs, thanks Keith. +#' This implementation is based on Alon Itai and Michael Rodeh: +#' Finding a minimum circuit in a graph *Proceedings of the ninth annual ACM symposium on Theory of computing*, +#' 1-10, 1977. The first implementation of this function was done by Keith Briggs, thanks Keith. #' -#' @param graph The input graph. It may be directed, but the algorithm searches -#' for undirected circles anyway. +#' @param graph The input graph. +#' It may be directed, but the algorithm searches for undirected circles anyway. #' @inheritParams rlang::args_dots_empty #' @param circle Logical, whether to return the shortest circle itself. #' @return A named list with two components: @@ -3469,9 +3341,9 @@ girth <- function( #' Find the multiple or loop edges in a graph #' -#' A loop edge is an edge from a vertex to itself. An edge is a multiple edge -#' if it has exactly the same head and tail vertices as another edge. A graph -#' without multiple and loop edges is called a simple graph. +#' A loop edge is an edge from a vertex to itself. +#' An edge is a multiple edge if it has exactly the same head and tail vertices as another edge. +#' A graph without multiple and loop edges is called a simple graph. #' #' `any_loop()` decides whether the graph has any loop edges. #' @@ -3481,23 +3353,20 @@ girth <- function( #' #' `any_multiple()` decides whether the graph has any multiple edges. #' -#' `which_multiple()` decides whether the edges of the graph are multiple -#' edges. +#' `which_multiple()` decides whether the edges of the graph are multiple edges. #' #' `count_multiple()` counts the multiplicity of each edge of a graph. #' -#' Note that the semantics for `which_multiple()` and `count_multiple()` is -#' different. `which_multiple()` gives `TRUE` for all occurrences of a -#' multiple edge except for one. I.e. if there are three `i-j` edges in the -#' graph then `which_multiple()` returns `TRUE` for only two of them while -#' `count_multiple()` returns \sQuote{3} for all three. +#' Note that the semantics for `which_multiple()` and `count_multiple()` is different. +#' `which_multiple()` gives `TRUE` for all occurrences of a multiple edge except for one. +#' I.e. if there are three `i-j` edges in the graph then `which_multiple()` returns `TRUE` for only two of them +#' while `count_multiple()` returns \sQuote{3} for all three. #' -#' See the examples for getting rid of multiple edges while keeping their -#' original multiplicity as an edge attribute. +#' See the examples for getting rid of multiple edges while keeping their original multiplicity as an edge attribute. #' #' @param graph The input graph. -#' @param eids The edges to which the query is restricted. The default -#' `NULL` selects all edges. +#' @param eids The edges to which the query is restricted. +#' The default `NULL` selects all edges. #' @return `any_loop()` and `any_multiple()` return a Logical. #' `which_loop()` and `which_multiple()` return a logical vector. #' `count_loops()` returns a numeric scalar with the total number of loop edges. @@ -3593,8 +3462,8 @@ count_loops <- function(graph) { #' Breadth-first search #' -#' Breadth-first search is an algorithm to traverse a graph. We start from a -#' root vertex and spread along every edge \dQuote{simultaneously}. +#' Breadth-first search is an algorithm to traverse a graph. +#' We start from a root vertex and spread along every edge \dQuote{simultaneously}. #' #' #' The callback function must have the following arguments: @@ -3615,52 +3484,46 @@ count_loops <- function(graph) { #' } #' } #' -#' The callback must return `FALSE` -#' to continue the search or `TRUE` to terminate it. See examples below on how to -#' use the callback function. +#' The callback must return `FALSE` to continue the search or `TRUE` to terminate it. +#' See examples below on how to use the callback function. #' #' @param graph The input graph. -#' @param root Numeric vector, usually of length one. The root vertex, or root -#' vertices to start the search from. When several roots are given, they are -#' considered in the order they appear. If a root vertex was already reached -#' while searching from an earlier root, no separate search is started from -#' it, so it keeps the distance it was first found at rather than `0`. +#' @param root Numeric vector, usually of length one. +#' The root vertex, or root vertices to start the search from. +#' When several roots are given, they are considered in the order they appear. +#' If a root vertex was already reached while searching from an earlier root, no separate search is started from it, +#' so it keeps the distance it was first found at rather than `0`. #' @param mode For directed graphs specifies the type of edges to follow. -#' \sQuote{out} follows outgoing, \sQuote{in} incoming edges. \sQuote{all} -#' ignores edge directions completely. \sQuote{total} is a synonym for -#' \sQuote{all}. This argument is ignored for undirected graphs. -#' @param unreachable Logical, whether the search should visit the -#' vertices that are unreachable from the given root vertex (or vertices). If -#' `TRUE`, then additional searches are performed until all vertices are -#' visited. -#' @param restricted `NULL` (=no restriction), or a vector of vertices -#' (IDs or symbolic names). In the latter case, the search is restricted to the -#' given vertices. +#' \sQuote{out} follows outgoing, \sQuote{in} incoming edges. +#' \sQuote{all} ignores edge directions completely. +#' \sQuote{total} is a synonym for \sQuote{all}. +#' This argument is ignored for undirected graphs. +#' @param unreachable Logical, whether the search should visit the vertices that are unreachable from the given root vertex (or vertices). +#' If `TRUE`, then additional searches are performed until all vertices are visited. +#' @param restricted `NULL` (=no restriction), or a vector of vertices (IDs or symbolic names). +#' In the latter case, the search is restricted to the given vertices. #' @param order Logical, whether to return the ordering of the vertices. #' @param rank Logical, whether to return the rank of the vertices. #' @param father `r lifecycle::badge("deprecated")` Use `parent` instead. #' @param parent Logical, whether to return the parent of the vertices. -#' @param pred Logical, whether to return the predecessors of the -#' vertices. -#' @param succ Logical, whether to return the successors of the -#' vertices. -#' @param dist Logical, whether to return the distance from the root of -#' the search tree. -#' @param callback Callback function. This is called whenever a vertex is visited. -#' The callback function should return `FALSE` to continue the search -#' or `TRUE` to stop it. See details below. +#' @param pred Logical, whether to return the predecessors of the vertices. +#' @param succ Logical, whether to return the successors of the vertices. +#' @param dist Logical, whether to return the distance from the root of the search tree. +#' @param callback Callback function. +#' This is called whenever a vertex is visited. +#' The callback function should return `FALSE` to continue the search or `TRUE` to stop it. +#' See details below. #' Default: `NULL`. #' @param extra Additional argument to supply to the callback function. #' @param rho The environment in which the callback function is evaluated. #' The default `NULL` uses the caller's environment. -#' @param neimode `r lifecycle::badge("deprecated")` This argument is deprecated -#' from igraph 1.3.0; use `mode` instead. +#' @param neimode `r lifecycle::badge("deprecated")` This argument is deprecated from igraph 1.3.0; use `mode` instead. #' @inheritParams rlang::args_dots_empty #' @return A named list with the following entries: #' \describe{ #' \item{root}{ -#' Numeric vector. The root vertex (or vertices) that was used as the -#' starting point of the search, as supplied in the `root` argument. +#' Numeric vector. +#' The root vertex (or vertices) that was used as the starting point of the search, as supplied in the `root` argument. #' } #' \item{neimode}{ #' Character scalar. The `mode` argument of the function call. @@ -3698,9 +3561,8 @@ count_loops <- function(graph) { #' } #' } #' -#' Note that `order`, `rank`, `parent`, `pred`, `succ` -#' and `dist` might be `NULL` if their corresponding argument is -#' `FALSE`, i.e. if their calculation is not requested. +#' Note that `order`, `rank`, `parent`, `pred`, `succ` and `dist` might be `NULL` if their corresponding argument is `FALSE`, +#' i.e. if their calculation is not requested. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @seealso [dfs()] for depth-first search. #' @family structural.properties @@ -3817,10 +3679,9 @@ bfs <- function( rho ) - # The C implementation only returns the scalar `root` it was passed, which is - # always 0 (reported as 1) when multiple roots are supplied. Report all of the - # requested root vertices instead. See - # https://github.com/igraph/rigraph/issues/1639 + # The C implementation only returns the scalar `root` it was passed, which is always 0 (reported as 1) when multiple roots are supplied. + # Report all of the requested root vertices instead. + # See https://github.com/igraph/rigraph/issues/1639 res$root <- requested_roots # Remove in 1.4.0 @@ -3890,8 +3751,8 @@ bfs <- function( #' Depth-first search #' -#' Depth-first search is an algorithm to traverse a graph. It starts from a -#' root vertex and tries to go quickly as far from as possible. +#' Depth-first search is an algorithm to traverse a graph. +#' It starts from a root vertex and tries to go quickly as far from as possible. #' #' The callback functions must have the following arguments: #' \describe{ @@ -3907,38 +3768,35 @@ bfs <- function( #' The extra argument. #' } #' } The callback must return FALSE to continue the search or TRUE -#' to terminate it. See examples below on how to use the callback functions. +#' to terminate it. +#' See examples below on how to use the callback functions. #' #' @param graph The input graph. #' @param root The single root vertex to start the search from. #' @param mode For directed graphs specifies the type of edges to follow. -#' \sQuote{out} follows outgoing, \sQuote{in} incoming edges. \sQuote{all} -#' ignores edge directions completely. \sQuote{total} is a synonym for -#' \sQuote{all}. This argument is ignored for undirected graphs. -#' @param unreachable Logical, whether the search should visit the -#' vertices that are unreachable from the given root vertex (or vertices). If -#' `TRUE`, then additional searches are performed until all vertices are -#' visited. -#' @param order Logical, whether to return the DFS ordering of the -#' vertices. -#' @param order.out Logical, whether to return the ordering based on -#' leaving the subtree of the vertex. +#' \sQuote{out} follows outgoing, \sQuote{in} incoming edges. +#' \sQuote{all} ignores edge directions completely. +#' \sQuote{total} is a synonym for \sQuote{all}. +#' This argument is ignored for undirected graphs. +#' @param unreachable Logical, whether the search should visit the vertices that are unreachable from the given root vertex (or vertices). +#' If `TRUE`, then additional searches are performed until all vertices are visited. +#' @param order Logical, whether to return the DFS ordering of the vertices. +#' @param order.out Logical, whether to return the ordering based on leaving the subtree of the vertex. #' @param father `r lifecycle::badge("deprecated")`, use `parent` instead. #' @param parent Logical, whether to return the parent of the vertices. -#' @param dist Logical, whether to return the distance from the root of -#' the search tree. +#' @param dist Logical, whether to return the distance from the root of the search tree. #' @param in.callback Callback function. -#' This is called whenever a vertex is visited. See details below. +#' This is called whenever a vertex is visited. +#' See details below. #' Default: `NULL`. #' @param out.callback Callback function. -#' This is called whenever the subtree of a vertex is completed by the -#' algorithm. See details below. +#' This is called whenever the subtree of a vertex is completed by the algorithm. +#' See details below. #' Default: `NULL`. #' @param extra Additional argument to supply to the callback function. #' @param rho The environment in which the callback function is evaluated. #' The default `NULL` uses the caller's environment. -#' @param neimode `r lifecycle::badge("deprecated")` This argument is deprecated from igraph 1.3.0; use -#' `mode` instead. +#' @param neimode `r lifecycle::badge("deprecated")` This argument is deprecated from igraph 1.3.0; use `mode` instead. #' @inheritParams rlang::args_dots_empty #' @return A named list with the following entries: #' \describe{ @@ -3966,9 +3824,8 @@ bfs <- function( #' } #' } #' -#' Note that `order`, `order.out`, `parent`, and `dist` -#' might be `NULL` if their corresponding argument is `FALSE`, i.e. -#' if their calculation is not requested. +#' Note that `order`, `order.out`, `parent`, and `dist` might be `NULL` if their corresponding argument is `FALSE`, +#' i.e. if their calculation is not requested. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @seealso [bfs()] for breadth-first search. #' @family structural.properties @@ -4125,34 +3982,30 @@ dfs <- function( #' #' Calculate the maximal (weakly or strongly) connected components of a graph #' -#' `is_connected()` decides whether the graph is weakly or strongly -#' connected. The null graph is considered disconnected. +#' `is_connected()` decides whether the graph is weakly or strongly connected. +#' The null graph is considered disconnected. #' -#' `components()` finds the maximal (weakly or strongly) connected components -#' of a graph. +#' `components()` finds the maximal (weakly or strongly) connected components of a graph. #' -#' `count_components()` does almost the same as `components()` but returns only -#' the number of clusters found instead of returning the actual clusters. +#' `count_components()` does almost the same as `components()` but returns only the number of clusters found instead of returning the actual clusters. #' -#' `component_distribution()` creates a histogram for the maximal connected -#' component sizes. +#' `component_distribution()` creates a histogram for the maximal connected component sizes. #' -#' `largest_component()` returns the largest connected component of a graph. For -#' directed graphs, optionally the largest weakly or strongly connected component. -#' In case of a tie, the first component by vertex ID order is returned. Vertex -#' IDs from the original graph are not retained in the returned graph. +#' `largest_component()` returns the largest connected component of a graph. +#' For directed graphs, optionally the largest weakly or strongly connected component. +#' In case of a tie, the first component by vertex ID order is returned. +#' Vertex IDs from the original graph are not retained in the returned graph. #' #' The weakly connected components are found by a simple breadth-first search. -#' The strongly connected components are implemented by two consecutive -#' depth-first searches. +#' The strongly connected components are implemented by two consecutive depth-first searches. #' #' @param graph The graph to analyze. -#' @param mode Character string, either \dQuote{weak} or \dQuote{strong}. For -#' directed graphs \dQuote{weak} implies weakly, \dQuote{strong} strongly -#' connected components to search. It is ignored for undirected graphs. +#' @param mode Character string, either \dQuote{weak} or \dQuote{strong}. +#' For directed graphs \dQuote{weak} implies weakly, +#' \dQuote{strong} strongly connected components to search. +#' It is ignored for undirected graphs. #' @param \dots For `component_distribution()`, forwarded to `components()`. -#' For `components()`, `is_connected()`, `count_components()` and -#' `largest_component()`, these dots must be empty. +#' For `components()`, `is_connected()`, `count_components()` and `largest_component()`, these dots must be empty. #' @return For `is_connected()` a Logical. #' #' For `components()` a named list with three components: @@ -4170,10 +4023,10 @@ dfs <- function( #' #' For `count_components()` an integer constant is returned. #' -#' For `component_distribution()` a numeric vector with the relative -#' frequencies. The length of the vector is the size of the largest component -#' plus one. Note that (for currently unknown reasons) the first element of the -#' vector is the number of clusters of size zero, so this is always zero. +#' For `component_distribution()` a numeric vector with the relative frequencies. +#' The length of the vector is the size of the largest component plus one. +#' Note that (for currently unknown reasons) the first element of the vector is the number of clusters of size zero, +#' so this is always zero. #' #' For `largest_component()` the largest connected component of the graph. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} @@ -4349,24 +4202,18 @@ count_components <- function( #' #' Counts the number of vertices reachable from each vertex in the graph. #' -#' For each vertex in the graph, this function counts how many vertices -#' are reachable from it, including the vertex itself. +#' For each vertex in the graph, this function counts how many vertices are reachable from it, including the vertex itself. #' A vertex is reachable from another if there is a directed path between them. -#' For undirected graphs, two vertices are reachable from each other if they -#' are in the same connected component. +#' For undirected graphs, two vertices are reachable from each other if they are in the same connected component. #' #' @param graph The input graph. #' @inheritParams rlang::args_dots_empty -#' @param mode Character constant, defines how edge directions are considered -#' in directed graphs. +#' @param mode Character constant, defines how edge directions are considered in directed graphs. #' `"out"` counts vertices reachable via outgoing edges, -#' `"in"` counts vertices from which the current vertex is reachable via -#' incoming edges, -#' `"all"` or `"total"` ignores edge directions. +#' `"in"` counts vertices from which the current vertex is reachable via incoming edges, `"all"` or `"total"` ignores edge directions. #' This parameter is ignored for undirected graphs. #' @return An integer vector of length `vcount(graph)`. -#' The i-th element is the number of vertices reachable from vertex i -#' (including vertex i itself). +#' The i-th element is the number of vertices reachable from vertex i (including vertex i itself). #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @seealso [components()], [subcomponent()], [is_connected()] #' @family components @@ -4435,22 +4282,19 @@ count_reachable <- function( #' Convert a general graph into a forest #' -#' Perform a breadth-first search on a graph and convert it into a tree or -#' forest by replicating vertices that were found more than once. +#' Perform a breadth-first search on a graph and convert it into a tree or forest by replicating vertices that were found more than once. #' #' A forest is a graph, whose components are trees. #' -#' The `roots` vector can be calculated by simply doing a topological sort -#' in all components of the graph, see the examples below. +#' The `roots` vector can be calculated by simply doing a topological sort in all components of the graph, see the examples below. #' #' @param graph The input graph, it can be either directed or undirected. #' @inheritParams rlang::args_dots_empty -#' @param mode Character string, defined the types of the paths used for the -#' breadth-first search. \dQuote{out} follows the outgoing, \dQuote{in} the -#' incoming edges, \dQuote{all} and \dQuote{total} both of them. This argument -#' is ignored for undirected graphs. -#' @param roots A vector giving the vertices from which the breadth-first -#' search is performed. Typically it contains one vertex per component. +#' @param mode Character string, defined the types of the paths used for the breadth-first search. +#' \dQuote{out} follows the outgoing, \dQuote{in} the incoming edges, \dQuote{all} and \dQuote{total} both of them. +#' This argument is ignored for undirected graphs. +#' @param roots A vector giving the vertices from which the breadth-first search is performed. +#' Typically it contains one vertex per component. #' @return A list with two components: #' \describe{ #' \item{tree}{ @@ -4534,40 +4378,33 @@ unfold_tree <- function( #' #' The Laplacian of a graph. #' -#' The Laplacian Matrix of a graph is a symmetric matrix having the same number -#' of rows and columns as the number of vertices in the graph and element (i,j) -#' is d\[i\], the degree of vertex i if if i==j, -1 if i!=j and there is an edge -#' between vertices i and j and 0 otherwise. +#' The Laplacian Matrix of a graph is a symmetric matrix having the same number of rows and columns as the number of vertices in the graph and element (i,j) is d\[i\], +#' the degree of vertex i if if i==j, -1 if i!=j and there is an edge between vertices i and j and 0 otherwise. #' -#' The Laplacian matrix can also be normalized, with several -#' conventional normalization methods. +#' The Laplacian matrix can also be normalized, with several conventional normalization methods. #' See the "Normalization methods" section on this page. #' -#' The weighted version of the Laplacian simply works with the weighted degree -#' instead of the plain degree. I.e. (i,j) is d\[i\], the weighted degree of -#' vertex i if if i==j, -w if i!=j and there is an edge between vertices i and -#' j with weight w, and 0 otherwise. The weighted degree of a vertex is the sum -#' of the weights of its adjacent edges. +#' The weighted version of the Laplacian simply works with the weighted degree instead of the plain degree. +#' I.e. (i,j) is d\[i\], the weighted degree of vertex i if if i==j, -w if i!=j and there is an edge between vertices i and j with weight w, +#' and 0 otherwise. +#' The weighted degree of a vertex is the sum of the weights of its adjacent edges. #' #' @param graph The input graph. -#' @param normalization The normalization method to use when calculating the -#' Laplacian matrix. See the "Normalization methods" section on this page. +#' @param normalization The normalization method to use when calculating the Laplacian matrix. +#' See the "Normalization methods" section on this page. #' @param normalized Deprecated, use `normalization` instead. -#' @param weights An optional vector giving edge weights for weighted Laplacian -#' matrix. If this is `NULL` and the graph has an edge attribute called -#' `weight`, then it will be used automatically. Set this to `NA` if -#' you want the unweighted Laplacian on a graph that has a `weight` edge -#' attribute. -#' @param sparse Logical, whether to return the result as a sparse -#' matrix. The `Matrix` package is required for sparse matrices. +#' @param weights An optional vector giving edge weights for weighted Laplacian matrix. +#' If this is `NULL` and the graph has an edge attribute called `weight`, then it will be used automatically. +#' Set this to `NA` if you want the unweighted Laplacian on a graph that has a `weight` edge attribute. +#' @param sparse Logical, whether to return the result as a sparse matrix. +#' The `Matrix` package is required for sparse matrices. #' @return A numeric matrix. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @export #' @keywords graphs #' @section Normalization methods: #' -#' The Laplacian matrix \eqn{L} is defined in terms of the adjacency matrix -#' \eqn{A} and a diagonal matrix \eqn{D} containing the degrees as follows: +#' The Laplacian matrix \eqn{L} is defined in terms of the adjacency matrix \eqn{A} and a diagonal matrix \eqn{D} containing the degrees as follows: #' #' - "unnormalized": Unnormalized Laplacian, \eqn{L = D - A}. #' - "symmetric": Symmetrically normalized Laplacian, @@ -4647,59 +4484,45 @@ laplacian_matrix <- function( #' Matching #' -#' A matching in a graph means the selection of a set of edges that are -#' pairwise non-adjacent, i.e. they have no common incident vertices. A -#' matching is maximal if it is not a proper subset of any other matching. -#' -#' `is_matching()` checks a matching vector and verifies whether its -#' length matches the number of vertices in the given graph, its values are -#' between zero (inclusive) and the number of vertices (inclusive), and -#' whether there exists a corresponding edge in the graph for every matched -#' vertex pair. For bipartite graphs, it also verifies whether the matched -#' vertices are in different parts of the graph. -#' -#' `is_max_matching()` checks whether a matching is maximal. A matching -#' is maximal if and only if there exists no unmatched vertex in a graph -#' such that one of its neighbors is also unmatched. -#' -#' `max_bipartite_match()` calculates a maximum matching in a bipartite -#' graph. A matching in a bipartite graph is a partial assignment of -#' vertices of the first kind to vertices of the second kind such that each -#' vertex of the first kind is matched to at most one vertex of the second -#' kind and vice versa, and matched vertices must be connected by an edge -#' in the graph. The size (or cardinality) of a matching is the number of -#' edges. A matching is a maximum matching if there exists no other -#' matching with larger cardinality. For weighted graphs, a maximum -#' matching is a matching whose edges have the largest possible total -#' weight among all possible matchings. -#' -#' Maximum matchings in bipartite graphs are found by the push-relabel -#' algorithm with greedy initialization and a global relabeling after every -#' \eqn{n/2} steps where \eqn{n} is the number of vertices in the graph. +#' A matching in a graph means the selection of a set of edges that are pairwise non-adjacent, i.e. they have no common incident vertices. +#' A matching is maximal if it is not a proper subset of any other matching. +#' +#' `is_matching()` checks a matching vector and verifies whether its length matches the number of vertices in the given graph, +#' its values are between zero (inclusive) and the number of vertices (inclusive), +#' and whether there exists a corresponding edge in the graph for every matched vertex pair. +#' For bipartite graphs, it also verifies whether the matched vertices are in different parts of the graph. +#' +#' `is_max_matching()` checks whether a matching is maximal. +#' A matching is maximal if and only if there exists no unmatched vertex in a graph such that one of its neighbors is also unmatched. +#' +#' `max_bipartite_match()` calculates a maximum matching in a bipartite graph. +#' A matching in a bipartite graph is a partial assignment of vertices of the first kind to vertices of the second kind such that each vertex of the first kind is matched to at most one vertex of the second kind and vice versa, and matched vertices must be connected by an edge in the graph. +#' The size (or cardinality) of a matching is the number of edges. +#' A matching is a maximum matching if there exists no other matching with larger cardinality. +#' For weighted graphs, a maximum matching is a matching whose edges have the largest possible total weight among all possible matchings. +#' +#' Maximum matchings in bipartite graphs are found by the push-relabel algorithm with greedy initialization and a global relabeling after every \eqn{n/2} steps +#' where \eqn{n} is the number of vertices in the graph. #' #' @rdname matching #' @aliases max_bipartite_match -#' @param graph The input graph. It might be directed, but edge directions will -#' be ignored. -#' @param types Vertex types, if the graph is bipartite. By default they -#' are taken from the \sQuote{`type`} vertex attribute, if present. -#' @param matching A potential matching. An integer vector that gives the -#' pair in the matching for each vertex. For vertices without a pair, -#' supply `NA` here. -#' @param weights Potential edge weights. If the graph has an edge -#' attribute called \sQuote{`weight`}, and this argument is -#' `NULL`, then the edge attribute is used automatically. -#' In weighted matching, the weights of the edges must match as -#' much as possible. -#' @param eps A small real number used in equality tests in the weighted -#' bipartite matching algorithm. Two real numbers are considered equal in -#' the algorithm if their difference is smaller than `eps`. This is -#' required to avoid the accumulation of numerical errors. The default -#' `NULL` stands for the smallest \eqn{x}, such that -#' \eqn{1+x \ne 1}{1+x != 1} holds (`.Machine$double.eps`). If you are running the algorithm with no weights, this argument -#' is ignored. -#' @return `is_matching()` and `is_max_matching()` return a logical -#' scalar. +#' @param graph The input graph. +#' It might be directed, but edge directions will be ignored. +#' @param types Vertex types, if the graph is bipartite. +#' By default they are taken from the \sQuote{`type`} vertex attribute, if present. +#' @param matching A potential matching. +#' An integer vector that gives the pair in the matching for each vertex. +#' For vertices without a pair, supply `NA` here. +#' @param weights Potential edge weights. +#' If the graph has an edge attribute called \sQuote{`weight`}, and this argument is `NULL`, +#' then the edge attribute is used automatically. +#' In weighted matching, the weights of the edges must match as much as possible. +#' @param eps A small real number used in equality tests in the weighted bipartite matching algorithm. +#' Two real numbers are considered equal in the algorithm if their difference is smaller than `eps`. +#' This is required to avoid the accumulation of numerical errors. +#' The default `NULL` stands for the smallest \eqn{x}, such that \eqn{1+x \ne 1}{1+x != 1} holds (`.Machine$double.eps`). +#' If you are running the algorithm with no weights, this argument is ignored. +#' @return `is_matching()` and `is_max_matching()` return a logical scalar. #' #' `max_bipartite_match()` returns a list with components: #' \describe{ @@ -4847,24 +4670,21 @@ max_bipartite_match <- function( #' #' This function checks the reciprocal pair of the supplied edges. #' -#' In a directed graph an (A,B) edge is mutual if the graph also includes a -#' (B,A) directed edge. +#' In a directed graph an (A,B) edge is mutual if the graph also includes a (B,A) directed edge. #' -#' Note that multi-graphs are not handled properly, i.e. if the graph contains -#' two copies of (A,B) and one copy of (B,A), then these three edges are -#' considered to be mutual. +#' Note that multi-graphs are not handled properly, i.e. if the graph contains two copies of (A,B) and one copy of (B,A), +#' then these three edges are considered to be mutual. #' #' Undirected graphs contain only mutual edges by definition. #' #' @param graph The input graph. -#' @param eids Edge sequence, the edges that will be probed. The default -#' `NULL` includes all edges in the order of their IDs. +#' @param eids Edge sequence, the edges that will be probed. +#' The default `NULL` includes all edges in the order of their IDs. #' @inheritParams rlang::args_dots_empty #' @param loops Logical, whether to consider directed self-loops to be mutual. #' @return A logical vector of the same length as the number of edges supplied. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} -#' @seealso [reciprocity()], [dyad_census()] if you just -#' want some statistics about mutual edges. +#' @seealso [reciprocity()], [dyad_census()] if you just want some statistics about mutual edges. #' @keywords graphs #' @examples #' @@ -4930,42 +4750,36 @@ which_mutual <- function( #' Average nearest neighbor degree #' -#' Calculate the average nearest neighbor degree of the given vertices and the -#' same quantity in the function of vertex degree +#' Calculate the average nearest neighbor degree of the given vertices and the same quantity in the function of vertex degree #' -#' Note that for zero degree vertices the answer in \sQuote{`knn`} is -#' `NaN` (zero divided by zero), the same is true for \sQuote{`knnk`} -#' if a given degree never appears in the network. +#' Note that for zero degree vertices the answer in \sQuote{`knn`} is `NaN` (zero divided by zero), +#' the same is true for \sQuote{`knnk`} if a given degree never appears in the network. #' #' The weighted version computes a weighted average of the neighbor degrees as #' #' \deqn{k_{nn,u} = \frac{1}{s_u} \sum_v w_{uv} k_v,}{k_nn_u = 1/s_u sum_v w_uv k_v,} #' -#' where \eqn{s_u = \sum_v w_{uv}}{s_u = sum_v w_uv} is the sum of the incident -#' edge weights of vertex `u`, i.e. its strength. -#' The sum runs over the neighbors `v` of vertex `u` -#' as indicated by `mode`. \eqn{w_{uv}}{w_uv} denotes the weighted adjacency matrix -#' and \eqn{k_v}{k_v} is the neighbors' degree, specified by `neighbor_degree_mode`. +#' where \eqn{s_u = \sum_v w_{uv}}{s_u = sum_v w_uv} is the sum of the incident edge weights of vertex `u`, i.e. its strength. +#' The sum runs over the neighbors `v` of vertex `u` as indicated by `mode`. +#' \eqn{w_{uv}}{w_uv} denotes the weighted adjacency matrix and \eqn{k_v}{k_v} is the neighbors' degree, +#' specified by `neighbor_degree_mode`. #' -#' @param graph The input graph. It may be directed. +#' @param graph The input graph. +#' It may be directed. #' @param vids The vertices for which the calculation is performed. -#' The default `NULL` includes all vertices. Note, that if not all vertices are given here, then -#' both \sQuote{`knn`} and \sQuote{`knnk`} will be calculated based -#' on the given vertices only. +#' The default `NULL` includes all vertices. +#' Note, that if not all vertices are given here, +#' then both \sQuote{`knn`} and \sQuote{`knnk`} will be calculated based on the given vertices only. #' @inheritParams rlang::args_dots_empty -#' @param mode Character constant to indicate the type of neighbors to consider -#' in directed graphs. `out` considers out-neighbors, `in` considers -#' in-neighbors and `all` ignores edge directions. +#' @param mode Character constant to indicate the type of neighbors to consider in directed graphs. +#' `out` considers out-neighbors, `in` considers in-neighbors and `all` ignores edge directions. #' @param neighbor.degree.mode The type of degree to average in directed graphs. -#' `out` averages out-degrees, `in` averages in-degrees and `all` -#' ignores edge directions for the degree calculation. -#' @param weights Weight vector. If the graph has a `weight` edge -#' attribute, then this is used by default. If this argument is given, then -#' vertex strength (see [strength()]) is used instead of vertex -#' degree. But note that `knnk` is still given in the function of the -#' normal vertex degree. -#' Weights are are used to calculate a weighted degree (also called -#' [strength()]) instead of the degree. +#' `out` averages out-degrees, `in` averages in-degrees and `all` ignores edge directions for the degree calculation. +#' @param weights Weight vector. +#' If the graph has a `weight` edge attribute, then this is used by default. +#' If this argument is given, then vertex strength (see [strength()]) is used instead of vertex degree. +#' But note that `knnk` is still given in the function of the normal vertex degree. +#' Weights are are used to calculate a weighted degree (also called [strength()]) instead of the degree. #' @return A list with two members: #' \describe{ #' \item{knn}{ diff --git a/R/structure.info.R b/R/structure.info.R index 3f24c0f6b5b..e831fa3ae9e 100644 --- a/R/structure.info.R +++ b/R/structure.info.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `are.connected()` was renamed to [are_adjacent()] to create a more -#' consistent API. +#' `are.connected()` was renamed to [are_adjacent()] to create a more consistent API. #' @inheritParams are_adjacent #' @keywords internal #' @export diff --git a/R/tkplot.R b/R/tkplot.R index 96934a4c80d..75bd7593e3a 100644 --- a/R/tkplot.R +++ b/R/tkplot.R @@ -4,8 +4,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `tkplot.setcoords()` was renamed to [tk_set_coords()] to create a more -#' consistent API. +#' `tkplot.setcoords()` was renamed to [tk_set_coords()] to create a more consistent API. #' @inheritParams tk_set_coords #' @keywords internal #' @export @@ -20,8 +19,7 @@ tkplot.setcoords <- function(tkp.id, coords) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `tkplot.rotate()` was renamed to [tk_rotate()] to create a more -#' consistent API. +#' `tkplot.rotate()` was renamed to [tk_rotate()] to create a more consistent API. #' @inheritParams tk_rotate #' @keywords internal #' @export @@ -36,8 +34,7 @@ tkplot.rotate <- function(tkp.id, degree = NULL, rad = NULL) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `tkplot.reshape()` was renamed to [tk_reshape()] to create a more -#' consistent API. +#' `tkplot.reshape()` was renamed to [tk_reshape()] to create a more consistent API. #' @inheritParams tk_reshape #' @keywords internal #' @export @@ -52,8 +49,7 @@ tkplot.reshape <- function(tkp.id, newlayout, ..., params) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `tkplot.off()` was renamed to [tk_off()] to create a more -#' consistent API. +#' `tkplot.off()` was renamed to [tk_off()] to create a more consistent API. #' #' @keywords internal #' @export @@ -68,8 +64,7 @@ tkplot.off <- function() { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `tkplot.getcoords()` was renamed to [tk_coords()] to create a more -#' consistent API. +#' `tkplot.getcoords()` was renamed to [tk_coords()] to create a more consistent API. #' @inheritParams tk_coords #' @keywords internal #' @export @@ -84,8 +79,7 @@ tkplot.getcoords <- function(tkp.id, norm = FALSE) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `tkplot.fit.to.screen()` was renamed to [tk_fit()] to create a more -#' consistent API. +#' `tkplot.fit.to.screen()` was renamed to [tk_fit()] to create a more consistent API. #' @inheritParams tk_fit #' @keywords internal #' @export @@ -100,8 +94,7 @@ tkplot.fit.to.screen <- function(tkp.id, width = NULL, height = NULL) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `tkplot.export.postscript()` was renamed to [tk_postscript()] to create a more -#' consistent API. +#' `tkplot.export.postscript()` was renamed to [tk_postscript()] to create a more consistent API. #' @inheritParams tk_postscript #' @keywords internal #' @export @@ -120,8 +113,7 @@ tkplot.export.postscript <- function(tkp.id) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `tkplot.close()` was renamed to [tk_close()] to create a more -#' consistent API. +#' `tkplot.close()` was renamed to [tk_close()] to create a more consistent API. #' @inheritParams tk_close #' @keywords internal #' @export @@ -136,8 +128,7 @@ tkplot.close <- function(tkp.id, window.close = TRUE) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `tkplot.center()` was renamed to [tk_center()] to create a more -#' consistent API. +#' `tkplot.center()` was renamed to [tk_center()] to create a more consistent API. #' @inheritParams tk_center #' @keywords internal #' @export @@ -152,8 +143,7 @@ tkplot.center <- function(tkp.id) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `tkplot.canvas()` was renamed to [tk_canvas()] to create a more -#' consistent API. +#' `tkplot.canvas()` was renamed to [tk_canvas()] to create a more consistent API. #' @inheritParams tk_canvas #' @keywords internal #' @export @@ -197,71 +187,58 @@ assign(".next", 1, .tkplot.env) #' Interactive plotting of graphs #' -#' `tkplot()` and its companion functions serve as an interactive graph -#' drawing facility. Not all parameters of the plot can be changed -#' interactively right now though, e.g. the colors of vertices, edges, and also -#' others have to be pre-defined. +#' `tkplot()` and its companion functions serve as an interactive graph drawing facility. +#' Not all parameters of the plot can be changed interactively right now though, e.g. the colors of vertices, edges, +#' and also others have to be pre-defined. #' -#' `tkplot()` is an interactive graph drawing facility. It is not very well -#' developed at this stage, but it should be still useful. +#' `tkplot()` is an interactive graph drawing facility. +#' It is not very well developed at this stage, but it should be still useful. #' -#' It's handling should be quite straightforward most of the time, here are -#' some remarks and hints. +#' It's handling should be quite straightforward most of the time, here are some remarks and hints. #' -#' There are different popup menus, activated by the right mouse button, for -#' vertices and edges. Both operate on the current selection if the vertex/edge -#' under the cursor is part of the selection and operate on the vertex/edge -#' under the cursor if it is not. +#' There are different popup menus, activated by the right mouse button, for vertices and edges. +#' Both operate on the current selection +#' if the vertex/edge under the cursor is part of the selection and operate on the vertex/edge under the cursor if it is not. #' #' One selection can be active at a time, either a vertex or an edge selection. -#' A vertex/edge can be added to a selection by holding the `control` key -#' while clicking on it with the left mouse button. Doing this again deselect -#' the vertex/edge. +#' A vertex/edge can be added to a selection by holding the `control` key while clicking on it with the left mouse button. +#' Doing this again deselect the vertex/edge. #' -#' Selections can be made also from the "Select" menu. The "Select some -#' vertices" dialog allows to give an expression for the vertices to be -#' selected: this can be a list of numeric R expessions separated by commas, -#' like `1,2:10,12,14,15` for example. Similarly in the "Select some -#' edges" dialog two such lists can be given and all edges connecting a vertex -#' in the first list to one in the second list will be selected. +#' Selections can be made also from the "Select" menu. +#' The "Select some vertices" dialog allows to give an expression for the vertices to be selected: +#' this can be a list of numeric R expessions separated by commas, like `1,2:10,12,14,15` for example. +#' Similarly in the "Select some edges" dialog two such lists can be given and all edges connecting a vertex in the first list to one in the second list will be selected. #' -#' In the color dialog a color name like 'orange' or RGB notation can also be -#' used. +#' In the color dialog a color name like 'orange' or RGB notation can also be used. #' -#' The `tkplot()` command creates a new Tk window with the graphical -#' representation of `graph`. The command returns an integer number, the -#' tkplot ID. The other commands utilize this ID to be able to query or -#' manipulate the plot. +#' The `tkplot()` command creates a new Tk window with the graphical representation of `graph`. +#' The command returns an integer number, the tkplot ID. +#' The other commands utilize this ID to be able to query or manipulate the plot. #' #' `tk_close()` closes the Tk plot with ID `tkp.id`. #' #' `tk_off()` closes all Tk plots. #' -#' `tk_fit()` fits the plot to the given rectangle -#' (`width` and `height`), if some of these are `NULL` the -#' actual physical width od height of the plot window is used. +#' `tk_fit()` fits the plot to the given rectangle (`width` and `height`), +#' if some of these are `NULL` the actual physical width od height of the plot window is used. #' -#' `tk_reshape()` applies a new layout to the plot, its optional -#' parameters will be collected to a list analogous to `layout.par`. +#' `tk_reshape()` applies a new layout to the plot, its optional parameters will be collected to a list analogous to `layout.par`. #' -#' `tk_postscript()` creates a dialog window for saving the plot -#' in postscript format. +#' `tk_postscript()` creates a dialog window for saving the plot in postscript format. #' -#' `tk_canvas()` returns the Tk canvas object that belongs to a graph -#' plot. The canvas can be directly manipulated then, e.g. labels can be added, -#' it could be saved to a file programmatically, etc. See an example below. +#' `tk_canvas()` returns the Tk canvas object that belongs to a graph plot. +#' The canvas can be directly manipulated then, e.g. labels can be added, it could be saved to a file programmatically, +#' etc. See an example below. #' #' `tk_coords()` returns the coordinates of the vertices in a matrix. #' Each row corresponds to one vertex. #' -#' `tk_set_coords()` sets the coordinates of the vertices. A two-column -#' matrix specifies the new positions, with each row corresponding to a single -#' vertex. +#' `tk_set_coords()` sets the coordinates of the vertices. +#' A two-column matrix specifies the new positions, with each row corresponding to a single vertex. #' #' `tk_center()` shifts the figure to the center of its plot window. #' -#' `tk_rotate()` rotates the figure, its parameter can be given either -#' in degrees or in radians. +#' `tk_rotate()` rotates the figure, its parameter can be given either in degrees or in radians. #' #' tkplot.center tkplot.rotate #' @param graph The `graph` to plot. @@ -272,23 +249,18 @@ assign(".next", 1, .tkplot.env) #' @param height The height of the rectangle for generating new coordinates. #' @param newlayout The new layout, see the `layout` parameter of tkplot. #' @param norm Logical, should we norm the coordinates. -#' @param coords Two-column numeric matrix, the new coordinates of the -#' vertices, in absolute coordinates. +#' @param coords Two-column numeric matrix, the new coordinates of the vertices, in absolute coordinates. #' @param degree The degree to rotate the plot. #' @param rad The degree to rotate the plot, in radian. -#' @param \dots For `tkplot()`, additional plotting parameters, see -#' [igraph.plotting] for the complete list. For `tk_close()`, `tk_fit()`, -#' `tk_coords()` and `tk_rotate()`, these dots must be empty. -#' @return `tkplot()` returns an integer, the ID of the plot, this can be -#' used to manipulate it from the command line. +#' @param \dots For `tkplot()`, additional plotting parameters, see [igraph.plotting] for the complete list. +#' For `tk_close()`, `tk_fit()`, `tk_coords()` and `tk_rotate()`, these dots must be empty. +#' @return `tkplot()` returns an integer, the ID of the plot, this can be used to manipulate it from the command line. #' #' `tk_canvas()` returns `tkwin` object, the Tk canvas. #' #' `tk_coords()` returns a matrix with the coordinates. #' -#' `tk_close()`, `tk_off()`, `tk_fit()`, -#' `tk_reshape()`, `tk_postscript()`, `tk_center()` -#' and `tk_rotate()` return `NULL` invisibly. +#' `tk_close()`, `tk_off()`, `tk_fit()`, `tk_reshape()`, `tk_postscript()`, `tk_center()` and `tk_rotate()` return `NULL` invisibly. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @seealso [plot.igraph()], [layout()] #' @family tkplot diff --git a/R/topology.R b/R/topology.R index 1069c076de5..36a3e5a926e 100644 --- a/R/topology.R +++ b/R/topology.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `permute.vertices()` was renamed to [permute()] to create a more -#' consistent API. +#' `permute.vertices()` was renamed to [permute()] to create a more consistent API. #' @inheritParams permute #' @keywords internal #' @export @@ -19,8 +18,7 @@ permute.vertices <- function(graph, permutation) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.isocreate()` was renamed to [graph_from_isomorphism_class()] to create a more -#' consistent API. +#' `graph.isocreate()` was renamed to [graph_from_isomorphism_class()] to create a more consistent API. #' @inheritParams graph_from_isomorphism_class #' @keywords internal #' @export @@ -43,8 +41,7 @@ graph.isocreate <- function(size, number, directed = TRUE) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `graph.automorphisms()` was renamed to [count_automorphisms()] to create a more -#' consistent API. +#' `graph.automorphisms()` was renamed to [count_automorphisms()] to create a more consistent API. #' @inheritParams count_automorphisms #' @keywords internal #' @export @@ -67,8 +64,7 @@ graph.automorphisms <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `canonical.permutation()` was renamed to [canonical_permutation()] to create a more -#' consistent API. +#' `canonical.permutation()` was renamed to [canonical_permutation()] to create a more consistent API. #' @inheritParams canonical_permutation #' @keywords internal #' @export @@ -91,8 +87,7 @@ canonical.permutation <- function( #' @description #' `r lifecycle::badge("deprecated")` #' -#' `automorphisms()` was renamed to [count_automorphisms()] to create a more -#' consistent API. +#' `automorphisms()` was renamed to [count_automorphisms()] to create a more consistent API. #' @inheritParams count_automorphisms #' @keywords internal #' @export @@ -310,14 +305,12 @@ graph.subisomorphic.lad <- function( #' } #' #' @section \sQuote{direct} method: -#' This method only works on graphs with three or four vertices, -#' and it is based on a pre-calculated and stored table. It does not -#' have any extra arguments. +#' This method only works on graphs with three or four vertices, and it is based on a pre-calculated and stored table. +#' It does not have any extra arguments. #' #' @section \sQuote{vf2} method: -#' This method uses the VF2 algorithm by Cordella, Foggia et al., see -#' references below. It supports vertex and edge colors and have the -#' following extra arguments: +#' This method uses the VF2 algorithm by Cordella, Foggia et al., see references below. +#' It supports vertex and edge colors and have the following extra arguments: #' \describe{ #' \item{vertex.color1, vertex.color2}{ #' Optional integer vectors giving the colors of the vertices for colored graph isomorphism. @@ -333,11 +326,9 @@ graph.subisomorphic.lad <- function( #' } #' #' @section \sQuote{bliss} method: -#' Uses the BLISS algorithm by Junttila and Kaski, and it works for -#' undirected graphs. For both graphs the -#' [canonical_permutation()] and then the [permute()] -#' function is called to transfer them into canonical form; finally the -#' canonical forms are compared. +#' Uses the BLISS algorithm by Junttila and Kaski, and it works for undirected graphs. +#' For both graphs the [canonical_permutation()] and then the [permute()] function is called to transfer them into canonical form; +#' finally the canonical forms are compared. #' Extra arguments: #' \describe{ #' \item{sh}{ @@ -348,9 +339,9 @@ graph.subisomorphic.lad <- function( #' #' @param graph1 The first graph. #' @param graph2 The second graph. -#' @param method The method to use. Possible values: \sQuote{auto}, -#' \sQuote{direct}, \sQuote{vf2}, \sQuote{bliss}. See their details -#' below. +#' @param method The method to use. +#' Possible values: \sQuote{auto}, \sQuote{direct}, \sQuote{vf2}, \sQuote{bliss}. +#' See their details below. #' @param ... Additional arguments, passed to the various methods. #' @return Logical scalar, `TRUE` if the graphs are isomorphic. #' @@ -639,12 +630,11 @@ is_isomorphic_to <- isomorphic #' Decide if a graph is subgraph isomorphic to another one #' #' @section \sQuote{auto} method: -#' This method currently selects \sQuote{lad}, always, as it seems -#' to be superior on most graphs. +#' This method currently selects \sQuote{lad}, always, as it seems to be superior on most graphs. #' #' @section \sQuote{lad} method: -#' This is the LAD algorithm by Solnon, see the reference below. It has -#' the following extra arguments: +#' This is the LAD algorithm by Solnon, see the reference below. +#' It has the following extra arguments: #' \describe{ #' \item{domains}{ #' Matching restrictions. @@ -664,9 +654,8 @@ is_isomorphic_to <- isomorphic #' } #' #' @section \sQuote{vf2} method: -#' This method uses the VF2 algorithm by Cordella, Foggia et al., see -#' references below. It supports vertex and edge colors and have the -#' following extra arguments: +#' This method uses the VF2 algorithm by Cordella, Foggia et al., see references below. +#' It supports vertex and edge colors and have the following extra arguments: #' \describe{ #' \item{vertex.color1, vertex.color2}{ #' Optional integer vectors giving the colors of the vertices for colored graph isomorphism. @@ -681,17 +670,15 @@ is_isomorphic_to <- isomorphic #' } #' } #' -#' @param pattern The smaller graph, it might be directed or -#' undirected. Undirected graphs are treated as directed graphs with -#' mutual edges. -#' @param target The bigger graph, it might be directed or -#' undirected. Undirected graphs are treated as directed graphs with -#' mutual edges. -#' @param method The method to use. Possible values: \sQuote{auto}, -#' \sQuote{lad}, \sQuote{vf2}. See their details below. +#' @param pattern The smaller graph, it might be directed or undirected. +#' Undirected graphs are treated as directed graphs with mutual edges. +#' @param target The bigger graph, it might be directed or undirected. +#' Undirected graphs are treated as directed graphs with mutual edges. +#' @param method The method to use. +#' Possible values: \sQuote{auto}, \sQuote{lad}, \sQuote{vf2}. +#' See their details below. #' @param ... Additional arguments, passed to the various methods. -#' @return Logical scalar, `TRUE` if the `pattern` is -#' isomorphic to a (possibly induced) subgraph of `target`. +#' @return Logical scalar, `TRUE` if the `pattern` is isomorphic to a (possibly induced) subgraph of `target`. #' #' @aliases graph.subisomorphic.vf2 graph.subisomorphic.lad #' @@ -764,8 +751,7 @@ is_subgraph_isomorphic_to <- subgraph_isomorphic #' #' @param graph1 The first graph. #' @param graph2 The second graph. -#' @param method Currently only \sQuote{vf2} is supported, see -#' [isomorphic()] for details about it and extra arguments. +#' @param method Currently only \sQuote{vf2} is supported, see [isomorphic()] for details about it and extra arguments. #' @param ... Passed to the individual methods. #' @return Number of isomorphic mappings between the two graphs. #' @@ -873,12 +859,11 @@ graph.count.isomorphisms.vf2 <- function( ) } -#' Count the isomorphic mappings between a graph and the subgraphs of -#' another graph +#' Count the isomorphic mappings between a graph and the subgraphs of another graph #' #' @section \sQuote{lad} method: -#' This is the LAD algorithm by Solnon, see the reference below. It has -#' the following extra arguments: +#' This is the LAD algorithm by Solnon, see the reference below. +#' It has the following extra arguments: #' \describe{ #' \item{domains}{ #' Matching restrictions. @@ -896,9 +881,8 @@ graph.count.isomorphisms.vf2 <- function( #' } #' #' @section \sQuote{vf2} method: -#' This method uses the VF2 algorithm by Cordella, Foggia et al., see -#' references below. It supports vertex and edge colors and have the -#' following extra arguments: +#' This method uses the VF2 algorithm by Cordella, Foggia et al., see references below. +#' It supports vertex and edge colors and have the following extra arguments: #' \describe{ #' \item{vertex.color1, vertex.color2}{ #' Optional integer vectors giving the colors of the vertices for colored graph isomorphism. @@ -913,17 +897,15 @@ graph.count.isomorphisms.vf2 <- function( #' } #' } #' -#' @param pattern The smaller graph, it might be directed or -#' undirected. Undirected graphs are treated as directed graphs with -#' mutual edges. -#' @param target The bigger graph, it might be directed or -#' undirected. Undirected graphs are treated as directed graphs with -#' mutual edges. -#' @param method The method to use. Possible values: -#' \sQuote{lad}, \sQuote{vf2}. See their details below. +#' @param pattern The smaller graph, it might be directed or undirected. +#' Undirected graphs are treated as directed graphs with mutual edges. +#' @param target The bigger graph, it might be directed or undirected. +#' Undirected graphs are treated as directed graphs with mutual edges. +#' @param method The method to use. +#' Possible values: \sQuote{lad}, \sQuote{vf2}. +#' See their details below. #' @param ... Additional arguments, passed to the various methods. -#' @return Logical scalar, `TRUE` if the `pattern` is -#' isomorphic to a (possibly induced) subgraph of `target`. +#' @return Logical scalar, `TRUE` if the `pattern` is isomorphic to a (possibly induced) subgraph of `target`. #' #' @aliases graph.count.subisomorphisms.vf2 #' @@ -1028,25 +1010,21 @@ graph.count.subisomorphisms.vf2 <- function( #' #' @param graph1 The first graph. #' @param graph2 The second graph. -#' @param method Currently only \sQuote{vf2} is supported, see -#' [isomorphic()] for details about it and extra arguments. +#' @param method Currently only \sQuote{vf2} is supported, see [isomorphic()] for details about it and extra arguments. #' @param ... Extra arguments, passed to the various methods. #' @param callback Optional callback function to call for each isomorphism found. -#' If provided, the function should accept two arguments: `map12` (integer vector -#' mapping vertex IDs from graph1 to graph2, 1-based indexing) and `map21` -#' (integer vector mapping vertex IDs from graph2 to graph1, 1-based indexing). +#' If provided, the function should accept two arguments: +#' `map12` (integer vector mapping vertex IDs from graph1 to graph2, 1-based indexing) and `map21` (integer vector mapping vertex IDs from graph2 to graph1, 1-based indexing). #' The function should return `FALSE` to continue the search or `TRUE` to stop it. #' If `NULL` (the default), all isomorphisms are collected and returned as a list. #' Only supported for `method = "vf2"`. #' -#' **Important limitation:** Callback functions must NOT call any igraph -#' functions (including simple queries like `vcount()` or `ecount()`). Doing -#' so will cause R to crash due to reentrancy issues. Extract -#' any needed graph information before calling the function with a callback, or -#' use collector mode (the default) and process results afterward. -#' @return If `callback` is `NULL`, returns a list of vertex sequences, corresponding -#' to all mappings from the first graph to the second. If `callback` is provided, -#' returns `NULL` invisibly. +#' **Important limitation:** Callback functions must NOT call any igraph functions (including simple queries like `vcount()` or `ecount()`). +#' Doing so will cause R to crash due to reentrancy issues. +#' Extract any needed graph information before calling the function with a callback, +#' or use collector mode (the default) and process results afterward. +#' @return If `callback` is `NULL`, returns a list of vertex sequences, corresponding to all mappings from the first graph to the second. +#' If `callback` is provided, returns `NULL` invisibly. #' #' @aliases graph.get.isomorphisms.vf2 #' @@ -1109,8 +1087,8 @@ isomorphisms <- function(graph1, graph2, method = "vf2", ..., callback = NULL) { #' All isomorphic mappings between a graph and subgraphs of another graph #' #' @section \sQuote{lad} method: -#' This is the LAD algorithm by Solnon, see the reference below. It has -#' the following extra arguments: +#' This is the LAD algorithm by Solnon, see the reference below. +#' It has the following extra arguments: #' \describe{ #' \item{domains}{ #' Matching restrictions. @@ -1130,9 +1108,8 @@ isomorphisms <- function(graph1, graph2, method = "vf2", ..., callback = NULL) { #' } #' #' @section \sQuote{vf2} method: -#' This method uses the VF2 algorithm by Cordella, Foggia et al., see -#' references below. It supports vertex and edge colors and have the -#' following extra arguments: +#' This method uses the VF2 algorithm by Cordella, Foggia et al., see references below. +#' It supports vertex and edge colors and have the following extra arguments: #' \describe{ #' \item{vertex.color1, vertex.color2}{ #' Optional integer vectors giving the colors of the vertices for colored graph isomorphism. @@ -1147,31 +1124,28 @@ isomorphisms <- function(graph1, graph2, method = "vf2", ..., callback = NULL) { #' } #' } #' -#' @param pattern The smaller graph, it might be directed or -#' undirected. Undirected graphs are treated as directed graphs with -#' mutual edges. -#' @param target The bigger graph, it might be directed or -#' undirected. Undirected graphs are treated as directed graphs with -#' mutual edges. -#' @param method The method to use. Possible values: \sQuote{auto}, -#' \sQuote{lad}, \sQuote{vf2}. See their details below. +#' @param pattern The smaller graph, it might be directed or undirected. +#' Undirected graphs are treated as directed graphs with mutual edges. +#' @param target The bigger graph, it might be directed or undirected. +#' Undirected graphs are treated as directed graphs with mutual edges. +#' @param method The method to use. +#' Possible values: \sQuote{auto}, \sQuote{lad}, \sQuote{vf2}. +#' See their details below. #' @param ... Additional arguments, passed to the various methods. #' @param callback Optional callback function to call for each subisomorphism found. -#' If provided, the function should accept two arguments: `map12` (integer vector -#' mapping vertex IDs from pattern to target, 1-based indexing) and `map21` -#' (integer vector mapping vertex IDs from target to pattern, 1-based indexing). +#' If provided, the function should accept two arguments: +#' `map12` (integer vector mapping vertex IDs from pattern to target, 1-based indexing) and `map21` (integer vector mapping vertex IDs from target to pattern, 1-based indexing). #' The function should return `FALSE` to continue the search or `TRUE` to stop it. #' If `NULL` (the default), all subisomorphisms are collected and returned as a list. #' Only supported for `method = "vf2"`. #' -#' **Important limitation:** Callback functions must NOT call any igraph -#' functions (including simple queries like `vcount()` or `ecount()`). Doing -#' so will cause R to crash due to reentrancy issues. Extract -#' any needed graph information before calling the function with a callback, or -#' use collector mode (the default) and process results afterward. -#' @return If `callback` is `NULL`, returns a list of vertex sequences, corresponding -#' to all mappings from the pattern graph to the target graph. If `callback` is -#' provided, returns `NULL` invisibly. +#' **Important limitation:** Callback functions must NOT call any igraph functions (including simple queries like `vcount()` or `ecount()`). +#' Doing so will cause R to crash due to reentrancy issues. +#' Extract any needed graph information before calling the function with a callback, +#' or use collector mode (the default) and process results afterward. +#' @return If `callback` is `NULL`, returns a list of vertex sequences, +#' corresponding to all mappings from the pattern graph to the target graph. +#' If `callback` is provided, returns `NULL` invisibly. #' #' @aliases graph.get.subisomorphisms.vf2 #' @@ -1245,14 +1219,12 @@ subgraph_isomorphisms <- function( #' Isomorphism class of a graph #' #' The isomorphism class is a non-negative integer number. -#' Graphs (with the same number of vertices) having the same isomorphism -#' class are isomorphic and isomorphic graphs always have the same -#' isomorphism class. Currently it can handle directed graphs with 3 or 4 -#' vertices and undirected graphs with 3 to 6 vertices. +#' Graphs (with the same number of vertices) having the same isomorphism class are isomorphic and isomorphic graphs always have the same isomorphism class. +#' Currently it can handle directed graphs with 3 or 4 vertices and undirected graphs with 3 to 6 vertices. #' #' @param graph The input graph. -#' @param v Optionally a vertex sequence. If not missing, then an induced -#' subgraph of the input graph, consisting of this vertices, is used. +#' @param v Optionally a vertex sequence. +#' If not missing, then an induced subgraph of the input graph, consisting of this vertices, is used. #' @return An integer number. #' #' @aliases graph.isoclass graph.isoclass.subgraph @@ -1284,17 +1256,14 @@ graph.isoclass <- function(graph) { #' Create a graph from an isomorphism class #' #' The isomorphism class is a non-negative integer number. -#' Graphs (with the same number of vertices) having the same isomorphism -#' class are isomorphic and isomorphic graphs always have the same -#' isomorphism class. Currently it can handle directed graphs with 3 or 4 -#' vertices and undirected graphd with 3 to 6 vertices. +#' Graphs (with the same number of vertices) having the same isomorphism class are isomorphic and isomorphic graphs always have the same isomorphism class. +#' Currently it can handle directed graphs with 3 or 4 vertices and undirected graphd with 3 to 6 vertices. #' #' @param size The number of vertices in the graph. #' @param number The isomorphism class. #' @inheritParams rlang::args_dots_empty #' @param directed Whether to create a directed graph (the default). -#' @return An igraph object, the graph of the given size, directedness -#' and isomorphism class. +#' @return An igraph object, the graph of the given size, directedness and isomorphism class. #' #' @family graph isomorphism #' @export @@ -1349,15 +1318,13 @@ graph_from_isomorphism_class <- function( #' Canonical permutation of a graph #' -#' The canonical permutation brings every isomorphic graphs into the same -#' (labeled) graph. +#' The canonical permutation brings every isomorphic graphs into the same (labeled) graph. #' -#' `canonical_permutation()` computes a permutation which brings the graph -#' into canonical form, as defined by the BLISS algorithm. All isomorphic -#' graphs have the same canonical form. +#' `canonical_permutation()` computes a permutation which brings the graph into canonical form, as defined by the BLISS algorithm. +#' All isomorphic graphs have the same canonical form. #' -#' See the paper below for the details about BLISS. This and more information -#' is available at . +#' See the paper below for the details about BLISS. +#' This and more information is available at . #' #' The possible values for the `sh` argument are: #' \describe{ @@ -1380,19 +1347,17 @@ graph_from_isomorphism_class <- function( #' Smallest maximally non-trivially connected non-singleton cell. #' } #' } -#' See the paper in references for details -#' about these. +#' See the paper in references for details about these. #' #' @param graph The input graph, treated as undirected. -#' @param colors The colors of the individual vertices of the graph; only -#' vertices having the same color are allowed to match each other in an -#' automorphism. When omitted, igraph uses the `color` attribute of the -#' vertices, or, if there is no such vertex attribute, it simply assumes that -#' all vertices have the same color. Pass NULL explicitly if the graph has a -#' `color` vertex attribute but you do not want to use it. +#' @param colors The colors of the individual vertices of the graph; +#' only vertices having the same color are allowed to match each other in an automorphism. +#' When omitted, igraph uses the `color` attribute of the vertices, or, if there is no such vertex attribute, +#' it simply assumes that all vertices have the same color. +#' Pass NULL explicitly if the graph has a `color` vertex attribute but you do not want to use it. #' @inheritParams rlang::args_dots_empty -#' @param sh Type of the heuristics to use for the BLISS algorithm. See details -#' for possible values. +#' @param sh Type of the heuristics to use for the BLISS algorithm. +#' See details for possible values. #' @return A list with the following members: #' \describe{ #' \item{labeling}{ @@ -1427,9 +1392,8 @@ graph_from_isomorphism_class <- function( #' } #' @author Tommi Junttila for BLISS, Gabor Csardi #' \email{csardi.gabor@@gmail.com} for the igraph and R interfaces. -#' @seealso [permute()] to apply a permutation to a graph, -#' [isomorphic()] for deciding graph isomorphism, possibly -#' based on canonical labels. +#' @seealso [permute()] to apply a permutation to a graph, [isomorphic()] for deciding graph isomorphism, +#' possibly based on canonical labels. #' @references Tommi Junttila and Petteri Kaski: Engineering an Efficient #' Canonical Labeling Tool for Large and Sparse Graphs, *Proceedings of #' the Ninth Workshop on Algorithm Engineering and Experiments and the Fourth @@ -1508,17 +1472,14 @@ canonical_permutation <- function( #' #' Create a new graph, by permuting vertex IDs. #' -#' This function creates a new graph from the input graph by permuting its -#' vertices according to the specified mapping. Call this function with the -#' output of [canonical_permutation()] to create the canonical form -#' of a graph. +#' This function creates a new graph from the input graph by permuting its vertices according to the specified mapping. +#' Call this function with the output of [canonical_permutation()] to create the canonical form of a graph. #' #' `permute()` keeps all graph, vertex and edge attributes of the graph. #' #' @param graph The input graph, it can directed or undirected. -#' @param permutation A numeric vector giving the permutation to apply. The -#' first element is the new ID of vertex 1, etc. Every number between one and -#' `vcount(graph)` must appear exactly once. +#' @param permutation A numeric vector giving the permutation to apply. +#' The first element is the new ID of vertex 1, etc. Every number between one and `vcount(graph)` must appear exactly once. #' @return A new graph object. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @seealso [canonical_permutation()] @@ -1559,29 +1520,23 @@ graph.isomorphic <- function(graph1, graph2) { #' Number of automorphisms #' -#' Calculate the number of automorphisms of a graph, i.e. the number of -#' isomorphisms to itself. +#' Calculate the number of automorphisms of a graph, i.e. the number of isomorphisms to itself. #' -#' An automorphism of a graph is a permutation of its vertices which brings the -#' graph into itself. +#' An automorphism of a graph is a permutation of its vertices which brings the graph into itself. #' -#' This function calculates the number of automorphism of a graph using the -#' BLISS algorithm. See also the BLISS homepage at -#' . If you need the -#' automorphisms themselves, use [automorphism_group()] to obtain -#' a compact representation of the automorphism group. +#' This function calculates the number of automorphism of a graph using the BLISS algorithm. +#' See also the BLISS homepage at . +#' If you need the automorphisms themselves, use [automorphism_group()] to obtain a compact representation of the automorphism group. #' #' @param graph The input graph, it is treated as undirected. -#' @param colors The colors of the individual vertices of the graph; only -#' vertices having the same color are allowed to match each other in an -#' automorphism. When omitted, igraph uses the `color` attribute of the -#' vertices, or, if there is no such vertex attribute, it simply assumes that -#' all vertices have the same color. Pass NULL explicitly if the graph has a -#' `color` vertex attribute but you do not want to use it. +#' @param colors The colors of the individual vertices of the graph; +#' only vertices having the same color are allowed to match each other in an automorphism. +#' When omitted, igraph uses the `color` attribute of the vertices, or, if there is no such vertex attribute, +#' it simply assumes that all vertices have the same color. +#' Pass NULL explicitly if the graph has a `color` vertex attribute but you do not want to use it. #' @inheritParams rlang::args_dots_empty -#' @param sh The splitting heuristics for the BLISS algorithm. Possible values -#' are: -#' \sQuote{`f`}: +#' @param sh The splitting heuristics for the BLISS algorithm. +#' Possible values are: \sQuote{`f`}: #' first non-singleton cell, #' \sQuote{`fl`}: #' first largest non-singleton cell, @@ -1620,9 +1575,7 @@ graph.isomorphic <- function(graph1, graph2) { #' @author Tommi Junttila () for BLISS #' and Gabor Csardi \email{csardi.gabor@@gmail.com} for the igraph glue code #' and this manual page. -#' @seealso [canonical_permutation()], [permute()], -#' and [automorphism_group()] for a compact representation of all -#' automorphisms +#' @seealso [canonical_permutation()], [permute()], and [automorphism_group()] for a compact representation of all automorphisms #' @references Tommi Junttila and Petteri Kaski: Engineering an Efficient #' Canonical Labeling Tool for Large and Sparse Graphs, *Proceedings of #' the Ninth Workshop on Algorithm Engineering and Experiments and the Fourth @@ -1694,29 +1647,23 @@ count_automorphisms <- function( #' #' Compute the generating set of the automorphism group of a graph. #' -#' An automorphism of a graph is a permutation of its vertices which brings the -#' graph into itself. The automorphisms of a graph form a group and there exists -#' a subset of this group (i.e. a set of permutations) such that every other -#' permutation can be expressed as a combination of these permutations. These -#' permutations are called the generating set of the automorphism group. +#' An automorphism of a graph is a permutation of its vertices which brings the graph into itself. +#' The automorphisms of a graph form a group and there exists a subset of this group (i.e. a set of permutations) such that every other permutation can be expressed as a combination of these permutations. +#' These permutations are called the generating set of the automorphism group. #' -#' This function calculates a possible generating set of the automorphism of -#' a graph using the BLISS algorithm. See also the BLISS homepage at -#' . The calculated -#' generating set is not necessarily minimal, and it may depend on the splitting -#' heuristics used by BLISS. +#' This function calculates a possible generating set of the automorphism of a graph using the BLISS algorithm. +#' See also the BLISS homepage at . +#' The calculated generating set is not necessarily minimal, and it may depend on the splitting heuristics used by BLISS. #' #' @param graph The input graph, it is treated as undirected. -#' @param colors The colors of the individual vertices of the graph; only -#' vertices having the same color are allowed to match each other in an -#' automorphism. When omitted, igraph uses the `color` attribute of the -#' vertices, or, if there is no such vertex attribute, it simply assumes that -#' all vertices have the same color. Pass NULL explicitly if the graph has a -#' `color` vertex attribute but you do not want to use it. +#' @param colors The colors of the individual vertices of the graph; +#' only vertices having the same color are allowed to match each other in an automorphism. +#' When omitted, igraph uses the `color` attribute of the vertices, or, if there is no such vertex attribute, +#' it simply assumes that all vertices have the same color. +#' Pass NULL explicitly if the graph has a `color` vertex attribute but you do not want to use it. #' @inheritParams rlang::args_dots_empty -#' @param sh The splitting heuristics for the BLISS algorithm. Possible values -#' are: -#' \sQuote{`f`}: +#' @param sh The splitting heuristics for the BLISS algorithm. +#' Possible values are: \sQuote{`f`}: #' first non-singleton cell, #' \sQuote{`fl`}: #' first largest non-singleton cell, @@ -1730,10 +1677,9 @@ count_automorphisms <- function( #' non-trivially connected non-singleton cell, #' \sQuote{`fsm`}: #' first smallest maximally non-trivially connected non-singleton cell. -#' @param details Specifies whether to provide additional details about the -#' BLISS internals in the result. -#' @return When `details` is `FALSE`, a list of vertex permutations -#' that form a generating set of the automorphism group of the input graph. +#' @param details Specifies whether to provide additional details about the BLISS internals in the result. +#' @return When `details` is `FALSE`, +#' a list of vertex permutations that form a generating set of the automorphism group of the input graph. #' When `details` is `TRUE`, a named list with two members: #' \describe{ #' \item{generators}{ @@ -1820,16 +1766,12 @@ automorphism_group <- function( #' `r lifecycle::badge("experimental")` #' #' Computes the transitive closure of a graph. -#' The resulting graph will have an edge from vertex \eqn{i} to vertex \eqn{j} -#' if \eqn{j} is reachable from \eqn{i} in the original graph. -#' -#' The transitive closure of a graph is a new graph where there is an edge -#' between any two vertices if there is a path between them in the original -#' graph. -#' For directed graphs, an edge from \eqn{i} to \eqn{j} is added if there is -#' a directed path from \eqn{i} to \eqn{j}. -#' For undirected graphs, this is equivalent to connecting all vertices that -#' are in the same connected component. +#' The resulting graph will have an edge from vertex \eqn{i} to vertex \eqn{j} if \eqn{j} is reachable from \eqn{i} in the original graph. +#' +#' The transitive closure of a graph is a new graph where there is an edge between any two vertices +#' if there is a path between them in the original graph. +#' For directed graphs, an edge from \eqn{i} to \eqn{j} is added if there is a directed path from \eqn{i} to \eqn{j}. +#' For undirected graphs, this is equivalent to connecting all vertices that are in the same connected component. #' #' @param graph The input graph. #' It can be directed or undirected. diff --git a/R/trees.R b/R/trees.R index 1041e5836c6..fbe95466d5a 100644 --- a/R/trees.R +++ b/R/trees.R @@ -1,28 +1,22 @@ #' Decide whether a graph is a tree. #' -#' `is_tree()` decides whether a graph is a tree, and optionally returns a -#' possible root vertex if the graph is a tree. +#' `is_tree()` decides whether a graph is a tree, and optionally returns a possible root vertex if the graph is a tree. #' #' An undirected graph is a tree if it is connected and has no cycles. -#' In the directed case, a possible additional requirement is that all edges -#' are oriented away from a root (out-tree or arborescence) or all edges are -#' oriented towards a root (in-tree or anti-arborescence). This test can be -#' controlled using the mode parameter. +#' In the directed case, +#' a possible additional requirement is that all edges are oriented away from a root (out-tree or arborescence) or all edges are oriented towards a root (in-tree or anti-arborescence). +#' This test can be controlled using the mode parameter. #' -#' By convention, the null graph (i.e. the graph with no vertices) is considered -#' not to be a tree. +#' By convention, the null graph (i.e. the graph with no vertices) is considered not to be a tree. #' #' @param graph An igraph graph object #' @inheritParams rlang::args_dots_empty #' @param mode Whether to consider edge directions in a directed graph. -#' \sQuote{all} ignores edge directions; \sQuote{out} requires edges to be -#' oriented outwards from the root, \sQuote{in} requires edges to be oriented -#' towards the root. -#' @param details Whether to return only whether the graph is a tree (`FALSE`) -#' or also a possible root (`TRUE`) -#' @return When `details` is `FALSE`, a logical value that indicates -#' whether the graph is a tree. When `details` is `TRUE`, a named -#' list with two entries: +#' \sQuote{all} ignores edge directions; \sQuote{out} requires edges to be oriented outwards from the root, +#' \sQuote{in} requires edges to be oriented towards the root. +#' @param details Whether to return only whether the graph is a tree (`FALSE`) or also a possible root (`TRUE`) +#' @return When `details` is `FALSE`, a logical value that indicates whether the graph is a tree. +#' When `details` is `TRUE`, a named list with two entries: #' \describe{ #' \item{res}{ #' Logical value that indicates whether the graph is a tree. @@ -98,29 +92,23 @@ is_tree <- function( #' Decide whether a graph is a forest. #' -#' `is_forest()` decides whether a graph is a forest, and optionally returns a -#' set of possible root vertices for its components. +#' `is_forest()` decides whether a graph is a forest, and optionally returns a set of possible root vertices for its components. #' -#' An undirected graph is a forest if it has no cycles. In the directed case, -#' a possible additional requirement is that edges in each tree are oriented -#' away from the root (out-trees or arborescences) or all edges are oriented -#' towards the root (in-trees or anti-arborescences). This test can be -#' controlled using the mode parameter. +#' An undirected graph is a forest if it has no cycles. +#' In the directed case, +#' a possible additional requirement is that edges in each tree are oriented away from the root (out-trees or arborescences) or all edges are oriented towards the root (in-trees or anti-arborescences). +#' This test can be controlled using the mode parameter. #' -#' By convention, the null graph (i.e. the graph with no vertices) is considered -#' to be a forest. +#' By convention, the null graph (i.e. the graph with no vertices) is considered to be a forest. #' #' @param graph An igraph graph object #' @inheritParams rlang::args_dots_empty #' @param mode Whether to consider edge directions in a directed graph. -#' \sQuote{all} ignores edge directions; \sQuote{out} requires edges to be -#' oriented outwards from the root, \sQuote{in} requires edges to be oriented -#' towards the root. -#' @param details Whether to return only whether the graph is a tree (`FALSE`) -#' or also a possible root (`TRUE`) -#' @return When `details` is `FALSE`, a logical value that indicates -#' whether the graph is a tree. When `details` is `TRUE`, a named -#' list with two entries: +#' \sQuote{all} ignores edge directions; \sQuote{out} requires edges to be oriented outwards from the root, +#' \sQuote{in} requires edges to be oriented towards the root. +#' @param details Whether to return only whether the graph is a tree (`FALSE`) or also a possible root (`TRUE`) +#' @return When `details` is `FALSE`, a logical value that indicates whether the graph is a tree. +#' When `details` is `TRUE`, a named list with two entries: #' \describe{ #' \item{res}{ #' Logical value that indicates whether the graph is a tree. @@ -193,18 +181,15 @@ is_forest <- function( #' #' `to_prufer()` converts a tree graph into its Prüfer sequence. #' -#' The Prüfer sequence of a tree graph with n labeled vertices is a sequence of -#' n-2 numbers, constructed as follows. If the graph has more than two vertices, -#' find a vertex with degree one, remove it from the tree and add the label of -#' the vertex that it was connected to to the sequence. Repeat until there are -#' only two vertices in the remaining graph. +#' The Prüfer sequence of a tree graph with n labeled vertices is a sequence of n-2 numbers, constructed as follows. +#' If the graph has more than two vertices, find a vertex with degree one, +#' remove it from the tree and add the label of the vertex that it was connected to to the sequence. +#' Repeat until there are only two vertices in the remaining graph. #' #' @param graph The graph to convert to a Prüfer sequence -#' @return The Prüfer sequence of the graph, represented as a numeric vector of -#' vertex IDs in the sequence. +#' @return The Prüfer sequence of the graph, represented as a numeric vector of vertex IDs in the sequence. #' -#' @seealso [make_from_prufer()] to construct a graph from its -#' Prüfer sequence +#' @seealso [make_from_prufer()] to construct a graph from its Prüfer sequence #' @keywords graphs #' @examples #' @@ -221,20 +206,17 @@ to_prufer <- function(graph) { #' Samples from the spanning trees of a graph randomly and uniformly #' -#' `sample_spanning_tree()` picks a spanning tree of an undirected graph -#' randomly and uniformly, using loop-erased random walks. +#' `sample_spanning_tree()` picks a spanning tree of an undirected graph randomly and uniformly, using loop-erased random walks. #' -#' @param graph The input graph to sample from. Edge directions are ignored if -#' the graph is directed. +#' @param graph The input graph to sample from. +#' Edge directions are ignored if the graph is directed. #' @inheritParams rlang::args_dots_empty -#' @param vid When the graph is disconnected, this argument specifies how to -#' handle the situation. When the argument is zero (the default), the sampling -#' will be performed component-wise, and the result will be a spanning forest. -#' When the argument contains a vertex ID, only the component containing the -#' given vertex will be processed, and the result will be a spanning tree of the -#' component of the graph. -#' @return An edge sequence containing the edges of the spanning tree. Use -#' [subgraph_from_edges()] to extract the corresponding subgraph. +#' @param vid When the graph is disconnected, this argument specifies how to handle the situation. +#' When the argument is zero (the default), the sampling will be performed component-wise, and the result will be a spanning forest. +#' When the argument contains a vertex ID, only the component containing the given vertex will be processed, +#' and the result will be a spanning tree of the component of the graph. +#' @return An edge sequence containing the edges of the spanning tree. +#' Use [subgraph_from_edges()] to extract the corresponding subgraph. #' #' @keywords graph #' @seealso [subgraph_from_edges()] to extract the tree itself diff --git a/R/triangles.R b/R/triangles.R index 5a0e5ebb9d9..665426e745e 100644 --- a/R/triangles.R +++ b/R/triangles.R @@ -3,8 +3,7 @@ #' @description #' `r lifecycle::badge("deprecated")` #' -#' `adjacent.triangles()` was renamed to [count_triangles()] to create a more -#' consistent API. +#' `adjacent.triangles()` was renamed to [count_triangles()] to create a more consistent API. #' @inheritParams count_triangles #' @keywords internal #' @export @@ -43,26 +42,23 @@ adjacent.triangles <- function(graph, vids = V(graph)) { #' Find triangles in graphs #' -#' Count how many triangles a vertex is part of, in a graph, or just list the -#' triangles of a graph. +#' Count how many triangles a vertex is part of, in a graph, or just list the triangles of a graph. #' -#' `triangles()` lists all triangles of a graph. For efficiency, all -#' triangles are returned in a single vector. The first three vertices belong -#' to the first triangle, etc. +#' `triangles()` lists all triangles of a graph. +#' For efficiency, all triangles are returned in a single vector. +#' The first three vertices belong to the first triangle, etc. #' #' `count_triangles()` counts how many triangles a vertex is part of. #' #' @aliases triangles -#' @param graph The input graph. It might be directed, but edge directions are -#' ignored. -#' @param vids The vertices to query. This might be a vector of numeric IDs, -#' or a character vector of symbolic vertex names for named graphs. The -#' default `NULL` selects all vertices. -#' @return For `triangles()` a numeric vector of vertex IDs, the first three -#' vertices belong to the first triangle found, etc. +#' @param graph The input graph. +#' It might be directed, but edge directions are ignored. +#' @param vids The vertices to query. +#' This might be a vector of numeric IDs, or a character vector of symbolic vertex names for named graphs. +#' The default `NULL` selects all vertices. +#' @return For `triangles()` a numeric vector of vertex IDs, the first three vertices belong to the first triangle found, etc. #' -#' For `count_triangles()` a numeric vector, the number of triangles for all -#' vertices queried. +#' For `count_triangles()` a numeric vector, the number of triangles for all vertices queried. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @seealso [transitivity()] #' @keywords graphs diff --git a/R/utils-s3.R b/R/utils-s3.R index 0958f90863a..33cb67bfca9 100644 --- a/R/utils-s3.R +++ b/R/utils-s3.R @@ -63,10 +63,8 @@ s3_register <- function(generic, class, method = NULL) { } # Avoid registration failures during loading (pkgload or regular). - # Check that environment is locked because the registering package - # might be a dependency of the package that exports the generic. In - # that case, the exports (and the generic) might not be populated - # yet (#1225). + # Check that environment is locked because the registering package might be a dependency of the package that exports the generic. + # In that case, the exports (and the generic) might not be populated yet (#1225). if (isNamespaceLoaded(package) && is_sealed(package)) { register() } diff --git a/R/utils.R b/R/utils.R index d172590cc0d..6e338e52e77 100644 --- a/R/utils.R +++ b/R/utils.R @@ -98,10 +98,8 @@ modify_list <- function(x, y) { #' Test function to verify error formatting with file and line information #' #' @description -#' This is a test function that throws an error from C code with file and line -#' information. -#' The error message should include the source file and line number where the -#' error occurred. +#' This is a test function that throws an error from C code with file and line information. +#' The error message should include the source file and line number where the error occurred. #' #' @return This function never returns; it always throws an error. #' @keywords internal diff --git a/R/versions.R b/R/versions.R index ab70f20b1ac..5d1ac91b400 100644 --- a/R/versions.R +++ b/R/versions.R @@ -31,19 +31,16 @@ pkg_graph_version <- ver_1_5_0 #' igraph data structure versions #' -#' igraph's internal data representation changes sometimes between -#' versions. This means that it is not always possible to use igraph objects -#' that were created (and possibly saved to a file) with an older -#' igraph version. +#' igraph's internal data representation changes sometimes between versions. +#' This means that it is not always possible to use igraph objects that were created (and possibly saved to a file) with an older igraph version. #' #' `graph_version()` queries the current data format, #' or the data format of a possibly older igraph graph. #' -#' [upgrade_graph()] can convert an older data format -#' to the current one. +#' [upgrade_graph()] can convert an older data format to the current one. #' -#' @param graph The input graph. If it is missing, then -#' the version number of the current data format is returned. +#' @param graph The input graph. +#' If it is missing, then the version number of the current data format is returned. #' @return An integer scalar. #' #' @seealso upgrade_graph to convert the data format of a graph. @@ -62,22 +59,18 @@ graph_version <- function(graph) { #' igraph data structure versions #' -#' igraph's internal data representation changes sometimes between -#' versions. This means that it is not possible to use igraph objects -#' that were created (and possibly saved to a file) with an older -#' igraph version. +#' igraph's internal data representation changes sometimes between versions. +#' This means that it is not possible to use igraph objects that were created (and possibly saved to a file) with an older igraph version. #' #' [graph_version()] queries the current data format, #' or the data format of a possibly older igraph graph. #' -#' `upgrade_graph()` can convert an older data format -#' to the current one. +#' `upgrade_graph()` can convert an older data format to the current one. #' #' @param graph The input graph. #' @return The graph in the current format. #' -#' @seealso graph_version to check the current data format version -#' or the version of a graph. +#' @seealso graph_version to check the current data format version or the version of a graph. #' @family versions #' @export upgrade_graph <- function(graph) { @@ -184,8 +177,7 @@ clear_native_ptr <- function(g) { #' @description #' `r lifecycle::badge("deprecated")` #' -#' `igraph.version()` was renamed to [igraph_version()] to create a more -#' consistent API. +#' `igraph.version()` was renamed to [igraph_version()] to create a more consistent API. #' #' @keywords internal #' @export @@ -203,8 +195,7 @@ igraph.version <- function() { #' Returns the R package version, #' prints the R package version and C library version. #' -#' @return A character scalar, the igraph version string, with an attribute -#' `"c_version"` giving the C library version string. +#' @return A character scalar, the igraph version string, with an attribute `"c_version"` giving the C library version string. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @keywords graphs #' @keywords internal diff --git a/README.md b/README.md index 090a2f85d1a..bbab5713db0 100644 --- a/README.md +++ b/README.md @@ -35,13 +35,12 @@ or Github, with the [pak package](https://pak.r-lib.org/): pak::pak("igraph/rigraph") ``` -When compiling from sources, make sure that you have C, C++ and Fortran -compilers, as well as development packages for `glpk` and `libxml2`. +When compiling from sources, make sure that you have C, C++ and Fortran compilers, +as well as development packages for `glpk` and `libxml2`. On Debian/Ubuntu, use `apt install libglpk-dev libxml2-dev`. On Fedora, use `yum install glpk-devel libxml2-devel`. -For installation from source on Windows, you need to have -[RTools](https://cran.r-project.org/bin/windows/Rtools/) installed. +For installation from source on Windows, you need to have [RTools](https://cran.r-project.org/bin/windows/Rtools/) installed. For versions R >= 4.0 you can install the dependencies using: ``` @@ -56,7 +55,8 @@ See the [Installation FAQ](https://r.igraph.org/articles/installation-troublesho See the [igraph package's website](https://r.igraph.org/) for the complete manual. -A good entry point is the "Get started" vignette, in [English](https://r.igraph.org/articles/igraph.html) or [Spanish](https://r.igraph.org/articles/igraph_ES.html). +A good entry point is the "Get started" vignette, +in [English](https://r.igraph.org/articles/igraph.html) or [Spanish](https://r.igraph.org/articles/igraph_ES.html). For an overview of igraph's functionality see the [reference index](https://r.igraph.org/reference/index.html). It includes [experimental functions](https://r.igraph.org/reference/index.html#experimental-functions) on which we especially welcome feedback @@ -64,8 +64,7 @@ It includes [experimental functions](https://r.igraph.org/reference/index.html#e ## Contributions -Please read our -[contribution guide](https://github.com/igraph/rigraph/blob/dev/CONTRIBUTING.md). +Please read our [contribution guide](https://github.com/igraph/rigraph/blob/dev/CONTRIBUTING.md). ## License diff --git a/man/E.Rd b/man/E.Rd index 8340cee43cc..2acb5208756 100644 --- a/man/E.Rd +++ b/man/E.Rd @@ -12,52 +12,43 @@ E(graph, ..., P = NULL, path = NULL, directed = TRUE) \item{...}{These dots are for future extensions and must be empty.} \item{P}{A list of vertices to select edges via pairs of vertices. -The first and second vertices select the first edge, the third -and fourth the second, etc.} +The first and second vertices select the first edge, the third and fourth the second, etc.} \item{path}{A list of vertices, to select edges along a path. -Note that this only works reliable for simple graphs. If the graph -has multiple edges, one of them will be chosen arbitrarily to -be included in the edge sequence.} +Note that this only works reliable for simple graphs. +If the graph has multiple edges, one of them will be chosen arbitrarily to be included in the edge sequence.} -\item{directed}{Whether to consider edge directions in the \code{P} -argument, for directed graphs.} +\item{directed}{Whether to consider edge directions in the \code{P} argument, for directed graphs.} } \value{ An edge sequence of the graph. } \description{ -An edge sequence is a vector containing numeric edge IDs, with a special -class attribute that allows custom operations: selecting subsets of -edges based on attributes, or graph structure, creating the -intersection, union of edges, etc. +An edge sequence is a vector containing numeric edge IDs, with a special class attribute that allows custom operations: +selecting subsets of edges based on attributes, or graph structure, creating the intersection, union of edges, etc. } \details{ -Edge sequences are usually used as igraph function arguments that -refer to edges of a graph. +Edge sequences are usually used as igraph function arguments that refer to edges of a graph. -An edge sequence is tied to the graph it refers to: it really denoted -the specific edges of that graph, and cannot be used together with -another graph. +An edge sequence is tied to the graph it refers to: it really denoted the specific edges of that graph, +and cannot be used together with another graph. -An edge sequence is most often created by the \code{E()} function. The -result includes edges in increasing edge ID order by default (if. none -of the \code{P} and \code{path} arguments are used). An edge -sequence can be indexed by a numeric vector, just like a regular R -vector. See links to other edge sequence operations below. +An edge sequence is most often created by the \code{E()} function. +The result includes edges in increasing edge ID order by default (if. none of the \code{P} and \code{path} arguments are used). +An edge sequence can be indexed by a numeric vector, just like a regular R vector. +See links to other edge sequence operations below. } \section{Indexing edge sequences}{ -Edge sequences mostly behave like regular vectors, but there are some -additional indexing operations that are specific for them; -e.g. selecting edges based on graph structure, or based on edge -attributes. See \code{\link{[.igraph.es}} for details. +Edge sequences mostly behave like regular vectors, but there are some additional indexing operations that are specific for them; +e.g. selecting edges based on graph structure, or based on edge attributes. +See \code{\link{[.igraph.es}} for details. } \section{Querying or setting attributes}{ -Edge sequences can be used to query or set attributes for the -edges in the sequence. See \code{\link[=$.igraph.es]{$.igraph.es()}} for details. +Edge sequences can be used to query or set attributes for the edges in the sequence. +See \code{\link[=$.igraph.es]{$.igraph.es()}} for details. } \section{Related documentation in the C library}{ diff --git a/man/V.Rd b/man/V.Rd index 968cdc0541a..27bd0d72692 100644 --- a/man/V.Rd +++ b/man/V.Rd @@ -10,45 +10,38 @@ V(graph) \item{graph}{The graph} } \value{ -A vertex sequence containing all vertices, in the order -of their numeric vertex IDs. +A vertex sequence containing all vertices, in the order of their numeric vertex IDs. } \description{ Create a vertex sequence (vs) containing all vertices of a graph. } \details{ -A vertex sequence is just what the name says it is: a sequence of -vertices. Vertex sequences are usually used as igraph function arguments -that refer to vertices of a graph. +A vertex sequence is just what the name says it is: a sequence of vertices. +Vertex sequences are usually used as igraph function arguments that refer to vertices of a graph. -A vertex sequence is tied to the graph it refers to: it really denoted -the specific vertices of that graph, and cannot be used together with -another graph. +A vertex sequence is tied to the graph it refers to: it really denoted the specific vertices of that graph, +and cannot be used together with another graph. -At the implementation level, a vertex sequence is simply a vector -containing numeric vertex IDs, but it has a special class attribute -which makes it possible to perform graph specific operations on it, like -selecting a subset of the vertices based on graph structure, or vertex -attributes. +At the implementation level, a vertex sequence is simply a vector containing numeric vertex IDs, +but it has a special class attribute which makes it possible to perform graph specific operations on it, +like selecting a subset of the vertices based on graph structure, or vertex attributes. -A vertex sequence is most often created by the \code{V()} function. The -result of this includes all vertices in increasing vertex ID order. A -vertex sequence can be indexed by a numeric vector, just like a regular -R vector. See \code{\link{[.igraph.vs}} and additional links to other -vertex sequence operations below. +A vertex sequence is most often created by the \code{V()} function. +The result of this includes all vertices in increasing vertex ID order. +A vertex sequence can be indexed by a numeric vector, just like a regular R vector. +See \code{\link{[.igraph.vs}} and additional links to other vertex sequence operations below. } \section{Indexing vertex sequences}{ -Vertex sequences mostly behave like regular vectors, but there are some -additional indexing operations that are specific for them; -e.g. selecting vertices based on graph structure, or based on vertex -attributes. See \code{\link{[.igraph.vs}} for details. +Vertex sequences mostly behave like regular vectors, but there are some additional indexing operations that are specific for them; +e.g. selecting vertices based on graph structure, or based on vertex attributes. +See \code{\link{[.igraph.vs}} for details. } \section{Querying or setting attributes}{ -Vertex sequences can be used to query or set attributes for the -vertices in the sequence. See \code{\link[=$.igraph.vs]{$.igraph.vs()}} for details. +Vertex sequences can be used to query or set attributes for the vertices in the sequence. +See \code{\link[=$.igraph.vs]{$.igraph.vs()}} for details. } \section{Related documentation in the C library}{ diff --git a/man/aaa-igraph-package.Rd b/man/aaa-igraph-package.Rd index 95fd92d9907..7a98cadf4c9 100644 --- a/man/aaa-igraph-package.Rd +++ b/man/aaa-igraph-package.Rd @@ -10,39 +10,30 @@ igraph is a library and R package for network analysis. } \section{Introduction}{ -The main goals of the igraph library is to provide a set of data types -and functions for 1) pain-free implementation of graph algorithms, 2) -fast handling of large graphs, with millions of vertices and edges, 3) -allowing rapid prototyping via high level languages like R. +The main goals of the igraph library is to provide a set of data types and functions for 1) pain-free implementation of graph algorithms, 2) fast handling of large graphs, +with millions of vertices and edges, 3) allowing rapid prototyping via high level languages like R. } \section{igraph graphs}{ -igraph graphs have a class \sQuote{\code{igraph}}. They are printed to -the screen in a special format, here is an example, a ring graph +igraph graphs have a class \sQuote{\code{igraph}}. +They are printed to the screen in a special format, here is an example, a ring graph created using \code{\link[=make_ring]{make_ring()}}: \preformatted{ IGRAPH U--- 10 10 -- Ring graph + attr: name (g/c), mutual (g/x), circular (g/x) } -\sQuote{\code{IGRAPH}} denotes that this is an igraph graph. Then -come four bits that denote the kind of the graph: the first is -\sQuote{\code{U}} for undirected and \sQuote{\code{D}} for directed -graphs. The second is \sQuote{\code{N}} for named graph (i.e. if the -graph has the \sQuote{\code{name}} vertex attribute set). The third is -\sQuote{\code{W}} for weighted graphs (i.e. if the -\sQuote{\code{weight}} edge attribute is set). The fourth is -\sQuote{\code{B}} for bipartite graphs (i.e. if the -\sQuote{\code{type}} vertex attribute is set). - -Then come two numbers, the number of vertices and the number of edges -in the graph, and after a double dash, the name of the graph (the -\sQuote{\code{name}} graph attribute) is printed if present. The -second line is optional and it contains all the attributes of the -graph. This graph has a \sQuote{\code{name}} graph attribute, of type -character, and two other graph attributes called -\sQuote{\code{mutual}} and \sQuote{\code{circular}}, of a complex -type. A complex type is simply anything that is not numeric or -character. See the documentation of \code{\link[=print.igraph]{print.igraph()}} for -details. +\sQuote{\code{IGRAPH}} denotes that this is an igraph graph. +Then come four bits that denote the kind of the graph: the first is \sQuote{\code{U}} for undirected and \sQuote{\code{D}} for directed graphs. +The second is \sQuote{\code{N}} for named graph (i.e. if the graph has the \sQuote{\code{name}} vertex attribute set). +The third is \sQuote{\code{W}} for weighted graphs (i.e. if the \sQuote{\code{weight}} edge attribute is set). +The fourth is \sQuote{\code{B}} for bipartite graphs (i.e. if the \sQuote{\code{type}} vertex attribute is set). + +Then come two numbers, the number of vertices and the number of edges in the graph, and after a double dash, +the name of the graph (the \sQuote{\code{name}} graph attribute) is printed if present. +The second line is optional and it contains all the attributes of the graph. +This graph has a \sQuote{\code{name}} graph attribute, of type character, +and two other graph attributes called \sQuote{\code{mutual}} and \sQuote{\code{circular}}, of a complex type. +A complex type is simply anything that is not numeric or character. +See the documentation of \code{\link[=print.igraph]{print.igraph()}} for details. If you want to see the edges of the graph as well, then use the \code{\link[=print_all]{print_all()}} function: \preformatted{ > print_all(g) @@ -54,117 +45,95 @@ If you want to see the edges of the graph as well, then use the \section{Creating graphs}{ -There are many functions in igraph for creating graphs, both -deterministic and stochastic; stochastic graph constructors are called -\sQuote{games}. +There are many functions in igraph for creating graphs, both deterministic and stochastic; +stochastic graph constructors are called \sQuote{games}. -To create small graphs with a given structure probably the -\code{\link[=graph_from_literal]{graph_from_literal()}} function is easiest. It uses R's formula -interface, its manual page contains many examples. Another option is -\code{\link[=make_graph]{make_graph()}}, which takes numeric vertex IDs directly. -\code{\link[=graph_from_atlas]{graph_from_atlas()}} creates graph from the Graph Atlas, -\code{\link[=make_graph]{make_graph()}} can create some special graphs. +To create small graphs with a given structure probably the \code{\link[=graph_from_literal]{graph_from_literal()}} function is easiest. +It uses R's formula interface, its manual page contains many examples. +Another option is \code{\link[=make_graph]{make_graph()}}, which takes numeric vertex IDs directly. +\code{\link[=graph_from_atlas]{graph_from_atlas()}} creates graph from the Graph Atlas, \code{\link[=make_graph]{make_graph()}} can create some special graphs. To create graphs from field data, \code{\link[=graph_from_edgelist]{graph_from_edgelist()}}, -\code{\link[=graph_from_data_frame]{graph_from_data_frame()}} and \code{\link[=graph_from_adjacency_matrix]{graph_from_adjacency_matrix()}} are -probably the best choices. - -The igraph package includes some classic random graphs like the -Erdős-Rényi GNP and GNM graphs (\code{\link[=sample_gnp]{sample_gnp()}}, \code{\link[=sample_gnm]{sample_gnm()}}) and -some recent popular models, like preferential attachment -(\code{\link[=sample_pa]{sample_pa()}}) and the small-world model -(\code{\link[=sample_smallworld]{sample_smallworld()}}). +\code{\link[=graph_from_data_frame]{graph_from_data_frame()}} and \code{\link[=graph_from_adjacency_matrix]{graph_from_adjacency_matrix()}} are probably the best choices. + +The igraph package includes some classic random graphs like the Erdős-Rényi GNP and GNM graphs (\code{\link[=sample_gnp]{sample_gnp()}}, \code{\link[=sample_gnm]{sample_gnm()}}) and some recent popular models, +like preferential attachment (\code{\link[=sample_pa]{sample_pa()}}) and the small-world model (\code{\link[=sample_smallworld]{sample_smallworld()}}). } \section{Vertex and edge IDs}{ -Vertices and edges have numerical vertex IDs in igraph. Vertex IDs are -always consecutive and they start with one. I.e. for a graph with -\eqn{n} vertices the vertex IDs are between \eqn{1} and -\eqn{n}. If some operation changes the number of vertices in the -graphs, e.g. a subgraph is created via \code{\link[=induced_subgraph]{induced_subgraph()}}, then -the vertices are renumbered to satisfy this criteria. - -The same is true for the edges as well, edge IDs are always between -one and \eqn{m}, the total number of edges in the graph. - -It is often desirable to follow vertices along a number of graph -operations, and vertex IDs don't allow this because of the -renumbering. The solution is to assign attributes to the -vertices. These are kept by all operations, if possible. See more -about attributes in the next section. +Vertices and edges have numerical vertex IDs in igraph. +Vertex IDs are always consecutive and they start with one. +I.e. for a graph with \eqn{n} vertices the vertex IDs are between \eqn{1} and \eqn{n}. +If some operation changes the number of vertices in the graphs, e.g. a subgraph is created via \code{\link[=induced_subgraph]{induced_subgraph()}}, +then the vertices are renumbered to satisfy this criteria. + +The same is true for the edges as well, edge IDs are always between one and \eqn{m}, the total number of edges in the graph. + +It is often desirable to follow vertices along a number of graph operations, +and vertex IDs don't allow this because of the renumbering. +The solution is to assign attributes to the vertices. +These are kept by all operations, if possible. +See more about attributes in the next section. } \section{Attributes}{ -In igraph it is possible to assign attributes to the vertices or edges -of a graph, or to the graph itself. igraph provides flexible -constructs for selecting a set of vertices or edges based on their -attribute values, see \code{\link[=vertex_attr]{vertex_attr()}}, -\code{\link[=V]{V()}} and \code{\link[=E]{E()}} for details. - -Some vertex/edge/graph attributes are treated specially. One of them -is the \sQuote{name} attribute. This is used for printing the graph -instead of the numerical IDs, if it exists. Vertex names can also be -used to specify a vector or set of vertices, in all igraph -functions. E.g. \code{\link[=degree]{degree()}} has a \code{v} argument -that gives the vertices for which the degree is calculated. This -argument can be given as a character vector of vertex names. - -Edges can also have a \sQuote{name} attribute, and this is treated -specially as well. Just like for vertices, edges can also be selected -based on their names, e.g. in the \code{\link[=delete_edges]{delete_edges()}} and -other functions. +In igraph it is possible to assign attributes to the vertices or edges of a graph, +or to the graph itself. igraph provides flexible constructs for selecting a set of vertices or edges based on their attribute values, +see \code{\link[=vertex_attr]{vertex_attr()}}, \code{\link[=V]{V()}} and \code{\link[=E]{E()}} for details. + +Some vertex/edge/graph attributes are treated specially. +One of them is the \sQuote{name} attribute. +This is used for printing the graph instead of the numerical IDs, if it exists. +Vertex names can also be used to specify a vector or set of vertices, in all igraph functions. +E.g. \code{\link[=degree]{degree()}} has a \code{v} argument that gives the vertices for which the degree is calculated. +This argument can be given as a character vector of vertex names. + +Edges can also have a \sQuote{name} attribute, and this is treated specially as well. +Just like for vertices, edges can also be selected based on their names, e.g. in the \code{\link[=delete_edges]{delete_edges()}} and other functions. We note here, that vertex names can also be used to select edges. -The form \sQuote{\code{from|to}}, where \sQuote{\code{from}} and -\sQuote{\code{to}} are vertex names, select a single, possibly -directed, edge going from \sQuote{\code{from}} to -\sQuote{\code{to}}. The two forms can also be mixed in the same edge -selector. - -Other attributes define visualization parameters, see -\link{igraph.plotting} for details. - -Attribute values can be set to any R object, but note that storing the -graph in some file formats might result the loss of complex attribute -values. All attribute values are preserved if you use -\code{\link[base:save]{base::save()}} and \code{\link[base:load]{base::load()}} to store/retrieve your -graphs. +The form \sQuote{\code{from|to}}, where \sQuote{\code{from}} and \sQuote{\code{to}} are vertex names, select a single, possibly directed, +edge going from \sQuote{\code{from}} to \sQuote{\code{to}}. +The two forms can also be mixed in the same edge selector. + +Other attributes define visualization parameters, see \link{igraph.plotting} for details. + +Attribute values can be set to any R object, +but note that storing the graph in some file formats might result the loss of complex attribute values. +All attribute values are preserved if you use \code{\link[base:save]{base::save()}} and \code{\link[base:load]{base::load()}} to store/retrieve your graphs. } \section{Visualization}{ -igraph provides three different ways for visualization. The first is -the \code{\link[=plot.igraph]{plot.igraph()}} function. (Actually you don't need to -write \code{plot.igraph()}, \code{\link[=plot]{plot()}} is enough. This function uses -regular R graphics and can be used with any R device. +igraph provides three different ways for visualization. +The first is the \code{\link[=plot.igraph]{plot.igraph()}} function. +(Actually you don't need to write \code{plot.igraph()}, \code{\link[=plot]{plot()}} is enough. +This function uses regular R graphics and can be used with any R device. -The second function is \code{\link[=tkplot]{tkplot()}}, which uses a Tk GUI for -basic interactive graph manipulation. (Tk is quite resource hungry, so -don't try this for very large graphs.) +The second function is \code{\link[=tkplot]{tkplot()}}, which uses a Tk GUI for basic interactive graph manipulation. +(Tk is quite resource hungry, so don't try this for very large graphs.) -The third way requires the \code{rgl} package and uses OpenGL. See the -\code{\link[=rglplot]{rglplot()}} function for the details. +The third way requires the \code{rgl} package and uses OpenGL. +See the \code{\link[=rglplot]{rglplot()}} function for the details. -Make sure you read \link{igraph.plotting} before you start -plotting your graphs. +Make sure you read \link{igraph.plotting} before you start plotting your graphs. } \section{File formats}{ -igraph can handle various graph file formats, usually both for reading -and writing. We suggest that you use the GraphML file format for your -graphs, except if the graphs are too big. For big graphs a simpler -format is recommended. See \code{\link[=read_graph]{read_graph()}} and -\code{\link[=write_graph]{write_graph()}} for details. +igraph can handle various graph file formats, usually both for reading and writing. +We suggest that you use the GraphML file format for your graphs, except if the graphs are too big. +For big graphs a simpler format is recommended. +See \code{\link[=read_graph]{read_graph()}} and \code{\link[=write_graph]{write_graph()}} for details. } \section{Further information}{ The igraph homepage is at \url{https://igraph.org}. -See especially the documentation section. Join the discussion forum at -\url{https://igraph.discourse.group} if you have questions or comments. +See especially the documentation section. +Join the discussion forum at \url{https://igraph.discourse.group} if you have questions or comments. } \seealso{ diff --git a/man/add.edges.Rd b/man/add.edges.Rd index 0c2fc925a37..75739d4b03c 100644 --- a/man/add.edges.Rd +++ b/man/add.edges.Rd @@ -9,22 +9,18 @@ add.edges(graph, edges, ..., attr = list()) \arguments{ \item{graph}{The input graph} -\item{edges}{The edges to add, a vertex sequence with even number -of vertices.} +\item{edges}{The edges to add, a vertex sequence with even number of vertices.} -\item{...}{Additional arguments, they must be named, -and they will be added as edge attributes, for the newly added -edges. See also details below.} +\item{...}{Additional arguments, they must be named, and they will be added as edge attributes, for the newly added edges. +See also details below.} -\item{attr}{A named list, its elements will be added -as edge attributes, for the newly added edges. See also details -below.} +\item{attr}{A named list, its elements will be added as edge attributes, for the newly added edges. +See also details below.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{add.edges()} was renamed to \code{\link[=add_edges]{add_edges()}} to create a more -consistent API. +\code{add.edges()} was renamed to \code{\link[=add_edges]{add_edges()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/add.vertex.shape.Rd b/man/add.vertex.shape.Rd index 89adafd6ef3..61b835aa4ad 100644 --- a/man/add.vertex.shape.Rd +++ b/man/add.vertex.shape.Rd @@ -12,28 +12,24 @@ add.vertex.shape( ) } \arguments{ -\item{shape}{Character scalar, name of a vertex shape. If it is -\code{NULL} for \code{shapes()}, then the names of all defined -vertex shapes are returned.} +\item{shape}{Character scalar, name of a vertex shape. +If it is \code{NULL} for \code{shapes()}, then the names of all defined vertex shapes are returned.} -\item{clip}{An R function object, the clipping function. The default -\code{NULL} uses \code{shape_noclip}.} +\item{clip}{An R function object, the clipping function. +The default \code{NULL} uses \code{shape_noclip}.} -\item{plot}{An R function object, the plotting function. The default -\code{NULL} uses \code{shape_noplot}.} +\item{plot}{An R function object, the plotting function. +The default \code{NULL} uses \code{shape_noplot}.} -\item{parameters}{Named list, additional plot/vertex/edge -parameters. The element named define the new parameters, and the -elements themselves define their default values. -Vertex parameters should have a prefix -\sQuote{\code{vertex.}}, edge parameters a prefix -\sQuote{\code{edge.}}. Other general plotting parameters should have -a prefix \sQuote{\code{plot.}}. See Details below.} +\item{parameters}{Named list, additional plot/vertex/edge parameters. +The element named define the new parameters, and the elements themselves define their default values. +Vertex parameters should have a prefix \sQuote{\code{vertex.}}, edge parameters a prefix \sQuote{\code{edge.}}. +Other general plotting parameters should have a prefix \sQuote{\code{plot.}}. +See Details below.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{add.vertex.shape()} was renamed to \code{\link[=add_shape]{add_shape()}} to create a more -consistent API. +\code{add.vertex.shape()} was renamed to \code{\link[=add_shape]{add_shape()}} to create a more consistent API. } \keyword{internal} diff --git a/man/add.vertices.Rd b/man/add.vertices.Rd index 67cf024dce0..ac6da62ff3a 100644 --- a/man/add.vertices.Rd +++ b/man/add.vertices.Rd @@ -11,19 +11,16 @@ add.vertices(graph, nv, ..., attr = list()) \item{nv}{The number of vertices to add.} -\item{...}{Additional arguments, they must be named, -and they will be added as vertex attributes, for the newly added -vertices. See also details below.} +\item{...}{Additional arguments, they must be named, and they will be added as vertex attributes, for the newly added vertices. +See also details below.} -\item{attr}{A named list, its elements will be added -as vertex attributes, for the newly added vertices. See also details -below.} +\item{attr}{A named list, its elements will be added as vertex attributes, for the newly added vertices. +See also details below.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{add.vertices()} was renamed to \code{\link[=add_vertices]{add_vertices()}} to create a more -consistent API. +\code{add.vertices()} was renamed to \code{\link[=add_vertices]{add_vertices()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_add_vertices}{\code{add_vertices()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/add_edges.Rd b/man/add_edges.Rd index 01859f4dde3..b4cee061ede 100644 --- a/man/add_edges.Rd +++ b/man/add_edges.Rd @@ -9,25 +9,20 @@ add_edges(graph, edges, ..., attr = list()) \arguments{ \item{graph}{The input graph} -\item{edges}{The edges to add, a vertex sequence with even number -of vertices.} +\item{edges}{The edges to add, a vertex sequence with even number of vertices.} -\item{...}{Additional arguments, they must be named, -and they will be added as edge attributes, for the newly added -edges. See also details below.} +\item{...}{Additional arguments, they must be named, and they will be added as edge attributes, for the newly added edges. +See also details below.} -\item{attr}{A named list, its elements will be added -as edge attributes, for the newly added edges. See also details -below.} +\item{attr}{A named list, its elements will be added as edge attributes, for the newly added edges. +See also details below.} } \value{ The graph, with the edges (and attributes) added. } \description{ -The new edges are given as a vertex sequence, e.g. internal -numeric vertex IDs, or vertex names. The first edge points from -\code{edges[1]} to \code{edges[2]}, the second from \code{edges[3]} -to \code{edges[4]}, etc. +The new edges are given as a vertex sequence, e.g. internal numeric vertex IDs, or vertex names. +The first edge points from \code{edges[1]} to \code{edges[2]}, the second from \code{edges[3]} to \code{edges[4]}, etc. } \details{ If attributes are supplied, and they are not present in the graph, diff --git a/man/add_vertices.Rd b/man/add_vertices.Rd index e54cd66e9d6..fa36c43e5b2 100644 --- a/man/add_vertices.Rd +++ b/man/add_vertices.Rd @@ -11,21 +11,17 @@ add_vertices(graph, nv, ..., attr = list()) \item{nv}{The number of vertices to add.} -\item{...}{Additional arguments, they must be named, -and they will be added as vertex attributes, for the newly added -vertices. See also details below.} +\item{...}{Additional arguments, they must be named, and they will be added as vertex attributes, for the newly added vertices. +See also details below.} -\item{attr}{A named list, its elements will be added -as vertex attributes, for the newly added vertices. See also details -below.} +\item{attr}{A named list, its elements will be added as vertex attributes, for the newly added vertices. +See also details below.} } \value{ The graph, with the vertices (and attributes) added. } \description{ -If attributes are supplied, and they are not present in the graph, -their values for the original vertices of the graph are set to -\code{NA}. +If attributes are supplied, and they are not present in the graph, their values for the original vertices of the graph are set to \code{NA}. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_add_vertices}{\code{add_vertices()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/adjacent.triangles.Rd b/man/adjacent.triangles.Rd index 88abc2cda05..b86726e0b30 100644 --- a/man/adjacent.triangles.Rd +++ b/man/adjacent.triangles.Rd @@ -7,18 +7,17 @@ adjacent.triangles(graph, vids = V(graph)) } \arguments{ -\item{graph}{The input graph. It might be directed, but edge directions are -ignored.} +\item{graph}{The input graph. +It might be directed, but edge directions are ignored.} -\item{vids}{The vertices to query. This might be a vector of numeric IDs, -or a character vector of symbolic vertex names for named graphs. The -default \code{NULL} selects all vertices.} +\item{vids}{The vertices to query. +This might be a vector of numeric IDs, or a character vector of symbolic vertex names for named graphs. +The default \code{NULL} selects all vertices.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{adjacent.triangles()} was renamed to \code{\link[=count_triangles]{count_triangles()}} to create a more -consistent API. +\code{adjacent.triangles()} was renamed to \code{\link[=count_triangles]{count_triangles()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Motifs.html#igraph_count_adjacent_triangles}{\code{count_adjacent_triangles()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/adjacent_vertices.Rd b/man/adjacent_vertices.Rd index 7cd09d74caa..10e5751658b 100644 --- a/man/adjacent_vertices.Rd +++ b/man/adjacent_vertices.Rd @@ -13,16 +13,14 @@ adjacent_vertices(graph, v, ..., mode = c("out", "in", "all", "total")) \item{...}{These dots are for future extensions and must be empty.} -\item{mode}{Whether to query outgoing (\sQuote{out}), incoming -(\sQuote{in}) edges, or both types (\sQuote{all}). This is -ignored for undirected graphs.} +\item{mode}{Whether to query outgoing (\sQuote{out}), incoming (\sQuote{in}) edges, or both types (\sQuote{all}). +This is ignored for undirected graphs.} } \value{ A list of vertex sequences. } \description{ -This function is similar to \code{\link[=neighbors]{neighbors()}}, but it queries -the adjacent vertices for multiple vertices at once. +This function is similar to \code{\link[=neighbors]{neighbors()}}, but it queries the adjacent vertices for multiple vertices at once. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/aging.ba.game.Rd b/man/aging.ba.game.Rd index 32bf32cc7fe..2f55e1e55e1 100644 --- a/man/aging.ba.game.Rd +++ b/man/aging.ba.game.Rd @@ -29,47 +29,43 @@ aging.ba.game( \item{aging.exp}{The exponent of the aging, usually a non-positive number, see details below.} -\item{m}{The number of edges each new vertex creates (except the very first -vertex). This argument is used only if both the \code{out.dist} and -\code{out.seq} arguments are NULL.} +\item{m}{The number of edges each new vertex creates (except the very first vertex). +This argument is used only if both the \code{out.dist} and \code{out.seq} arguments are NULL.} -\item{aging.bin}{The number of bins to use for measuring the age of -vertices, see details below.} +\item{aging.bin}{The number of bins to use for measuring the age of vertices, see details below.} -\item{out.dist}{The discrete distribution to generate the number of edges to -add in each time step if \code{out.seq} is NULL. See details below.} +\item{out.dist}{The discrete distribution to generate the number of edges to add in each time step if \code{out.seq} is NULL. +See details below.} -\item{out.seq}{The number of edges to add in each time step, a vector -containing as many elements as the number of vertices. See details below.} +\item{out.seq}{The number of edges to add in each time step, a vector containing as many elements as the number of vertices. +See details below.} -\item{out.pref}{Logical, whether to include edges not initiated by -the vertex as a basis of preferential attachment. See details below.} +\item{out.pref}{Logical, whether to include edges not initiated by the vertex as a basis of preferential attachment. +See details below.} -\item{directed}{Logical, whether to generate a directed graph. See -details below.} +\item{directed}{Logical, whether to generate a directed graph. +See details below.} -\item{zero.deg.appeal}{The degree-dependent part of the -\sQuote{attractiveness} of the vertices with no adjacent edges. See also -details below.} +\item{zero.deg.appeal}{The degree-dependent part of the \sQuote{attractiveness} of the vertices with no adjacent edges. +See also details below.} -\item{zero.age.appeal}{The age-dependent part of the \sQuote{attrativeness} -of the vertices with age zero. It is usually zero, see details below.} +\item{zero.age.appeal}{The age-dependent part of the \sQuote{attrativeness} of the vertices with age zero. +It is usually zero, see details below.} -\item{deg.coef}{The coefficient of the degree-dependent -\sQuote{attractiveness}. See details below.} +\item{deg.coef}{The coefficient of the degree-dependent \sQuote{attractiveness}. +See details below.} -\item{age.coef}{The coefficient of the age-dependent part of the -\sQuote{attractiveness}. See details below.} +\item{age.coef}{The coefficient of the age-dependent part of the \sQuote{attractiveness}. +See details below.} -\item{time.window}{Integer constant, if NULL only adjacent added in the last -\code{time.windows} time steps are counted as a basis of the preferential -attachment. See also details below.} +\item{time.window}{Integer constant, +if NULL only adjacent added in the last \code{time.windows} time steps are counted as a basis of the preferential attachment. +See also details below.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{aging.ba.game()} was renamed to \code{\link[=sample_pa_age]{sample_pa_age()}} to create a more -consistent API. +\code{aging.ba.game()} was renamed to \code{\link[=sample_pa_age]{sample_pa_age()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_barabasi_aging_game}{\code{barabasi_aging_game()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_recent_degree_aging_game}{\code{recent_degree_aging_game()}} diff --git a/man/aging.barabasi.game.Rd b/man/aging.barabasi.game.Rd index 3a1c36c7736..949a62d3e0a 100644 --- a/man/aging.barabasi.game.Rd +++ b/man/aging.barabasi.game.Rd @@ -29,47 +29,43 @@ aging.barabasi.game( \item{aging.exp}{The exponent of the aging, usually a non-positive number, see details below.} -\item{m}{The number of edges each new vertex creates (except the very first -vertex). This argument is used only if both the \code{out.dist} and -\code{out.seq} arguments are NULL.} +\item{m}{The number of edges each new vertex creates (except the very first vertex). +This argument is used only if both the \code{out.dist} and \code{out.seq} arguments are NULL.} -\item{aging.bin}{The number of bins to use for measuring the age of -vertices, see details below.} +\item{aging.bin}{The number of bins to use for measuring the age of vertices, see details below.} -\item{out.dist}{The discrete distribution to generate the number of edges to -add in each time step if \code{out.seq} is NULL. See details below.} +\item{out.dist}{The discrete distribution to generate the number of edges to add in each time step if \code{out.seq} is NULL. +See details below.} -\item{out.seq}{The number of edges to add in each time step, a vector -containing as many elements as the number of vertices. See details below.} +\item{out.seq}{The number of edges to add in each time step, a vector containing as many elements as the number of vertices. +See details below.} -\item{out.pref}{Logical, whether to include edges not initiated by -the vertex as a basis of preferential attachment. See details below.} +\item{out.pref}{Logical, whether to include edges not initiated by the vertex as a basis of preferential attachment. +See details below.} -\item{directed}{Logical, whether to generate a directed graph. See -details below.} +\item{directed}{Logical, whether to generate a directed graph. +See details below.} -\item{zero.deg.appeal}{The degree-dependent part of the -\sQuote{attractiveness} of the vertices with no adjacent edges. See also -details below.} +\item{zero.deg.appeal}{The degree-dependent part of the \sQuote{attractiveness} of the vertices with no adjacent edges. +See also details below.} -\item{zero.age.appeal}{The age-dependent part of the \sQuote{attrativeness} -of the vertices with age zero. It is usually zero, see details below.} +\item{zero.age.appeal}{The age-dependent part of the \sQuote{attrativeness} of the vertices with age zero. +It is usually zero, see details below.} -\item{deg.coef}{The coefficient of the degree-dependent -\sQuote{attractiveness}. See details below.} +\item{deg.coef}{The coefficient of the degree-dependent \sQuote{attractiveness}. +See details below.} -\item{age.coef}{The coefficient of the age-dependent part of the -\sQuote{attractiveness}. See details below.} +\item{age.coef}{The coefficient of the age-dependent part of the \sQuote{attractiveness}. +See details below.} -\item{time.window}{Integer constant, if NULL only adjacent added in the last -\code{time.windows} time steps are counted as a basis of the preferential -attachment. See also details below.} +\item{time.window}{Integer constant, +if NULL only adjacent added in the last \code{time.windows} time steps are counted as a basis of the preferential attachment. +See also details below.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{aging.barabasi.game()} was renamed to \code{\link[=sample_pa_age]{sample_pa_age()}} to create a more -consistent API. +\code{aging.barabasi.game()} was renamed to \code{\link[=sample_pa_age]{sample_pa_age()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_barabasi_aging_game}{\code{barabasi_aging_game()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_recent_degree_aging_game}{\code{recent_degree_aging_game()}} diff --git a/man/aging.prefatt.game.Rd b/man/aging.prefatt.game.Rd index e89d14fdb24..e8090720a2d 100644 --- a/man/aging.prefatt.game.Rd +++ b/man/aging.prefatt.game.Rd @@ -29,47 +29,43 @@ aging.prefatt.game( \item{aging.exp}{The exponent of the aging, usually a non-positive number, see details below.} -\item{m}{The number of edges each new vertex creates (except the very first -vertex). This argument is used only if both the \code{out.dist} and -\code{out.seq} arguments are NULL.} +\item{m}{The number of edges each new vertex creates (except the very first vertex). +This argument is used only if both the \code{out.dist} and \code{out.seq} arguments are NULL.} -\item{aging.bin}{The number of bins to use for measuring the age of -vertices, see details below.} +\item{aging.bin}{The number of bins to use for measuring the age of vertices, see details below.} -\item{out.dist}{The discrete distribution to generate the number of edges to -add in each time step if \code{out.seq} is NULL. See details below.} +\item{out.dist}{The discrete distribution to generate the number of edges to add in each time step if \code{out.seq} is NULL. +See details below.} -\item{out.seq}{The number of edges to add in each time step, a vector -containing as many elements as the number of vertices. See details below.} +\item{out.seq}{The number of edges to add in each time step, a vector containing as many elements as the number of vertices. +See details below.} -\item{out.pref}{Logical, whether to include edges not initiated by -the vertex as a basis of preferential attachment. See details below.} +\item{out.pref}{Logical, whether to include edges not initiated by the vertex as a basis of preferential attachment. +See details below.} -\item{directed}{Logical, whether to generate a directed graph. See -details below.} +\item{directed}{Logical, whether to generate a directed graph. +See details below.} -\item{zero.deg.appeal}{The degree-dependent part of the -\sQuote{attractiveness} of the vertices with no adjacent edges. See also -details below.} +\item{zero.deg.appeal}{The degree-dependent part of the \sQuote{attractiveness} of the vertices with no adjacent edges. +See also details below.} -\item{zero.age.appeal}{The age-dependent part of the \sQuote{attrativeness} -of the vertices with age zero. It is usually zero, see details below.} +\item{zero.age.appeal}{The age-dependent part of the \sQuote{attrativeness} of the vertices with age zero. +It is usually zero, see details below.} -\item{deg.coef}{The coefficient of the degree-dependent -\sQuote{attractiveness}. See details below.} +\item{deg.coef}{The coefficient of the degree-dependent \sQuote{attractiveness}. +See details below.} -\item{age.coef}{The coefficient of the age-dependent part of the -\sQuote{attractiveness}. See details below.} +\item{age.coef}{The coefficient of the age-dependent part of the \sQuote{attractiveness}. +See details below.} -\item{time.window}{Integer constant, if NULL only adjacent added in the last -\code{time.windows} time steps are counted as a basis of the preferential -attachment. See also details below.} +\item{time.window}{Integer constant, +if NULL only adjacent added in the last \code{time.windows} time steps are counted as a basis of the preferential attachment. +See also details below.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{aging.prefatt.game()} was renamed to \code{\link[=sample_pa_age]{sample_pa_age()}} to create a more -consistent API. +\code{aging.prefatt.game()} was renamed to \code{\link[=sample_pa_age]{sample_pa_age()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_barabasi_aging_game}{\code{barabasi_aging_game()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_recent_degree_aging_game}{\code{recent_degree_aging_game()}} diff --git a/man/align_layout.Rd b/man/align_layout.Rd index bfb62b60c53..0a46dee5cdb 100644 --- a/man/align_layout.Rd +++ b/man/align_layout.Rd @@ -2,10 +2,8 @@ % Please edit documentation in R/layout.R \name{align_layout} \alias{align_layout} -\title{Align a vertex layout -This function centers a vertex layout on the coordinate system origin and -rotates the layout to achieve a visually pleasing alignment with the coordinate -axes. Doing this is particularly useful with force-directed layouts such as \code{\link[=layout_with_fr]{layout_with_fr()}}.} +\title{Align a vertex layout This function centers a vertex layout on the coordinate system origin and rotates the layout to achieve a visually pleasing alignment with the coordinate axes. +Doing this is particularly useful with force-directed layouts such as \code{\link[=layout_with_fr]{layout_with_fr()}}.} \usage{ align_layout(graph, layout) } @@ -18,10 +16,8 @@ align_layout(graph, layout) modified layout matrix } \description{ -Align a vertex layout -This function centers a vertex layout on the coordinate system origin and -rotates the layout to achieve a visually pleasing alignment with the coordinate -axes. Doing this is particularly useful with force-directed layouts such as \code{\link[=layout_with_fr]{layout_with_fr()}}. +Align a vertex layout This function centers a vertex layout on the coordinate system origin and rotates the layout to achieve a visually pleasing alignment with the coordinate axes. +Doing this is particularly useful with force-directed layouts such as \code{\link[=layout_with_fr]{layout_with_fr()}}. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Layout.html#igraph_layout_align}{\code{layout_align()}} diff --git a/man/all_simple_paths.Rd b/man/all_simple_paths.Rd index 538fc0756b1..d0b7cbca497 100644 --- a/man/all_simple_paths.Rd +++ b/man/all_simple_paths.Rd @@ -18,34 +18,31 @@ all_simple_paths( \item{from}{The source vertex.} -\item{to}{The target vertex of vertices. The default \code{NULL} selects all -vertices.} +\item{to}{The target vertex of vertices. +The default \code{NULL} selects all vertices.} \item{...}{These dots are for future extensions and must be empty.} -\item{mode}{Character constant, gives whether the shortest paths to or -from the given vertices should be calculated for directed graphs. If -\code{out} then the shortest paths \emph{from} the vertex, if \verb{in} -then \emph{to} it will be considered. If \code{all}, the default, then -the corresponding undirected graph will be used, i.e. not directed paths -are searched. This argument is ignored for undirected graphs.} +\item{mode}{Character constant, +gives whether the shortest paths to or from the given vertices should be calculated for directed graphs. +If \code{out} then the shortest paths \emph{from} the vertex, if \verb{in} then \emph{to} it will be considered. +If \code{all}, the default, then the corresponding undirected graph will be used, i.e. not directed paths are searched. +This argument is ignored for undirected graphs.} -\item{cutoff}{Maximum length of the paths that are considered. If negative, -no cutoff is used.} +\item{cutoff}{Maximum length of the paths that are considered. +If negative, no cutoff is used.} } \value{ -A list of integer vectors, each integer vector is a path from -the source vertex to one of the target vertices. A path is given by its -vertex IDs. +A list of integer vectors, each integer vector is a path from the source vertex to one of the target vertices. +A path is given by its vertex IDs. } \description{ -This function lists all simple paths from one source vertex to another -vertex or vertices. A path is simple if contains no repeated vertices. +This function lists all simple paths from one source vertex to another vertex or vertices. +A path is simple if contains no repeated vertices. } \details{ -Note that potentially there are exponentially many paths between two -vertices of a graph, and you may run out of memory when using this -function, if your graph is lattice-like. +Note that potentially there are exponentially many paths between two vertices of a graph, +and you may run out of memory when using this function, if your graph is lattice-like. This function ignores multiple and loop edges. } diff --git a/man/alpha.centrality.Rd b/man/alpha.centrality.Rd index c9c87f8d343..838a80dca8f 100644 --- a/man/alpha.centrality.Rd +++ b/man/alpha.centrality.Rd @@ -16,50 +16,42 @@ alpha.centrality( ) } \arguments{ -\item{graph}{The input graph, can be directed or undirected. In undirected -graphs, edges are treated as if they were reciprocal directed ones.} +\item{graph}{The input graph, can be directed or undirected. +In undirected graphs, edges are treated as if they were reciprocal directed ones.} -\item{nodes}{Vertex sequence, the vertices for which the alpha centrality -values are returned. The default \code{NULL} selects all vertices. +\item{nodes}{Vertex sequence, the vertices for which the alpha centrality values are returned. +The default \code{NULL} selects all vertices. (For technical reasons they will be calculated for all vertices, anyway.)} -\item{alpha}{Parameter specifying the relative importance of endogenous -versus exogenous factors in the determination of centrality. See details -below.} +\item{alpha}{Parameter specifying the relative importance of endogenous versus exogenous factors in the determination of centrality. +See details below.} -\item{loops}{Whether to eliminate loop edges from the graph before the -calculation.} +\item{loops}{Whether to eliminate loop edges from the graph before the calculation.} -\item{exo}{The exogenous factors, in most cases this is either a constant -- -the same factor for every node, or a vector giving the factor for every -vertex. Note that too long vectors will be truncated and too short vectors -will be replicated to match the number of vertices.} +\item{exo}{The exogenous factors, in most cases this is either a constant -- the same factor for every node, +or a vector giving the factor for every vertex. +Note that too long vectors will be truncated and too short vectors will be replicated to match the number of vertices.} \item{weights}{One of the following: \itemize{ -\item \code{NULL} (default): use the \code{weight} edge attribute if the graph has -one, otherwise return a traditional (unweighted) adjacency matrix. +\item \code{NULL} (default): use the \code{weight} edge attribute if the graph has one, +otherwise return a traditional (unweighted) adjacency matrix. \item \code{NA}: explicitly unweighted, ignoring any \code{weight} edge attribute. -\item A numeric or logical vector of length \code{\link[=ecount]{ecount()}}: use these values -directly as edge weights. -\item A character scalar: the name of an edge attribute whose values are -used as weights. The attribute must be numeric or logical. +\item A numeric or logical vector of length \code{\link[=ecount]{ecount()}}: use these values directly as edge weights. +\item A character scalar: the name of an edge attribute whose values are used as weights. +The attribute must be numeric or logical. } -If multiple edges share endpoints, the value of an arbitrarily chosen edge -is included in the matrix.} +If multiple edges share endpoints, the value of an arbitrarily chosen edge is included in the matrix.} -\item{tol}{Tolerance for near-singularities during matrix inversion, see -\code{\link[Matrix:solve]{Matrix::solve()}}.} +\item{tol}{Tolerance for near-singularities during matrix inversion, see \code{\link[Matrix:solve]{Matrix::solve()}}.} -\item{sparse}{Logical, whether to use sparse matrices for the -calculation. The \sQuote{Matrix} package is required for sparse matrix -support} +\item{sparse}{Logical, whether to use sparse matrices for the calculation. +The \sQuote{Matrix} package is required for sparse matrix support} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{alpha.centrality()} was renamed to \code{\link[=alpha_centrality]{alpha_centrality()}} to create a more -consistent API. +\code{alpha.centrality()} was renamed to \code{\link[=alpha_centrality]{alpha_centrality()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Operators.html#igraph_simplify}{\code{simplify()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_adjacency}{\code{get_adjacency()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_adjacency_sparse}{\code{get_adjacency_sparse()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/alpha_centrality.Rd b/man/alpha_centrality.Rd index 29b1404c764..6110d69668a 100644 --- a/man/alpha_centrality.Rd +++ b/man/alpha_centrality.Rd @@ -17,66 +17,54 @@ alpha_centrality( ) } \arguments{ -\item{graph}{The input graph, can be directed or undirected. In undirected -graphs, edges are treated as if they were reciprocal directed ones.} +\item{graph}{The input graph, can be directed or undirected. +In undirected graphs, edges are treated as if they were reciprocal directed ones.} -\item{nodes}{Vertex sequence, the vertices for which the alpha centrality -values are returned. The default \code{NULL} selects all vertices. +\item{nodes}{Vertex sequence, the vertices for which the alpha centrality values are returned. +The default \code{NULL} selects all vertices. (For technical reasons they will be calculated for all vertices, anyway.)} \item{...}{These dots are for future extensions and must be empty.} -\item{alpha}{Parameter specifying the relative importance of endogenous -versus exogenous factors in the determination of centrality. See details -below.} +\item{alpha}{Parameter specifying the relative importance of endogenous versus exogenous factors in the determination of centrality. +See details below.} -\item{loops}{Whether to eliminate loop edges from the graph before the -calculation.} +\item{loops}{Whether to eliminate loop edges from the graph before the calculation.} -\item{exo}{The exogenous factors, in most cases this is either a constant -- -the same factor for every node, or a vector giving the factor for every -vertex. Note that too long vectors will be truncated and too short vectors -will be replicated to match the number of vertices.} +\item{exo}{The exogenous factors, in most cases this is either a constant -- the same factor for every node, +or a vector giving the factor for every vertex. +Note that too long vectors will be truncated and too short vectors will be replicated to match the number of vertices.} \item{weights}{One of the following: \itemize{ -\item \code{NULL} (default): use the \code{weight} edge attribute if the graph has -one, otherwise return a traditional (unweighted) adjacency matrix. +\item \code{NULL} (default): use the \code{weight} edge attribute if the graph has one, +otherwise return a traditional (unweighted) adjacency matrix. \item \code{NA}: explicitly unweighted, ignoring any \code{weight} edge attribute. -\item A numeric or logical vector of length \code{\link[=ecount]{ecount()}}: use these values -directly as edge weights. -\item A character scalar: the name of an edge attribute whose values are -used as weights. The attribute must be numeric or logical. +\item A numeric or logical vector of length \code{\link[=ecount]{ecount()}}: use these values directly as edge weights. +\item A character scalar: the name of an edge attribute whose values are used as weights. +The attribute must be numeric or logical. } -If multiple edges share endpoints, the value of an arbitrarily chosen edge -is included in the matrix.} +If multiple edges share endpoints, the value of an arbitrarily chosen edge is included in the matrix.} -\item{tol}{Tolerance for near-singularities during matrix inversion, see -\code{\link[Matrix:solve]{Matrix::solve()}}.} +\item{tol}{Tolerance for near-singularities during matrix inversion, see \code{\link[Matrix:solve]{Matrix::solve()}}.} -\item{sparse}{Logical, whether to use sparse matrices for the -calculation. The \sQuote{Matrix} package is required for sparse matrix -support} +\item{sparse}{Logical, whether to use sparse matrices for the calculation. +The \sQuote{Matrix} package is required for sparse matrix support} } \value{ -A numeric vector contaning the centrality scores for the selected -vertices. +A numeric vector contaning the centrality scores for the selected vertices. } \description{ -\code{alpha_centrality()} calculates the alpha centrality of some (or all) -vertices in a graph. +\code{alpha_centrality()} calculates the alpha centrality of some (or all) vertices in a graph. } \details{ -The alpha centrality measure can be considered as a generalization of -eigenvector centrality to directed graphs. It was proposed by Bonacich in -2001 (see reference below). +The alpha centrality measure can be considered as a generalization of eigenvector centrality to directed graphs. +It was proposed by Bonacich in 2001 (see reference below). The alpha centrality of the vertices in a graph is defined as the solution of the following matrix equation: \deqn{x=\alpha A^T x+e,}{x=alpha t(A)x+e,} -where \eqn{A}{A} is the (not necessarily symmetric) adjacency matrix of the -graph, \eqn{e}{e} is the vector of exogenous sources of status of the -vertices and \eqn{\alpha}{alpha} is the relative importance of the -endogenous versus exogenous factors. +where \eqn{A}{A} is the (not necessarily symmetric) adjacency matrix of the graph, +\eqn{e}{e} is the vector of exogenous sources of status of the vertices and \eqn{\alpha}{alpha} is the relative importance of the endogenous versus exogenous factors. } \section{Warning}{ Singular adjacency matrices cause problems for this diff --git a/man/are.connected.Rd b/man/are.connected.Rd index 6bc190f881c..251f992a245 100644 --- a/man/are.connected.Rd +++ b/man/are.connected.Rd @@ -16,8 +16,7 @@ are.connected(graph, v1, v2) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{are.connected()} was renamed to \code{\link[=are_adjacent]{are_adjacent()}} to create a more -consistent API. +\code{are.connected()} was renamed to \code{\link[=are_adjacent]{are_adjacent()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_are_adjacent}{\code{are_adjacent()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/arpack.Rd b/man/arpack.Rd index 45a21237d34..7b03b8744c0 100644 --- a/man/arpack.Rd +++ b/man/arpack.Rd @@ -19,27 +19,24 @@ arpack( ) } \arguments{ -\item{func}{The function to perform the matrix-vector multiplication. ARPACK -requires to perform these by the user. The function gets the vector \eqn{x} -as the first argument, and it should return \eqn{Ax}, where \eqn{A} is the -\dQuote{input matrix}. (The input matrix is never given explicitly.) The -second argument is \code{extra}.} +\item{func}{The function to perform the matrix-vector multiplication. +ARPACK requires to perform these by the user. +The function gets the vector \eqn{x} as the first argument, and it should return \eqn{Ax}, where \eqn{A} is the \dQuote{input matrix}. +(The input matrix is never given explicitly.) The second argument is \code{extra}.} \item{extra}{Extra argument to supply to \code{func}.} -\item{sym}{Logical, whether the input matrix is symmetric. Always -supply \code{TRUE} here if it is, since it can speed up the computation.} +\item{sym}{Logical, whether the input matrix is symmetric. +Always supply \code{TRUE} here if it is, since it can speed up the computation.} -\item{options}{Options to ARPACK, a named list to overwrite some of the -default option values. See details below.} +\item{options}{Options to ARPACK, a named list to overwrite some of the default option values. +See details below.} \item{env}{The environment in which \code{func} will be evaluated.} -\item{complex}{Whether to convert the eigenvectors returned by ARPACK into R -complex vectors. By default this is not done for symmetric problems (these -only have real eigenvectors/values), but only non-symmetric ones. If you -have a non-symmetric problem, but you're sure that the results will be real, -then supply \code{FALSE} here.} +\item{complex}{Whether to convert the eigenvectors returned by ARPACK into R complex vectors. +By default this is not done for symmetric problems (these only have real eigenvectors/values), but only non-symmetric ones. +If you have a non-symmetric problem, but you're sure that the results will be real, then supply \code{FALSE} here.} } \value{ A named list with the following members: @@ -60,31 +57,26 @@ See the details above. } } \description{ -Interface to the ARPACK library for calculating eigenvectors of sparse -matrices +Interface to the ARPACK library for calculating eigenvectors of sparse matrices } \details{ -ARPACK is a library for solving large scale eigenvalue problems. The -package is designed to compute a few eigenvalues and corresponding -eigenvectors of a general \eqn{n} by \eqn{n} matrix \eqn{A}. It is most -appropriate for large sparse or structured matrices \eqn{A} where structured -means that a matrix-vector product \code{w <- Av} requires order \eqn{n} -rather than the usual order \eqn{n^2} floating point operations. +ARPACK is a library for solving large scale eigenvalue problems. +The package is designed to compute a few eigenvalues and corresponding eigenvectors of a general \eqn{n} by \eqn{n} matrix \eqn{A}. +It is most appropriate for large sparse or structured matrices \eqn{A} +where structured means that a matrix-vector product \code{w <- Av} requires order \eqn{n} rather than the usual order \eqn{n^2} floating point operations. -This function is an interface to ARPACK. igraph does not contain all ARPACK -routines, only the ones dealing with symmetric and non-symmetric eigenvalue -problems using double precision real numbers. +This function is an interface to ARPACK. igraph does not contain all ARPACK routines, +only the ones dealing with symmetric and non-symmetric eigenvalue problems using double precision real numbers. -The eigenvalue calculation in ARPACK (in the simplest case) involves the -calculation of the \eqn{Av} product where \eqn{A} is the matrix we work with -and \eqn{v} is an arbitrary vector. The function supplied in the \code{fun} -argument is expected to perform this product. If the product can be done -efficiently, e.g. if the matrix is sparse, then \code{arpack()} is usually -able to calculate the eigenvalues very quickly. +The eigenvalue calculation in ARPACK (in the simplest case) involves the calculation of the \eqn{Av} product +where \eqn{A} is the matrix we work with and \eqn{v} is an arbitrary vector. +The function supplied in the \code{fun} argument is expected to perform this product. +If the product can be done efficiently, e.g. if the matrix is sparse, +then \code{arpack()} is usually able to calculate the eigenvalues very quickly. The \code{options} argument specifies what kind of calculation to perform. -It is a list with the following members, they correspond directly to ARPACK -parameters. On input it has the following fields: +It is a list with the following members, they correspond directly to ARPACK parameters. +On input it has the following fields: \describe{ \item{bmat}{ Character constant, possible values: @@ -147,8 +139,8 @@ e.g. \code{\link[=page_rank]{page_rank()}} always sets \sQuote{\code{LM}}. Numeric scalar. The number of eigenvalues to be computed. } \item{tol}{ -Numeric scalar. Stopping criterion: -the relative accuracy of the Ritz value is considered acceptable +Numeric scalar. +Stopping criterion: the relative accuracy of the Ritz value is considered acceptable if its error is less than \code{tol} times its estimated value. If this is set to zero then machine precision is used. } @@ -171,7 +163,8 @@ Maximum number of Arnoldi update iterations allowed. Blocksize to be used in the recurrence. Please always leave this on the default value, one. } \item{mode}{ -The type of the eigenproblem to be solved. Possible values if the input matrix is symmetric: +The type of the eigenproblem to be solved. +Possible values if the input matrix is symmetric: \describe{ \item{1}{ \eqn{Ax=\lambda x}{A*x=lambda*x}, \eqn{A} is symmetric. @@ -320,9 +313,8 @@ Matrices. \emph{Linear Algebra and its Applications}, vol 88/89, pp 575-595, (1987). } \seealso{ -\code{\link[=eigen_centrality]{eigen_centrality()}}, \code{\link[=page_rank]{page_rank()}}, -\code{\link[=hub_score]{hub_score()}}, \code{\link[=cluster_leading_eigen]{cluster_leading_eigen()}} are some of the -functions in igraph that use ARPACK. +\code{\link[=eigen_centrality]{eigen_centrality()}}, \code{\link[=page_rank]{page_rank()}}, \code{\link[=hub_score]{hub_score()}}, +\code{\link[=cluster_leading_eigen]{cluster_leading_eigen()}} are some of the functions in igraph that use ARPACK. } \author{ Rich Lehoucq, Kristi Maschhoff, Danny Sorensen, Chao Yang for diff --git a/man/articulation.points.Rd b/man/articulation.points.Rd index 05dad4a7ad2..b19d2625312 100644 --- a/man/articulation.points.Rd +++ b/man/articulation.points.Rd @@ -7,14 +7,13 @@ articulation.points(graph) } \arguments{ -\item{graph}{The input graph. It is treated as an undirected graph, even if -it is directed.} +\item{graph}{The input graph. +It is treated as an undirected graph, even if it is directed.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{articulation.points()} was renamed to \code{\link[=articulation_points]{articulation_points()}} to create a more -consistent API. +\code{articulation.points()} was renamed to \code{\link[=articulation_points]{articulation_points()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_articulation_points}{\code{articulation_points()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/articulation_points.Rd b/man/articulation_points.Rd index c36b206b672..fec2f70dbcb 100644 --- a/man/articulation_points.Rd +++ b/man/articulation_points.Rd @@ -10,24 +10,21 @@ articulation_points(graph) bridges(graph) } \arguments{ -\item{graph}{The input graph. It is treated as an undirected graph, even if -it is directed.} +\item{graph}{The input graph. +It is treated as an undirected graph, even if it is directed.} } \value{ -For \code{articulation_points()}, a numeric vector giving the vertex -IDs of the articulation points of the input graph. For \code{bridges()}, a -numeric vector giving the edge IDs of the bridges of the input graph. +For \code{articulation_points()}, a numeric vector giving the vertex IDs of the articulation points of the input graph. +For \code{bridges()}, a numeric vector giving the edge IDs of the bridges of the input graph. } \description{ \code{articulation_points()} finds the articulation points (or cut vertices) } \details{ -Articulation points or cut vertices are vertices whose removal increases the -number of connected components in a graph. Similarly, bridges or cut-edges -are edges whose removal increases the number of connected components in a -graph. If the original graph was connected, then the removal of a single -articulation point or a single bridge makes it disconnected. If a graph -contains no articulation points, then its vertex connectivity is at least +Articulation points or cut vertices are vertices whose removal increases the number of connected components in a graph. +Similarly, bridges or cut-edges are edges whose removal increases the number of connected components in a graph. +If the original graph was connected, then the removal of a single articulation point or a single bridge makes it disconnected. +If a graph contains no articulation points, then its vertex connectivity is at least two. } \section{Related documentation in the C library}{ diff --git a/man/as.directed.Rd b/man/as.directed.Rd index f2d4dac32d0..c640691bb4c 100644 --- a/man/as.directed.Rd +++ b/man/as.directed.Rd @@ -9,16 +9,15 @@ as.directed(graph, mode = c("mutual", "arbitrary", "random", "acyclic")) \arguments{ \item{graph}{The graph to convert.} -\item{mode}{Character constant, defines the conversion algorithm. For -\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{mode}{Character constant, defines the conversion algorithm. +For \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.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{as.directed()} was renamed to \code{\link[=as_directed]{as_directed()}} to create a more -consistent API. +\code{as.directed()} was renamed to \code{\link[=as_directed]{as_directed()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_to_directed}{\code{to_directed()}} diff --git a/man/as.igraph.Rd b/man/as.igraph.Rd index 6cd869be514..51afc706490 100644 --- a/man/as.igraph.Rd +++ b/man/as.igraph.Rd @@ -10,7 +10,8 @@ as.igraph(x, ...) \arguments{ \item{x}{The object to convert.} -\item{\dots}{Additional arguments. None currently.} +\item{\dots}{Additional arguments. +None currently.} } \value{ All these functions return an igraph graph. diff --git a/man/as.matrix.igraph.Rd b/man/as.matrix.igraph.Rd index d5839fde213..024ceeeda5b 100644 --- a/man/as.matrix.igraph.Rd +++ b/man/as.matrix.igraph.Rd @@ -9,31 +9,25 @@ \arguments{ \item{x}{object of class \code{igraph}, the network} -\item{matrix.type}{character, type of matrix to return, currently "adjacency" -or "edgelist" are supported} +\item{matrix.type}{character, type of matrix to return, currently "adjacency" or "edgelist" are supported} \item{\dots}{other arguments to/from other methods} } \value{ -Depending on the value of \code{matrix.type} either a square -adjacency matrix or a two-column numeric matrix representing the edgelist. +Depending on the value of \code{matrix.type} either a square adjacency matrix or a two-column numeric matrix representing the edgelist. } \description{ -Get adjacency or edgelist representation of the network stored as an -\code{igraph} object. +Get adjacency or edgelist representation of the network stored as an \code{igraph} object. } \details{ -If \code{matrix.type} is \code{"edgelist"}, then a two-column numeric edge list -matrix is returned. The value of \code{attrname} is ignored. +If \code{matrix.type} is \code{"edgelist"}, then a two-column numeric edge list matrix is returned. +The value of \code{attrname} is ignored. -If \code{matrix.type} is \code{"adjacency"}, then a square adjacency matrix is -returned. For adjacency matrices, you can use the \code{attr} keyword argument -to use the values of an edge attribute in the matrix cells. See the -documentation of \link{as_adjacency_matrix} for more details. +If \code{matrix.type} is \code{"adjacency"}, then a square adjacency matrix is returned. +For adjacency matrices, you can use the \code{attr} keyword argument to use the values of an edge attribute in the matrix cells. +See the documentation of \link{as_adjacency_matrix} for more details. -Other arguments passed through \code{...} are passed to either -\code{\link[=as_adjacency_matrix]{as_adjacency_matrix()}} or \code{\link[=as_edgelist]{as_edgelist()}} -depending on the value of \code{matrix.type}. +Other arguments passed through \code{...} are passed to either \code{\link[=as_adjacency_matrix]{as_adjacency_matrix()}} or \code{\link[=as_edgelist]{as_edgelist()}} depending on the value of \code{matrix.type}. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_edgelist}{\code{get_edgelist()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_adjacency}{\code{get_adjacency()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_adjacency_sparse}{\code{get_adjacency_sparse()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/as.undirected.Rd b/man/as.undirected.Rd index 63476faf18b..5eef609bdac 100644 --- a/man/as.undirected.Rd +++ b/man/as.undirected.Rd @@ -13,22 +13,21 @@ as.undirected( \arguments{ \item{graph}{The graph to convert.} -\item{mode}{Character constant, defines the conversion algorithm. For -\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{mode}{Character constant, defines the conversion algorithm. +For \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. The default \code{NULL} uses the \code{edge.attr.comb} igraph option.} +\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. +The default \code{NULL} uses the \code{edge.attr.comb} igraph option.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{as.undirected()} was renamed to \code{\link[=as_undirected]{as_undirected()}} to create a more -consistent API. +\code{as.undirected()} was renamed to \code{\link[=as_undirected]{as_undirected()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_to_undirected}{\code{to_undirected()}} diff --git a/man/as_adj.Rd b/man/as_adj.Rd index b6ef3142c40..ea8720617ad 100644 --- a/man/as_adj.Rd +++ b/man/as_adj.Rd @@ -18,44 +18,37 @@ as_adj( \item{graph}{The graph to convert.} \item{type}{Gives how to create the adjacency matrix for undirected graphs. -It is ignored for directed graphs. Possible values: \code{upper}: the upper -right triangle of the matrix is used, \code{lower}: the lower left triangle -of the matrix is used. \code{both}: the whole matrix is used, a symmetric -matrix is returned.} +It is ignored for directed graphs. +Possible values: \code{upper}: the upper right triangle of the matrix is used, \code{lower}: the lower left triangle of the matrix is used. +\code{both}: the whole matrix is used, a symmetric matrix is returned.} \item{weights}{One of the following: \itemize{ -\item \code{NULL} (default): use the \code{weight} edge attribute if the graph has -one, otherwise return a traditional (unweighted) adjacency matrix. +\item \code{NULL} (default): use the \code{weight} edge attribute if the graph has one, +otherwise return a traditional (unweighted) adjacency matrix. \item \code{NA}: explicitly unweighted, ignoring any \code{weight} edge attribute. -\item A numeric or logical vector of length \code{\link[=ecount]{ecount()}}: use these values -directly as edge weights. -\item A character scalar: the name of an edge attribute whose values are -used as weights. The attribute must be numeric or logical. +\item A numeric or logical vector of length \code{\link[=ecount]{ecount()}}: use these values directly as edge weights. +\item A character scalar: the name of an edge attribute whose values are used as weights. +The attribute must be numeric or logical. } -If multiple edges share endpoints, the value of an arbitrarily chosen edge -is included in the matrix.} +If multiple edges share endpoints, the value of an arbitrarily chosen edge is included in the matrix.} -\item{attr}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{weights} instead. A -character edge attribute name is forwarded to \code{weights} unchanged; \code{NULL} -becomes \code{weights = NA}, since \code{attr = NULL} asked for a traditional -unweighted matrix while \code{weights = NULL} picks the \code{weight} attribute up.} +\item{attr}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{weights} instead. +A character edge attribute name is forwarded to \code{weights} unchanged; \code{NULL} becomes \code{weights = NA}, +since \code{attr = NULL} asked for a traditional unweighted matrix while \code{weights = NULL} picks the \code{weight} attribute up.} \item{edges}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Logical, whether to return the edge IDs in the matrix. For non-existant edges zero is returned.} -\item{names}{Logical, whether to assign row and column names -to the matrix. These are only assigned if the \code{name} vertex attribute -is present in the graph.} +\item{names}{Logical, whether to assign row and column names to the matrix. +These are only assigned if the \code{name} vertex attribute is present in the graph.} -\item{sparse}{Logical, whether to create a sparse matrix. The -\sQuote{\code{Matrix}} package must be installed for creating sparse -matrices. The default \code{NULL} uses the \code{sparsematrices} igraph option.} +\item{sparse}{Logical, whether to create a sparse matrix. +The \sQuote{\code{Matrix}} package must be installed for creating sparse matrices. +The default \code{NULL} uses the \code{sparsematrices} igraph option.} } \description{ -\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -We plan to remove \code{as_adj()} in favor of the more explicitly named -\code{as_adjacency_matrix()} so please use \code{as_adjacency_matrix()} instead. +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} We plan to remove \code{as_adj()} in favor of the more explicitly named \code{as_adjacency_matrix()} so please use \code{as_adjacency_matrix()} instead. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_adjacency}{\code{get_adjacency()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_adjacency_sparse}{\code{get_adjacency_sparse()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/as_adj_list.Rd b/man/as_adj_list.Rd index 4f5f7515f95..602fd9b97a6 100644 --- a/man/as_adj_list.Rd +++ b/man/as_adj_list.Rd @@ -25,39 +25,32 @@ as_adj_edge_list( \item{...}{These dots are for future extensions and must be empty.} -\item{mode}{Character scalar, it gives what kind of adjacent edges/vertices -to include in the lists. \sQuote{\code{out}} is for outgoing edges/vertices, -\sQuote{\verb{in}} is for incoming edges/vertices, \sQuote{\code{all}} is -for both. This argument is ignored for undirected graphs.} +\item{mode}{Character scalar, it gives what kind of adjacent edges/vertices to include in the lists. +\sQuote{\code{out}} is for outgoing edges/vertices, \sQuote{\verb{in}} is for incoming edges/vertices, \sQuote{\code{all}} is for both. +This argument is ignored for undirected graphs.} -\item{loops}{Character scalar, one of \code{"ignore"} (to omit loops), \code{"twice"} -(to include loop edges twice) and \code{"once"} (to include them once). \code{"twice"} -is not allowed for directed graphs and will be replaced with \code{"once"}.} +\item{loops}{Character scalar, one of \code{"ignore"} (to omit loops), +\code{"twice"} (to include loop edges twice) and \code{"once"} (to include them once). +\code{"twice"} is not allowed for directed graphs and will be replaced with \code{"once"}.} -\item{multiple}{Logical, set to \code{FALSE} to use only one representative -of each set of parallel edges.} +\item{multiple}{Logical, set to \code{FALSE} to use only one representative of each set of parallel edges.} } \value{ -A list of \code{igraph.vs} or a list of numeric vectors depending on -the value of \code{igraph_opt("return.vs.es")}, see details for performance -characteristics. +A list of \code{igraph.vs} or a list of numeric vectors depending on the value of \code{igraph_opt("return.vs.es")}, +see details for performance characteristics. } \description{ -Create adjacency lists from a graph, either for adjacent edges or for -neighboring vertices +Create adjacency lists from a graph, either for adjacent edges or for neighboring vertices } \details{ -\code{as_adj_list()} returns a list of numeric vectors, which include the IDs -of neighbor vertices (according to the \code{mode} argument) of all -vertices. +\code{as_adj_list()} returns a list of numeric vectors, +which include the IDs of neighbor vertices (according to the \code{mode} argument) of all vertices. -\code{as_adj_edge_list()} returns a list of numeric vectors, which include the -IDs of adjacent edges (according to the \code{mode} argument) of all -vertices. +\code{as_adj_edge_list()} returns a list of numeric vectors, +which include the IDs of adjacent edges (according to the \code{mode} argument) of all vertices. -If \code{igraph_opt("return.vs.es")} is true (default), the numeric -vectors of the adjacency lists are coerced to \code{igraph.vs}, this can be -a very expensive operation on large graphs. +If \code{igraph_opt("return.vs.es")} is true (default), the numeric vectors of the adjacency lists are coerced to \code{igraph.vs}, +this can be a very expensive operation on large graphs. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_is_directed}{\code{is_directed()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/as_adjacency_matrix.Rd b/man/as_adjacency_matrix.Rd index b7148dc2a05..7b7bbe04065 100644 --- a/man/as_adjacency_matrix.Rd +++ b/man/as_adjacency_matrix.Rd @@ -19,55 +19,46 @@ as_adjacency_matrix( \item{graph}{The graph to convert.} \item{type}{Gives how to create the adjacency matrix for undirected graphs. -It is ignored for directed graphs. Possible values: \code{upper}: the upper -right triangle of the matrix is used, \code{lower}: the lower left triangle -of the matrix is used. \code{both}: the whole matrix is used, a symmetric -matrix is returned.} +It is ignored for directed graphs. +Possible values: \code{upper}: the upper right triangle of the matrix is used, \code{lower}: the lower left triangle of the matrix is used. +\code{both}: the whole matrix is used, a symmetric matrix is returned.} \item{...}{These dots are for future extensions and must be empty.} \item{weights}{One of the following: \itemize{ -\item \code{NULL} (default): use the \code{weight} edge attribute if the graph has -one, otherwise return a traditional (unweighted) adjacency matrix. +\item \code{NULL} (default): use the \code{weight} edge attribute if the graph has one, +otherwise return a traditional (unweighted) adjacency matrix. \item \code{NA}: explicitly unweighted, ignoring any \code{weight} edge attribute. -\item A numeric or logical vector of length \code{\link[=ecount]{ecount()}}: use these values -directly as edge weights. -\item A character scalar: the name of an edge attribute whose values are -used as weights. The attribute must be numeric or logical. +\item A numeric or logical vector of length \code{\link[=ecount]{ecount()}}: use these values directly as edge weights. +\item A character scalar: the name of an edge attribute whose values are used as weights. +The attribute must be numeric or logical. } -If multiple edges share endpoints, the value of an arbitrarily chosen edge -is included in the matrix.} +If multiple edges share endpoints, the value of an arbitrarily chosen edge is included in the matrix.} -\item{names}{Logical, whether to assign row and column names -to the matrix. These are only assigned if the \code{name} vertex attribute -is present in the graph.} +\item{names}{Logical, whether to assign row and column names to the matrix. +These are only assigned if the \code{name} vertex attribute is present in the graph.} -\item{sparse}{Logical, whether to create a sparse matrix. The -\sQuote{\code{Matrix}} package must be installed for creating sparse -matrices. The default \code{NULL} uses the \code{sparsematrices} igraph option.} +\item{sparse}{Logical, whether to create a sparse matrix. +The \sQuote{\code{Matrix}} package must be installed for creating sparse matrices. +The default \code{NULL} uses the \code{sparsematrices} igraph option.} \item{edges}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Logical, whether to return the edge IDs in the matrix. For non-existant edges zero is returned.} -\item{attr}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{weights} instead. A -character edge attribute name is forwarded to \code{weights} unchanged; \code{NULL} -becomes \code{weights = NA}, since \code{attr = NULL} asked for a traditional -unweighted matrix while \code{weights = NULL} picks the \code{weight} attribute up.} +\item{attr}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{weights} instead. +A character edge attribute name is forwarded to \code{weights} unchanged; \code{NULL} becomes \code{weights = NA}, +since \code{attr = NULL} asked for a traditional unweighted matrix while \code{weights = NULL} picks the \code{weight} attribute up.} } \value{ -A \code{vcount(graph)} by \code{vcount(graph)} (usually) numeric -matrix. +A \code{vcount(graph)} by \code{vcount(graph)} (usually) numeric matrix. } \description{ -Sometimes it is useful to work with a standard representation of a -graph, like an adjacency matrix. +Sometimes it is useful to work with a standard representation of a graph, like an adjacency matrix. } \details{ -\code{as_adjacency_matrix()} returns the adjacency matrix of a graph, a -regular matrix if \code{sparse} is \code{FALSE}, or a sparse matrix, as -defined in the \sQuote{\code{Matrix}} package, if \code{sparse} if -\code{TRUE}. +\code{as_adjacency_matrix()} returns the adjacency matrix of a graph, a regular matrix if \code{sparse} is \code{FALSE}, or a sparse matrix, +as defined in the \sQuote{\code{Matrix}} package, if \code{sparse} if \code{TRUE}. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_adjacency}{\code{get_adjacency()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_adjacency_sparse}{\code{get_adjacency_sparse()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/as_biadjacency_matrix.Rd b/man/as_biadjacency_matrix.Rd index 9f0e5300f33..270ad0843bc 100644 --- a/man/as_biadjacency_matrix.Rd +++ b/man/as_biadjacency_matrix.Rd @@ -15,57 +15,47 @@ as_biadjacency_matrix( ) } \arguments{ -\item{graph}{The input graph. The direction of the edges is ignored in -directed graphs.} +\item{graph}{The input graph. +The direction of the edges is ignored in directed graphs.} -\item{types}{An optional vertex type vector to use instead of the -\code{type} vertex attribute. You must supply this argument if the graph has -no \code{type} vertex attribute.} +\item{types}{An optional vertex type vector to use instead of the \code{type} vertex attribute. +You must supply this argument if the graph has no \code{type} vertex attribute.} \item{...}{These dots are for future extensions and must be empty.} \item{weights}{One of the following: \itemize{ -\item \code{NULL} (default): use the \code{weight} edge attribute if the graph has -one, otherwise return a traditional (unweighted) adjacency matrix. +\item \code{NULL} (default): use the \code{weight} edge attribute if the graph has one, +otherwise return a traditional (unweighted) adjacency matrix. \item \code{NA}: explicitly unweighted, ignoring any \code{weight} edge attribute. -\item A numeric or logical vector of length \code{\link[=ecount]{ecount()}}: use these values -directly as edge weights. -\item A character scalar: the name of an edge attribute whose values are -used as weights. The attribute must be numeric or logical. +\item A numeric or logical vector of length \code{\link[=ecount]{ecount()}}: use these values directly as edge weights. +\item A character scalar: the name of an edge attribute whose values are used as weights. +The attribute must be numeric or logical. } -If multiple edges share endpoints, the value of an arbitrarily chosen edge -is included in the matrix.} +If multiple edges share endpoints, the value of an arbitrarily chosen edge is included in the matrix.} -\item{names}{Logical, if \code{TRUE} and the vertices in the graph -are named (i.e. the graph has a vertex attribute called \code{name}), then -vertex names will be added to the result as row and column names. Otherwise -the IDs of the vertices are used as row and column names.} +\item{names}{Logical, if \code{TRUE} and the vertices in the graph are named (i.e. the graph has a vertex attribute called \code{name}), +then vertex names will be added to the result as row and column names. +Otherwise the IDs of the vertices are used as row and column names.} -\item{sparse}{Logical, if it is \code{TRUE} then a sparse matrix is -created, you will need the \code{Matrix} package for this.} +\item{sparse}{Logical, if it is \code{TRUE} then a sparse matrix is created, you will need the \code{Matrix} package for this.} -\item{attr}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{weights} instead. A -character edge attribute name is forwarded to \code{weights} unchanged; \code{NULL} -becomes \code{weights = NA}, since \code{attr = NULL} asked for a traditional -unweighted matrix while \code{weights = NULL} picks the \code{weight} attribute up.} +\item{attr}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{weights} instead. +A character edge attribute name is forwarded to \code{weights} unchanged; \code{NULL} becomes \code{weights = NA}, +since \code{attr = NULL} asked for a traditional unweighted matrix while \code{weights = NULL} picks the \code{weight} attribute up.} } \value{ A sparse or dense matrix. } \description{ -This function can return a sparse or dense bipartite adjacency matrix of a bipartite -network. The bipartite adjacency matrix is an \eqn{n} times \eqn{m} matrix, \eqn{n} -and \eqn{m} are the number of vertices of the two kinds. +This function can return a sparse or dense bipartite adjacency matrix of a bipartite network. +The bipartite adjacency matrix is an \eqn{n} times \eqn{m} matrix, \eqn{n} and \eqn{m} are the number of vertices of the two kinds. } \details{ -Bipartite graphs have a \code{type} vertex attribute in igraph, this is -boolean and \code{FALSE} for the vertices of the first kind and \code{TRUE} -for vertices of the second kind. +Bipartite graphs have a \code{type} vertex attribute in igraph, +this is boolean and \code{FALSE} for the vertices of the first kind and \code{TRUE} for vertices of the second kind. -Some authors refer to the bipartite adjacency matrix as the -"bipartite incidence matrix". igraph 1.6.0 and later does not use -this naming to avoid confusion with the edge-vertex incidence matrix. +Some authors refer to the bipartite adjacency matrix as the "bipartite incidence matrix". igraph 1.6.0 and later does not use this naming to avoid confusion with the edge-vertex incidence matrix. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Bipartite.html#igraph_get_biadjacency}{\code{get_biadjacency()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_edgelist}{\code{get_edgelist()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/as_directed.Rd b/man/as_directed.Rd index ca83689eb05..d0290250524 100644 --- a/man/as_directed.Rd +++ b/man/as_directed.Rd @@ -18,24 +18,23 @@ as_undirected( \item{...}{These dots are for future extensions and must be empty.} -\item{mode}{Character constant, defines the conversion algorithm. For -\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{mode}{Character constant, defines the conversion algorithm. +For \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. The default \code{NULL} uses the \code{edge.attr.comb} igraph option.} +\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. +The default \code{NULL} uses the \code{edge.attr.comb} igraph option.} } \value{ A new graph object. } \description{ -\code{as_directed()} converts an undirected graph to directed, -\code{as_undirected()} does the opposite, it converts a directed graph to -undirected. +\code{as_directed()} converts an undirected graph to directed, \code{as_undirected()} does the opposite, +it converts a directed graph to undirected. } \details{ Conversion algorithms for \code{as_directed()}: @@ -51,18 +50,13 @@ Two directed edges are created for each undirected edge, one in each direction. } \item{"random"}{ -The number of edges in the graph stays the same, and -a randomly directed edge is created for each undirected edge. You -will get different results if you call the function multiple times -with the same graph. +The number of edges in the graph stays the same, and a randomly directed edge is created for each undirected edge. +You will get different results if you call the function multiple times with the same graph. } \item{"acyclic"}{ -The number of edges in the graph stays the same, and -a directed edge is created for each undirected edge such that the -resulting graph is guaranteed to be acyclic. This is achieved by ensuring -that edges always point from a lower index vertex to a higher index. -Note that the graph may include cycles of length 1 if the original -graph contained loop edges. +The number of edges in the graph stays the same, and a directed edge is created for each undirected edge such that the resulting graph is guaranteed to be acyclic. +This is achieved by ensuring that edges always point from a lower index vertex to a higher index. +Note that the graph may include cycles of length 1 if the original graph contained loop edges. } } @@ -79,10 +73,9 @@ for each pair of vertices which are connected with at least one directed edge, no multiple edges will be created. } \item{"mutual"}{ -One -undirected edge will be created for each pair of mutual edges. Non-mutual -edges are ignored. This mode might create multiple edges if there are more -than one mutual edge pairs between the same pair of vertices. +One undirected edge will be created for each pair of mutual edges. +Non-mutual edges are ignored. +This mode might create multiple edges if there are more than one mutual edge pairs between the same pair of vertices. } } } @@ -123,8 +116,7 @@ print(ug4, e = TRUE) } \seealso{ -\code{\link[=simplify]{simplify()}} for removing multiple and/or loop edges from -a graph. +\code{\link[=simplify]{simplify()}} for removing multiple and/or loop edges from a graph. Other conversion: \code{\link[=as.matrix.igraph]{as.matrix.igraph()}}, diff --git a/man/as_edgelist.Rd b/man/as_edgelist.Rd index 218bcecca7e..4d46996378e 100644 --- a/man/as_edgelist.Rd +++ b/man/as_edgelist.Rd @@ -11,16 +11,14 @@ as_edgelist(graph, ..., names = TRUE) \item{...}{These dots are for future extensions and must be empty.} -\item{names}{Whether to return a character matrix containing vertex -names (i.e. the \code{name} vertex attribute) if they exist or numeric -vertex IDs.} +\item{names}{Whether to return a character matrix containing vertex names (i.e. the \code{name} vertex attribute) +if they exist or numeric vertex IDs.} } \value{ A \code{ecount(graph)} by 2 numeric matrix. } \description{ -Sometimes it is useful to work with a standard representation of a -graph, like an edge list. +Sometimes it is useful to work with a standard representation of a graph, like an edge list. } \details{ \code{as_edgelist()} returns the list of edges in a graph. diff --git a/man/as_graphnel.Rd b/man/as_graphnel.Rd index cfae3c957cc..faf1f8a35c0 100644 --- a/man/as_graphnel.Rd +++ b/man/as_graphnel.Rd @@ -13,16 +13,14 @@ as_graphnel(graph) \code{as_graphnel()} returns a graphNEL graph object. } \description{ -The graphNEL class is defined in the \code{graph} package, it is another -way to represent graphs. These functions are provided to convert between -the igraph and the graphNEL objects. +The graphNEL class is defined in the \code{graph} package, it is another way to represent graphs. +These functions are provided to convert between the igraph and the graphNEL objects. } \details{ -\code{as_graphnel()} converts an igraph graph to a graphNEL graph. It -converts all graph/vertex/edge attributes. If the igraph graph has a -vertex attribute \sQuote{\code{name}}, then it will be used to assign -vertex names in the graphNEL graph. Otherwise numeric igraph vertex IDs -will be used for this purpose. +\code{as_graphnel()} converts an igraph graph to a graphNEL graph. +It converts all graph/vertex/edge attributes. +If the igraph graph has a vertex attribute \sQuote{\code{name}}, then it will be used to assign vertex names in the graphNEL graph. +Otherwise numeric igraph vertex IDs will be used for this purpose. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_edgelist}{\code{get_edgelist()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_is_directed}{\code{is_directed()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_has_multiple}{\code{has_multiple()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} @@ -46,10 +44,8 @@ g4 \dontshow{\}) # examplesIf} } \seealso{ -\code{\link[=graph_from_graphnel]{graph_from_graphnel()}} for the other direction, -\code{\link[=as_adjacency_matrix]{as_adjacency_matrix()}}, \code{\link[=graph_from_adjacency_matrix]{graph_from_adjacency_matrix()}}, -\code{\link[=as_adj_list]{as_adj_list()}} and \code{\link[=graph_from_adj_list]{graph_from_adj_list()}} for -other graph representations. +\code{\link[=graph_from_graphnel]{graph_from_graphnel()}} for the other direction, \code{\link[=as_adjacency_matrix]{as_adjacency_matrix()}}, \code{\link[=graph_from_adjacency_matrix]{graph_from_adjacency_matrix()}}, +\code{\link[=as_adj_list]{as_adj_list()}} and \code{\link[=graph_from_adj_list]{graph_from_adj_list()}} for other graph representations. Other conversion: \code{\link[=as.matrix.igraph]{as.matrix.igraph()}}, diff --git a/man/as_ids.Rd b/man/as_ids.Rd index 5b822b79039..2cd705362a2 100644 --- a/man/as_ids.Rd +++ b/man/as_ids.Rd @@ -22,15 +22,12 @@ A character or numeric vector, see details below. Convert a vertex or edge sequence to an ordinary vector } \details{ -For graphs without names, a numeric vector is returned, containing the -internal numeric vertex or edge IDs. +For graphs without names, a numeric vector is returned, containing the internal numeric vertex or edge IDs. -For graphs with names, and vertex sequences, the vertex names are -returned in a character vector. +For graphs with names, and vertex sequences, the vertex names are returned in a character vector. -For graphs with names and edge sequences, a character vector is -returned, with the \sQuote{bar} notation: \code{a|b} means an edge from -vertex \code{a} to vertex \code{b}. +For graphs with names and edge sequences, a character vector is returned, with the \sQuote{bar} notation: +\code{a|b} means an edge from vertex \code{a} to vertex \code{b}. } \examples{ g <- make_ring(10) diff --git a/man/as_incidence_matrix.Rd b/man/as_incidence_matrix.Rd index 88d1c436f48..f23d452645a 100644 --- a/man/as_incidence_matrix.Rd +++ b/man/as_incidence_matrix.Rd @@ -12,13 +12,10 @@ as_incidence_matrix(...) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{as_incidence_matrix()} was renamed to \code{\link[=as_biadjacency_matrix]{as_biadjacency_matrix()}} to create a more -consistent API. +\code{as_incidence_matrix()} was renamed to \code{\link[=as_biadjacency_matrix]{as_biadjacency_matrix()}} to create a more consistent API. } \details{ -Some authors refer to the bipartite adjacency matrix as the -"bipartite incidence matrix". igraph 1.6.0 and later does not use -this naming to avoid confusion with the edge-vertex incidence matrix. +Some authors refer to the bipartite adjacency matrix as the "bipartite incidence matrix". igraph 1.6.0 and later does not use this naming to avoid confusion with the edge-vertex incidence matrix. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Bipartite.html#igraph_get_biadjacency}{\code{get_biadjacency()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_edgelist}{\code{get_edgelist()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/as_long_data_frame.Rd b/man/as_long_data_frame.Rd index b15ef7acaa7..142f7a2012d 100644 --- a/man/as_long_data_frame.Rd +++ b/man/as_long_data_frame.Rd @@ -13,14 +13,11 @@ as_long_data_frame(graph) A long data frame. } \description{ -A long data frame contains all metadata about both the vertices -and edges of the graph. It contains one row for each edge, and -all metadata about that edge and its incident vertices are included -in that row. The names of the columns that contain the metadata -of the incident vertices are prefixed with \code{from_} and \code{to_}. -The first two columns are always named \code{from} and \code{to} and -they contain the numeric IDs of the incident vertices. The rows are -listed in the order of numeric vertex IDs. +A long data frame contains all metadata about both the vertices and edges of the graph. +It contains one row for each edge, and all metadata about that edge and its incident vertices are included in that row. +The names of the columns that contain the metadata of the incident vertices are prefixed with \code{from_} and \code{to_}. +The first two columns are always named \code{from} and \code{to} and they contain the numeric IDs of the incident vertices. +The rows are listed in the order of numeric vertex IDs. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_edgelist}{\code{get_edgelist()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/as_membership.Rd b/man/as_membership.Rd index 3ad183a4306..b9a704448ab 100644 --- a/man/as_membership.Rd +++ b/man/as_membership.Rd @@ -13,9 +13,8 @@ as_membership(x) The input vector, with the \code{membership} class added. } \description{ -This is useful if you want to use functions defined on -membership vectors, but your membership vector does not -come from an igraph clustering method. +This is useful if you want to use functions defined on membership vectors, +but your membership vector does not come from an igraph clustering method. } \examples{ ## Compare to the correct clustering diff --git a/man/as_phylo.Rd b/man/as_phylo.Rd index 12eb27d4eea..178d08906f3 100644 --- a/man/as_phylo.Rd +++ b/man/as_phylo.Rd @@ -14,7 +14,6 @@ as_phylo(x, ...) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{as_phylo} methods were renamed \code{as.phylo} -for more consistency with other R methods. +\code{as_phylo} methods were renamed \code{as.phylo} for more consistency with other R methods. } \keyword{internal} diff --git a/man/assortativity.Rd b/man/assortativity.Rd index dde0c7e7940..0714ee3f9a0 100644 --- a/man/assortativity.Rd +++ b/man/assortativity.Rd @@ -28,61 +28,51 @@ assortativity_degree(graph, ..., directed = TRUE) \item{...}{These dots are for future extensions and must be empty.} -\item{values.in}{A second value vector to use for the incoming edges when -calculating assortativity for a directed graph. -Supply \code{NULL} here if -you want to use the same values for outgoing and incoming edges. -This -argument is ignored (with a warning) if it is not \code{NULL} and undirected -assortativity coefficient is being calculated.} - -\item{directed}{Logical, whether to consider edge directions for -directed graphs. +\item{values.in}{A second value vector to use for the incoming edges when calculating assortativity for a directed graph. +Supply \code{NULL} here if you want to use the same values for outgoing and incoming edges. +This argument is ignored (with a warning) if it is not \code{NULL} and undirected assortativity coefficient is being calculated.} + +\item{directed}{Logical, whether to consider edge directions for directed graphs. This argument is ignored for undirected graphs. -Supply -\code{TRUE} here to do the natural thing, i.e. use directed version of the -measure for directed graphs and the undirected version for undirected -graphs.} +Supply \code{TRUE} here to do the natural thing, +i.e. use directed version of the measure for directed graphs and the undirected version for undirected graphs.} \item{normalized}{Logical, whether to compute the normalized assortativity. The non-normalized nominal assortativity is identical to modularity. -The non-normalized value-based assortativity is simply the covariance of the -values at the two ends of edges.} +The non-normalized value-based assortativity is simply the covariance of the values at the two ends of edges.} -\item{types1, types2}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -Deprecated aliases for \code{values} and \code{values.in}, respectively.} +\item{types1, types2}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Deprecated aliases for \code{values} and \code{values.in}, respectively.} -\item{types}{Vector giving the vertex types. They as assumed to be integer -numbers, starting with one. Non-integer values are converted to integers -with \code{\link[=as.integer]{as.integer()}}. Character vectors are converted to integers using -\code{\link[=as.factor]{as.factor()}}.} +\item{types}{Vector giving the vertex types. +They as assumed to be integer numbers, starting with one. +Non-integer values are converted to integers with \code{\link[=as.integer]{as.integer()}}. +Character vectors are converted to integers using \code{\link[=as.factor]{as.factor()}}.} } \value{ A single real number. } \description{ -The assortativity coefficient is positive if similar vertices (based on some -external property) tend to connect to each, and negative otherwise. +The assortativity coefficient is positive if similar vertices (based on some external property) tend to connect to each, +and negative otherwise. } \details{ -The assortativity coefficient measures the level of homophyly of the graph, -based on some vertex labeling or values assigned to vertices. If the -coefficient is high, that means that connected vertices tend to have the -same labels or similar assigned values. +The assortativity coefficient measures the level of homophyly of the graph, based on some vertex labeling or values assigned to vertices. +If the coefficient is high, that means that connected vertices tend to have the same labels or similar assigned values. -M.E.J. Newman defined two kinds of assortativity coefficients, the first one -is for categorical labels of vertices. \code{assortativity_nominal()} -calculates this measure. It is defined as +M.E.J. +Newman defined two kinds of assortativity coefficients, the first one is for categorical labels of vertices. +\code{assortativity_nominal()} calculates this measure. +It is defined as \deqn{r=\frac{\sum_i e_{ii}-\sum_i a_i b_i}{1-\sum_i a_i b_i}}{ r=(sum(e(i,i), i) - sum(a(i)b(i), i)) / (1 - sum(a(i)b(i), i))} -where \eqn{e_{ij}}{e(i,j)} is the fraction of edges connecting vertices of -type \eqn{i} and \eqn{j}, \eqn{a_i=\sum_j e_{ij}}{a(i)=sum(e(i,j), j)} and -\eqn{b_j=\sum_i e_{ij}}{b(j)=sum(e(i,j), i)}. +where \eqn{e_{ij}}{e(i,j)} is the fraction of edges connecting vertices of type \eqn{i} and \eqn{j}, +\eqn{a_i=\sum_j e_{ij}}{a(i)=sum(e(i,j), j)} and \eqn{b_j=\sum_i e_{ij}}{b(j)=sum(e(i,j), i)}. -The second assortativity variant is based on values assigned to the -vertices. \code{assortativity()} calculates this measure. It is defined as +The second assortativity variant is based on values assigned to the vertices. +\code{assortativity()} calculates this measure. +It is defined as \deqn{r=\frac1{\sigma_q^2}\sum_{jk} jk(e_{jk}-q_j q_k)}{ sum(jk(e(j,k)-q(j)q(k)), j, k) / sigma(q)^2} @@ -92,18 +82,15 @@ for undirected graphs (\eqn{q_i=\sum_j e_{ij}}{q(i)=sum(e(i,j), j)}) and as \deqn{r=\frac1{\sigma_o\sigma_i}\sum_{jk}jk(e_{jk}-q_j^o q_k^i)}{ sum(jk(e(j,k)-qout(j)qin(k)), j, k) / sigma(qin) / sigma(qout) } -for directed ones. Here \eqn{q_i^o=\sum_j e_{ij}}{qout(i)=sum(e(i,j), j)}, -\eqn{q_i^i=\sum_j e_{ji}}{qin(i)=sum(e(j,i), j)}, moreover, -\eqn{\sigma_q}{\sigma(q)}, \eqn{\sigma_o}{\sigma(qout)} and -\eqn{\sigma_i}{\sigma(qin)} are the standard deviations of \eqn{q}, +for directed ones. +Here \eqn{q_i^o=\sum_j e_{ij}}{qout(i)=sum(e(i,j), j)}, \eqn{q_i^i=\sum_j e_{ji}}{qin(i)=sum(e(j,i), j)}, moreover, +\eqn{\sigma_q}{\sigma(q)}, \eqn{\sigma_o}{\sigma(qout)} and \eqn{\sigma_i}{\sigma(qin)} are the standard deviations of \eqn{q}, \eqn{q^o}{qout} and \eqn{q^i}{qin}, respectively. -The reason of the difference is that in directed networks the relationship -is not symmetric, so it is possible to assign different values to the -outgoing and the incoming end of the edges. +The reason of the difference is that in directed networks the relationship is not symmetric, +so it is possible to assign different values to the outgoing and the incoming end of the edges. -\code{assortativity_degree()} uses vertex degree as vertex values -and calls \code{assortativity()}. +\code{assortativity_degree()} uses vertex degree as vertex values and calls \code{assortativity()}. Undirected graphs are effectively treated as directed ones with all-reciprocal edges. Thus, self-loops are taken into account twice in undirected graphs. diff --git a/man/assortativity.degree.Rd b/man/assortativity.degree.Rd index 1c2be5594f9..1bad9439091 100644 --- a/man/assortativity.degree.Rd +++ b/man/assortativity.degree.Rd @@ -9,19 +9,15 @@ assortativity.degree(graph, directed = TRUE) \arguments{ \item{graph}{The input graph, it can be directed or undirected.} -\item{directed}{Logical, whether to consider edge directions for -directed graphs. +\item{directed}{Logical, whether to consider edge directions for directed graphs. This argument is ignored for undirected graphs. -Supply -\code{TRUE} here to do the natural thing, i.e. use directed version of the -measure for directed graphs and the undirected version for undirected -graphs.} +Supply \code{TRUE} here to do the natural thing, +i.e. use directed version of the measure for directed graphs and the undirected version for undirected graphs.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{assortativity.degree()} was renamed to \code{\link[=assortativity_degree]{assortativity_degree()}} to create a more -consistent API. +\code{assortativity.degree()} was renamed to \code{\link[=assortativity_degree]{assortativity_degree()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_assortativity_degree}{\code{assortativity_degree()}} diff --git a/man/assortativity.nominal.Rd b/man/assortativity.nominal.Rd index 83d39e590ae..06e3c7d468d 100644 --- a/man/assortativity.nominal.Rd +++ b/man/assortativity.nominal.Rd @@ -9,29 +9,24 @@ assortativity.nominal(graph, types, directed = TRUE, normalized = TRUE) \arguments{ \item{graph}{The input graph, it can be directed or undirected.} -\item{types}{Vector giving the vertex types. They as assumed to be integer -numbers, starting with one. Non-integer values are converted to integers -with \code{\link[=as.integer]{as.integer()}}. Character vectors are converted to integers using -\code{\link[=as.factor]{as.factor()}}.} +\item{types}{Vector giving the vertex types. +They as assumed to be integer numbers, starting with one. +Non-integer values are converted to integers with \code{\link[=as.integer]{as.integer()}}. +Character vectors are converted to integers using \code{\link[=as.factor]{as.factor()}}.} -\item{directed}{Logical, whether to consider edge directions for -directed graphs. +\item{directed}{Logical, whether to consider edge directions for directed graphs. This argument is ignored for undirected graphs. -Supply -\code{TRUE} here to do the natural thing, i.e. use directed version of the -measure for directed graphs and the undirected version for undirected -graphs.} +Supply \code{TRUE} here to do the natural thing, +i.e. use directed version of the measure for directed graphs and the undirected version for undirected graphs.} \item{normalized}{Logical, whether to compute the normalized assortativity. The non-normalized nominal assortativity is identical to modularity. -The non-normalized value-based assortativity is simply the covariance of the -values at the two ends of edges.} +The non-normalized value-based assortativity is simply the covariance of the values at the two ends of edges.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{assortativity.nominal()} was renamed to \code{\link[=assortativity_nominal]{assortativity_nominal()}} to create a more -consistent API. +\code{assortativity.nominal()} was renamed to \code{\link[=assortativity_nominal]{assortativity_nominal()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_assortativity_nominal}{\code{assortativity_nominal()}} diff --git a/man/asymmetric.preference.game.Rd b/man/asymmetric.preference.game.Rd index a25892561c8..ec836b9a55f 100644 --- a/man/asymmetric.preference.game.Rd +++ b/man/asymmetric.preference.game.Rd @@ -17,21 +17,20 @@ asymmetric.preference.game( \item{types}{The number of different vertex types.} -\item{type.dist.matrix}{The joint distribution of the in- and out-vertex -types. The default \code{NULL} gives a uniform distribution.} +\item{type.dist.matrix}{The joint distribution of the in- and out-vertex types. +The default \code{NULL} gives a uniform distribution.} -\item{pref.matrix}{A square matrix giving the preferences of the vertex -types. The matrix has \sQuote{types} rows and columns. When generating -an undirected graph, it must be symmetric. The default \code{NULL} sets all -preferences to one.} +\item{pref.matrix}{A square matrix giving the preferences of the vertex types. +The matrix has \sQuote{types} rows and columns. +When generating an undirected graph, it must be symmetric. +The default \code{NULL} sets all preferences to one.} \item{loops}{Logical, whether self-loops are allowed in the graph.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{asymmetric.preference.game()} was renamed to \code{\link[=sample_asym_pref]{sample_asym_pref()}} to create a more -consistent API. +\code{asymmetric.preference.game()} was renamed to \code{\link[=sample_asym_pref]{sample_asym_pref()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_asymmetric_preference_game}{\code{asymmetric_preference_game()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/authority.score.Rd b/man/authority.score.Rd index 2f2ba4666d5..bb82bb5e03d 100644 --- a/man/authority.score.Rd +++ b/man/authority.score.Rd @@ -14,24 +14,20 @@ authority.score( \arguments{ \item{graph}{The input graph.} -\item{scale}{Logical, whether to scale the result to have a maximum -score of one. If no scaling is used then the result vector has unit length -in the Euclidean norm.} +\item{scale}{Logical, whether to scale the result to have a maximum score of one. +If no scaling is used then the result vector has unit length in the Euclidean norm.} -\item{weights}{Optional positive weight vector for calculating weighted -scores. If the graph has a \code{weight} edge attribute, then this is used -by default. -This function interprets edge weights as connection strengths. In the -random surfer model, an edge with a larger weight is more likely to be -selected by the surfer.} +\item{weights}{Optional positive weight vector for calculating weighted scores. +If the graph has a \code{weight} edge attribute, then this is used by default. +This function interprets edge weights as connection strengths. +In the random surfer model, an edge with a larger weight is more likely to be selected by the surfer.} -\item{options}{A named list, to override some ARPACK options. See -\code{\link[=arpack]{arpack()}} for details.} +\item{options}{A named list, to override some ARPACK options. +See \code{\link[=arpack]{arpack()}} for details.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{authority.score()} was renamed to \code{\link[=authority_score]{authority_score()}} to create a more -consistent API. +\code{authority.score()} was renamed to \code{\link[=authority_score]{authority_score()}} to create a more consistent API. } \keyword{internal} diff --git a/man/autocurve.edges.Rd b/man/autocurve.edges.Rd index 536f641bc4b..59f11bc39d4 100644 --- a/man/autocurve.edges.Rd +++ b/man/autocurve.edges.Rd @@ -9,14 +9,13 @@ autocurve.edges(graph, start = 0.5) \arguments{ \item{graph}{The input graph.} -\item{start}{The curvature at the two extreme edges. All edges will have a -curvature between \code{-start} and \code{start}, spaced equally.} +\item{start}{The curvature at the two extreme edges. +All edges will have a curvature between \code{-start} and \code{start}, spaced equally.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{autocurve.edges()} was renamed to \code{\link[=curve_multiple]{curve_multiple()}} to create a more -consistent API. +\code{autocurve.edges()} was renamed to \code{\link[=curve_multiple]{curve_multiple()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_edgelist}{\code{get_edgelist()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/automorphism_group.Rd b/man/automorphism_group.Rd index ad0087f2356..b4a53d0c3b0 100644 --- a/man/automorphism_group.Rd +++ b/man/automorphism_group.Rd @@ -15,18 +15,16 @@ automorphism_group( \arguments{ \item{graph}{The input graph, it is treated as undirected.} -\item{colors}{The colors of the individual vertices of the graph; only -vertices having the same color are allowed to match each other in an -automorphism. When omitted, igraph uses the \code{color} attribute of the -vertices, or, if there is no such vertex attribute, it simply assumes that -all vertices have the same color. Pass NULL explicitly if the graph has a -\code{color} vertex attribute but you do not want to use it.} +\item{colors}{The colors of the individual vertices of the graph; +only vertices having the same color are allowed to match each other in an automorphism. +When omitted, igraph uses the \code{color} attribute of the vertices, or, if there is no such vertex attribute, +it simply assumes that all vertices have the same color. +Pass NULL explicitly if the graph has a \code{color} vertex attribute but you do not want to use it.} \item{...}{These dots are for future extensions and must be empty.} -\item{sh}{The splitting heuristics for the BLISS algorithm. Possible values -are: -\sQuote{\code{f}}: +\item{sh}{The splitting heuristics for the BLISS algorithm. +Possible values are: \sQuote{\code{f}}: first non-singleton cell, \sQuote{\code{fl}}: first largest non-singleton cell, @@ -41,12 +39,11 @@ non-trivially connected non-singleton cell, \sQuote{\code{fsm}}: first smallest maximally non-trivially connected non-singleton cell.} -\item{details}{Specifies whether to provide additional details about the -BLISS internals in the result.} +\item{details}{Specifies whether to provide additional details about the BLISS internals in the result.} } \value{ -When \code{details} is \code{FALSE}, a list of vertex permutations -that form a generating set of the automorphism group of the input graph. +When \code{details} is \code{FALSE}, +a list of vertex permutations that form a generating set of the automorphism group of the input graph. When \code{details} is \code{TRUE}, a named list with two members: \describe{ \item{generators}{ @@ -62,17 +59,13 @@ See \code{\link[=count_automorphisms]{count_automorphisms()}} for more details. Compute the generating set of the automorphism group of a graph. } \details{ -An automorphism of a graph is a permutation of its vertices which brings the -graph into itself. The automorphisms of a graph form a group and there exists -a subset of this group (i.e. a set of permutations) such that every other -permutation can be expressed as a combination of these permutations. These -permutations are called the generating set of the automorphism group. +An automorphism of a graph is a permutation of its vertices which brings the graph into itself. +The automorphisms of a graph form a group and there exists a subset of this group (i.e. a set of permutations) such that every other permutation can be expressed as a combination of these permutations. +These permutations are called the generating set of the automorphism group. -This function calculates a possible generating set of the automorphism of -a graph using the BLISS algorithm. See also the BLISS homepage at -\url{http://www.tcs.hut.fi/Software/bliss/index.html}. The calculated -generating set is not necessarily minimal, and it may depend on the splitting -heuristics used by BLISS. +This function calculates a possible generating set of the automorphism of a graph using the BLISS algorithm. +See also the BLISS homepage at \url{http://www.tcs.hut.fi/Software/bliss/index.html}. +The calculated generating set is not necessarily minimal, and it may depend on the splitting heuristics used by BLISS. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Isomorphism.html#igraph_automorphism_group}{\code{automorphism_group()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/automorphisms.Rd b/man/automorphisms.Rd index c04952a9838..96573de3f3f 100644 --- a/man/automorphisms.Rd +++ b/man/automorphisms.Rd @@ -13,16 +13,14 @@ automorphisms( \arguments{ \item{graph}{The input graph, it is treated as undirected.} -\item{colors}{The colors of the individual vertices of the graph; only -vertices having the same color are allowed to match each other in an -automorphism. When omitted, igraph uses the \code{color} attribute of the -vertices, or, if there is no such vertex attribute, it simply assumes that -all vertices have the same color. Pass NULL explicitly if the graph has a -\code{color} vertex attribute but you do not want to use it.} +\item{colors}{The colors of the individual vertices of the graph; +only vertices having the same color are allowed to match each other in an automorphism. +When omitted, igraph uses the \code{color} attribute of the vertices, or, if there is no such vertex attribute, +it simply assumes that all vertices have the same color. +Pass NULL explicitly if the graph has a \code{color} vertex attribute but you do not want to use it.} -\item{sh}{The splitting heuristics for the BLISS algorithm. Possible values -are: -\sQuote{\code{f}}: +\item{sh}{The splitting heuristics for the BLISS algorithm. +Possible values are: \sQuote{\code{f}}: first non-singleton cell, \sQuote{\code{fl}}: first largest non-singleton cell, @@ -40,8 +38,7 @@ first smallest maximally non-trivially connected non-singleton cell.} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{automorphisms()} was renamed to \code{\link[=count_automorphisms]{count_automorphisms()}} to create a more -consistent API. +\code{automorphisms()} was renamed to \code{\link[=count_automorphisms]{count_automorphisms()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Isomorphism.html#igraph_count_automorphisms}{\code{count_automorphisms()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/average.path.length.Rd b/man/average.path.length.Rd index f2fb38059ee..adbdd4d7494 100644 --- a/man/average.path.length.Rd +++ b/man/average.path.length.Rd @@ -15,31 +15,26 @@ average.path.length( \arguments{ \item{graph}{The graph to work on.} -\item{weights}{Possibly a numeric vector giving edge weights. If this is -\code{NULL} and the graph has a \code{weight} edge attribute, then the -attribute is used. If this is \code{NA} then no weights are used (even if -the graph has a \code{weight} attribute). In a weighted graph, the length -of a path is the sum of the weights of its constituent edges.} +\item{weights}{Possibly a numeric vector giving edge weights. +If this is \code{NULL} and the graph has a \code{weight} edge attribute, then the attribute is used. +If this is \code{NA} then no weights are used (even if the graph has a \code{weight} attribute). +In a weighted graph, the length of a path is the sum of the weights of its constituent edges.} \item{directed}{Whether to consider directed paths in directed graphs, this argument is ignored for undirected graphs.} -\item{unconnected}{What to do if the graph is unconnected (not -strongly connected if directed paths are considered). If TRUE, only -the lengths of the existing paths are considered and averaged; if -FALSE, the length of the missing paths are considered as having infinite -length, making the mean distance infinite as well.} +\item{unconnected}{What to do if the graph is unconnected (not strongly connected if directed paths are considered). +If TRUE, only the lengths of the existing paths are considered and averaged; if FALSE, +the length of the missing paths are considered as having infinite length, making the mean distance infinite as well.} \item{details}{Whether to provide additional details in the result. -Functions accepting this argument (like \code{mean_distance()}) return -additional information like the number of disconnected vertex pairs in -the result when this parameter is set to \code{TRUE}.} +Functions accepting this argument (like \code{mean_distance()}) return additional information like the number of disconnected vertex pairs in the result +when this parameter is set to \code{TRUE}.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{average.path.length()} was renamed to \code{\link[=mean_distance]{mean_distance()}} to create a more -consistent API. +\code{average.path.length()} was renamed to \code{\link[=mean_distance]{mean_distance()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_average_path_length_dijkstra}{\code{average_path_length_dijkstra()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/ba.game.Rd b/man/ba.game.Rd index 3e36c4dcfd1..e362ba0e21e 100644 --- a/man/ba.game.Rd +++ b/man/ba.game.Rd @@ -24,52 +24,42 @@ ba.game( i.e. linear preferential attachment.} \item{m}{Numeric constant, the number of edges to add in each time step, -defaults to 1. -This argument is only used if both \code{out.dist} and \code{out.seq} are omitted -or NULL.} +defaults to 1. This argument is only used if both \code{out.dist} and \code{out.seq} are omitted or NULL.} -\item{out.dist}{Numeric vector, the distribution of the number of edges to -add in each time step. This argument is only used if the \code{out.seq} -argument is omitted or NULL.} +\item{out.dist}{Numeric vector, the distribution of the number of edges to add in each time step. +This argument is only used if the \code{out.seq} argument is omitted or NULL.} -\item{out.seq}{Numeric vector giving the number of edges to add in each time -step. Its first element is ignored as no edges are added in the first time -step.} +\item{out.seq}{Numeric vector giving the number of edges to add in each time step. +Its first element is ignored as no edges are added in the first time step.} -\item{out.pref}{Logical, if true the total degree is used for calculating -the citation probability, otherwise the in-degree is used.} +\item{out.pref}{Logical, if true the total degree is used for calculating the citation probability, otherwise the in-degree is used.} -\item{zero.appeal}{The \sQuote{attractiveness} of the vertices with no -adjacent edges. See details below.} +\item{zero.appeal}{The \sQuote{attractiveness} of the vertices with no adjacent edges. +See details below.} \item{directed}{Whether to create a directed graph.} \item{algorithm}{The algorithm to use for the graph generation. -\code{psumtree} uses a partial prefix-sum tree to generate the graph, this -algorithm can handle any \code{power} and \code{zero.appeal} values and -never generates multiple edges. \code{psumtree-multiple} also uses a -partial prefix-sum tree, but the generation of multiple edges is allowed. -Before the 0.6 version igraph used this algorithm if \code{power} was not -one, or \code{zero.appeal} was not one. \code{bag} is the algorithm that -was previously (before version 0.6) used if \code{power} was one and -\code{zero.appeal} was one as well. It works by putting the IDs of the -vertices into a bag (multiset, really), exactly as many times as their -(in-)degree, plus once more. Then the required number of cited vertices are -drawn from the bag, with replacement. This method might generate multiple -edges. It only works if \code{power} and \code{zero.appeal} are equal one.} +\code{psumtree} uses a partial prefix-sum tree to generate the graph, +this algorithm can handle any \code{power} and \code{zero.appeal} values and never generates multiple edges. +\code{psumtree-multiple} also uses a partial prefix-sum tree, but the generation of multiple edges is allowed. +Before the 0.6 version igraph used this algorithm if \code{power} was not one, or \code{zero.appeal} was not one. +\code{bag} is the algorithm that was previously (before version 0.6) used if \code{power} was one and \code{zero.appeal} was one as well. +It works by putting the IDs of the vertices into a bag (multiset, really), exactly as many times as their (in-)degree, plus once more. +Then the required number of cited vertices are drawn from the bag, with replacement. +This method might generate multiple edges. +It only works if \code{power} and \code{zero.appeal} are equal one.} -\item{start.graph}{\code{NULL} or an igraph graph. If a graph, then the -supplied graph is used as a starting graph for the preferential attachment -algorithm. The graph should have at least one vertex. If a graph is supplied -here and the \code{out.seq} argument is not \code{NULL}, then it should -contain the out degrees of the new vertices only, not the ones in the -\code{start.graph}.} +\item{start.graph}{\code{NULL} or an igraph graph. +If a graph, then the supplied graph is used as a starting graph for the preferential attachment algorithm. +The graph should have at least one vertex. +If a graph is supplied here and the \code{out.seq} argument is not \code{NULL}, then it should contain the out degrees of the new vertices only, +not the ones in the \code{start.graph}.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{ba.game()} was renamed to \code{\link[=sample_pa]{sample_pa()}} to create a more -consistent API. +\code{ba.game()} was renamed to \code{\link[=sample_pa]{sample_pa()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_barabasi_game}{\code{barabasi_game()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/barabasi.game.Rd b/man/barabasi.game.Rd index bd290d644bb..00e70a02fe7 100644 --- a/man/barabasi.game.Rd +++ b/man/barabasi.game.Rd @@ -24,52 +24,42 @@ barabasi.game( i.e. linear preferential attachment.} \item{m}{Numeric constant, the number of edges to add in each time step, -defaults to 1. -This argument is only used if both \code{out.dist} and \code{out.seq} are omitted -or NULL.} +defaults to 1. This argument is only used if both \code{out.dist} and \code{out.seq} are omitted or NULL.} -\item{out.dist}{Numeric vector, the distribution of the number of edges to -add in each time step. This argument is only used if the \code{out.seq} -argument is omitted or NULL.} +\item{out.dist}{Numeric vector, the distribution of the number of edges to add in each time step. +This argument is only used if the \code{out.seq} argument is omitted or NULL.} -\item{out.seq}{Numeric vector giving the number of edges to add in each time -step. Its first element is ignored as no edges are added in the first time -step.} +\item{out.seq}{Numeric vector giving the number of edges to add in each time step. +Its first element is ignored as no edges are added in the first time step.} -\item{out.pref}{Logical, if true the total degree is used for calculating -the citation probability, otherwise the in-degree is used.} +\item{out.pref}{Logical, if true the total degree is used for calculating the citation probability, otherwise the in-degree is used.} -\item{zero.appeal}{The \sQuote{attractiveness} of the vertices with no -adjacent edges. See details below.} +\item{zero.appeal}{The \sQuote{attractiveness} of the vertices with no adjacent edges. +See details below.} \item{directed}{Whether to create a directed graph.} \item{algorithm}{The algorithm to use for the graph generation. -\code{psumtree} uses a partial prefix-sum tree to generate the graph, this -algorithm can handle any \code{power} and \code{zero.appeal} values and -never generates multiple edges. \code{psumtree-multiple} also uses a -partial prefix-sum tree, but the generation of multiple edges is allowed. -Before the 0.6 version igraph used this algorithm if \code{power} was not -one, or \code{zero.appeal} was not one. \code{bag} is the algorithm that -was previously (before version 0.6) used if \code{power} was one and -\code{zero.appeal} was one as well. It works by putting the IDs of the -vertices into a bag (multiset, really), exactly as many times as their -(in-)degree, plus once more. Then the required number of cited vertices are -drawn from the bag, with replacement. This method might generate multiple -edges. It only works if \code{power} and \code{zero.appeal} are equal one.} +\code{psumtree} uses a partial prefix-sum tree to generate the graph, +this algorithm can handle any \code{power} and \code{zero.appeal} values and never generates multiple edges. +\code{psumtree-multiple} also uses a partial prefix-sum tree, but the generation of multiple edges is allowed. +Before the 0.6 version igraph used this algorithm if \code{power} was not one, or \code{zero.appeal} was not one. +\code{bag} is the algorithm that was previously (before version 0.6) used if \code{power} was one and \code{zero.appeal} was one as well. +It works by putting the IDs of the vertices into a bag (multiset, really), exactly as many times as their (in-)degree, plus once more. +Then the required number of cited vertices are drawn from the bag, with replacement. +This method might generate multiple edges. +It only works if \code{power} and \code{zero.appeal} are equal one.} -\item{start.graph}{\code{NULL} or an igraph graph. If a graph, then the -supplied graph is used as a starting graph for the preferential attachment -algorithm. The graph should have at least one vertex. If a graph is supplied -here and the \code{out.seq} argument is not \code{NULL}, then it should -contain the out degrees of the new vertices only, not the ones in the -\code{start.graph}.} +\item{start.graph}{\code{NULL} or an igraph graph. +If a graph, then the supplied graph is used as a starting graph for the preferential attachment algorithm. +The graph should have at least one vertex. +If a graph is supplied here and the \code{out.seq} argument is not \code{NULL}, then it should contain the out degrees of the new vertices only, +not the ones in the \code{start.graph}.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{barabasi.game()} was renamed to \code{\link[=sample_pa]{sample_pa()}} to create a more -consistent API. +\code{barabasi.game()} was renamed to \code{\link[=sample_pa]{sample_pa()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_barabasi_game}{\code{barabasi_game()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/betweenness.Rd b/man/betweenness.Rd index f8dbd6d4a34..094484f06fa 100644 --- a/man/betweenness.Rd +++ b/man/betweenness.Rd @@ -34,42 +34,34 @@ The default \code{NULL} selects all vertices.} \item{...}{These dots are for future extensions and must be empty.} -\item{directed}{Logical, whether directed paths should be considered while -determining the shortest paths.} +\item{directed}{Logical, whether directed paths should be considered while determining the shortest paths.} -\item{weights}{Optional positive weight vector for calculating weighted -betweenness. If the graph has a \code{weight} edge attribute, then this is -used by default. Weights are used to calculate weighted shortest paths, -so they are interpreted as distances.} +\item{weights}{Optional positive weight vector for calculating weighted betweenness. +If the graph has a \code{weight} edge attribute, then this is used by default. +Weights are used to calculate weighted shortest paths, so they are interpreted as distances.} -\item{normalized}{Logical, whether to normalize the betweenness -scores. If \code{TRUE}, then the results are normalized by the number of ordered -or unordered vertex pairs in directed and undirected graphs, respectively. +\item{normalized}{Logical, whether to normalize the betweenness scores. +If \code{TRUE}, +then the results are normalized by the number of ordered or unordered vertex pairs in directed and undirected graphs, respectively. In an undirected graph, \deqn{B^n=\frac{2B}{(n-1)(n-2)},}{Bnorm=2 B / ((n-1)(n-2)),} -where -\eqn{B^n}{Bnorm} is the normalized, \eqn{B} the raw betweenness, and -\eqn{n} is the number of vertices in the graph. Note that the same -normalization factor is used even when setting a \code{cutoff} on the considered -shortest path lengths, even though the number of vertex pairs reachable -from each other may be less than \eqn{(n-1)(n-2)/2}.} +where \eqn{B^n}{Bnorm} is the normalized, \eqn{B} the raw betweenness, and \eqn{n} is the number of vertices in the graph. +Note that the same normalization factor is used even when setting a \code{cutoff} on the considered shortest path lengths, +even though the number of vertex pairs reachable from each other may be less than \eqn{(n-1)(n-2)/2}.} -\item{cutoff}{The maximum shortest path length to consider when calculating -betweenness. If negative, then there is no such limit.} +\item{cutoff}{The maximum shortest path length to consider when calculating betweenness. +If negative, then there is no such limit.} \item{e}{The edges for which the edge betweenness will be calculated. The default \code{NULL} selects all edges.} } \value{ -A numeric vector with the betweenness score for each vertex in -\code{v} for \code{betweenness()}. +A numeric vector with the betweenness score for each vertex in \code{v} for \code{betweenness()}. -A numeric vector with the edge betweenness score for each edge in \code{e} -for \code{edge_betweenness()}. +A numeric vector with the edge betweenness score for each edge in \code{e} for \code{edge_betweenness()}. } \description{ -The vertex and edge betweenness are (roughly) defined by the number of -geodesics (shortest paths) going through a vertex or an edge. +The vertex and edge betweenness are (roughly) defined by the number of geodesics (shortest paths) going through a vertex or an edge. } \details{ The vertex betweenness of vertex \code{v} is defined by @@ -81,26 +73,20 @@ The edge betweenness of edge \code{e} is defined by \deqn{\sum_{i\ne j} g_{iej}/g_{ij}.}{sum( g_iej / g_ij, i!=j).} -\code{betweenness()} calculates vertex betweenness, \code{edge_betweenness()} -calculates edge betweenness. +\code{betweenness()} calculates vertex betweenness, \code{edge_betweenness()} calculates edge betweenness. -Here \eqn{g_{ij}}{g_ij} is the total number of shortest paths between vertices -\eqn{i} and \eqn{j} while \eqn{g_{ivj}} is the number of those shortest paths -which pass though vertex \eqn{v}. +Here \eqn{g_{ij}}{g_ij} is the total number of shortest paths between vertices \eqn{i} and \eqn{j} +while \eqn{g_{ivj}} is the number of those shortest paths which pass though vertex \eqn{v}. -Both functions allow you to consider only paths of length \code{cutoff} or -smaller; this can be run for larger graphs, as the running time is not -quadratic (if \code{cutoff} is small). If \code{cutoff} is negative (the default), -then the function calculates the exact betweenness scores. Since igraph 1.6.0, -a \code{cutoff} value of zero is treated literally, i.e. paths of length larger -than zero are ignored. +Both functions allow you to consider only paths of length \code{cutoff} or smaller; this can be run for larger graphs, +as the running time is not quadratic (if \code{cutoff} is small). +If \code{cutoff} is negative (the default), then the function calculates the exact betweenness scores. +Since igraph 1.6.0, a \code{cutoff} value of zero is treated literally, i.e. paths of length larger than zero are ignored. -For calculating the betweenness a similar algorithm to the one proposed by -Brandes (see References) is used. +For calculating the betweenness a similar algorithm to the one proposed by Brandes (see References) is used. } \note{ -\code{edge_betweenness()} might give false values for graphs with -multiple edges. +\code{edge_betweenness()} might give false values for graphs with multiple edges. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_betweenness_cutoff}{\code{betweenness_cutoff()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_is_directed}{\code{is_directed()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_edge_betweenness_cutoff}{\code{edge_betweenness_cutoff()}} diff --git a/man/bfs.Rd b/man/bfs.Rd index b18e9a28f94..abc62f2006c 100644 --- a/man/bfs.Rd +++ b/man/bfs.Rd @@ -27,27 +27,25 @@ bfs( \arguments{ \item{graph}{The input graph.} -\item{root}{Numeric vector, usually of length one. The root vertex, or root -vertices to start the search from. When several roots are given, they are -considered in the order they appear. If a root vertex was already reached -while searching from an earlier root, no separate search is started from -it, so it keeps the distance it was first found at rather than \code{0}.} +\item{root}{Numeric vector, usually of length one. +The root vertex, or root vertices to start the search from. +When several roots are given, they are considered in the order they appear. +If a root vertex was already reached while searching from an earlier root, no separate search is started from it, +so it keeps the distance it was first found at rather than \code{0}.} \item{mode}{For directed graphs specifies the type of edges to follow. -\sQuote{out} follows outgoing, \sQuote{in} incoming edges. \sQuote{all} -ignores edge directions completely. \sQuote{total} is a synonym for -\sQuote{all}. This argument is ignored for undirected graphs.} +\sQuote{out} follows outgoing, \sQuote{in} incoming edges. +\sQuote{all} ignores edge directions completely. +\sQuote{total} is a synonym for \sQuote{all}. +This argument is ignored for undirected graphs.} \item{...}{These dots are for future extensions and must be empty.} -\item{unreachable}{Logical, whether the search should visit the -vertices that are unreachable from the given root vertex (or vertices). If -\code{TRUE}, then additional searches are performed until all vertices are -visited.} +\item{unreachable}{Logical, whether the search should visit the vertices that are unreachable from the given root vertex (or vertices). +If \code{TRUE}, then additional searches are performed until all vertices are visited.} -\item{restricted}{\code{NULL} (=no restriction), or a vector of vertices -(IDs or symbolic names). In the latter case, the search is restricted to the -given vertices.} +\item{restricted}{\code{NULL} (=no restriction), or a vector of vertices (IDs or symbolic names). +In the latter case, the search is restricted to the given vertices.} \item{order}{Logical, whether to return the ordering of the vertices.} @@ -55,18 +53,16 @@ given vertices.} \item{parent}{Logical, whether to return the parent of the vertices.} -\item{pred}{Logical, whether to return the predecessors of the -vertices.} +\item{pred}{Logical, whether to return the predecessors of the vertices.} -\item{succ}{Logical, whether to return the successors of the -vertices.} +\item{succ}{Logical, whether to return the successors of the vertices.} -\item{dist}{Logical, whether to return the distance from the root of -the search tree.} +\item{dist}{Logical, whether to return the distance from the root of the search tree.} -\item{callback}{Callback function. This is called whenever a vertex is visited. -The callback function should return \code{FALSE} to continue the search -or \code{TRUE} to stop it. See details below. +\item{callback}{Callback function. +This is called whenever a vertex is visited. +The callback function should return \code{FALSE} to continue the search or \code{TRUE} to stop it. +See details below. Default: \code{NULL}.} \item{extra}{Additional argument to supply to the callback function.} @@ -74,8 +70,7 @@ Default: \code{NULL}.} \item{rho}{The environment in which the callback function is evaluated. The default \code{NULL} uses the caller's environment.} -\item{neimode}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} This argument is deprecated -from igraph 1.3.0; use \code{mode} instead.} +\item{neimode}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} This argument is deprecated from igraph 1.3.0; use \code{mode} instead.} \item{father}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{parent} instead.} } @@ -83,8 +78,8 @@ from igraph 1.3.0; use \code{mode} instead.} A named list with the following entries: \describe{ \item{root}{ -Numeric vector. The root vertex (or vertices) that was used as the -starting point of the search, as supplied in the \code{root} argument. +Numeric vector. +The root vertex (or vertices) that was used as the starting point of the search, as supplied in the \code{root} argument. } \item{neimode}{ Character scalar. The \code{mode} argument of the function call. @@ -122,13 +117,12 @@ Unreachable vertices have a negative distance as of igraph 1.6.0, this used to b } } -Note that \code{order}, \code{rank}, \code{parent}, \code{pred}, \code{succ} -and \code{dist} might be \code{NULL} if their corresponding argument is -\code{FALSE}, i.e. if their calculation is not requested. +Note that \code{order}, \code{rank}, \code{parent}, \code{pred}, \code{succ} and \code{dist} might be \code{NULL} if their corresponding argument is \code{FALSE}, +i.e. if their calculation is not requested. } \description{ -Breadth-first search is an algorithm to traverse a graph. We start from a -root vertex and spread along every edge \dQuote{simultaneously}. +Breadth-first search is an algorithm to traverse a graph. +We start from a root vertex and spread along every edge \dQuote{simultaneously}. } \details{ The callback function must have the following arguments: @@ -149,9 +143,8 @@ The extra argument. } } -The callback must return \code{FALSE} -to continue the search or \code{TRUE} to terminate it. See examples below on how to -use the callback function. +The callback must return \code{FALSE} to continue the search or \code{TRUE} to terminate it. +See examples below on how to use the callback function. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/biconnected.components.Rd b/man/biconnected.components.Rd index 43d62a46e92..c01d9268061 100644 --- a/man/biconnected.components.Rd +++ b/man/biconnected.components.Rd @@ -7,14 +7,13 @@ biconnected.components(graph) } \arguments{ -\item{graph}{The input graph. It is treated as an undirected graph, even if -it is directed.} +\item{graph}{The input graph. +It is treated as an undirected graph, even if it is directed.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{biconnected.components()} was renamed to \code{\link[=biconnected_components]{biconnected_components()}} to create a more -consistent API. +\code{biconnected.components()} was renamed to \code{\link[=biconnected_components]{biconnected_components()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_biconnected_components}{\code{biconnected_components()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/biconnected_components.Rd b/man/biconnected_components.Rd index edab1796bfc..ef28df2183f 100644 --- a/man/biconnected_components.Rd +++ b/man/biconnected_components.Rd @@ -7,8 +7,8 @@ biconnected_components(graph) } \arguments{ -\item{graph}{The input graph. It is treated as an undirected graph, even if -it is directed.} +\item{graph}{The input graph. +It is treated as an undirected graph, even if it is directed.} } \value{ A named list with three components: @@ -36,14 +36,12 @@ The articulation points of the graph. See \code{\link[=articulation_points]{arti Finding the biconnected components of a graph } \details{ -A graph is biconnected if the removal of any single vertex (and its adjacent -edges) does not disconnect it. +A graph is biconnected if the removal of any single vertex (and its adjacent edges) does not disconnect it. A biconnected component of a graph is a maximal biconnected subgraph of it. -The biconnected components of a graph can be given by the partition of its -edges: every edge is a member of exactly one biconnected component. Note -that this is not true for vertices: the same vertex can be part of many -biconnected components. +The biconnected components of a graph can be given by the partition of its edges: +every edge is a member of exactly one biconnected component. +Note that this is not true for vertices: the same vertex can be part of many biconnected components. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_biconnected_components}{\code{biconnected_components()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/bipartite.mapping.Rd b/man/bipartite.mapping.Rd index eae9cf6f060..b0931995d32 100644 --- a/man/bipartite.mapping.Rd +++ b/man/bipartite.mapping.Rd @@ -12,8 +12,7 @@ bipartite.mapping(graph) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{bipartite.mapping()} was renamed to \code{\link[=bipartite_mapping]{bipartite_mapping()}} to create a more -consistent API. +\code{bipartite.mapping()} was renamed to \code{\link[=bipartite_mapping]{bipartite_mapping()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Bipartite.html#igraph_is_bipartite}{\code{is_bipartite()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/bipartite.projection.Rd b/man/bipartite.projection.Rd index a841122f28d..fd5473fbe2d 100644 --- a/man/bipartite.projection.Rd +++ b/man/bipartite.projection.Rd @@ -14,39 +14,33 @@ bipartite.projection( ) } \arguments{ -\item{graph}{The input graph. It can be directed, but edge directions are -ignored during the computation.} +\item{graph}{The input graph. +It can be directed, but edge directions are ignored during the computation.} -\item{types}{An optional vertex type vector to use instead of the -\sQuote{\code{type}} vertex attribute. You must supply this argument if the -graph has no \sQuote{\code{type}} vertex attribute.} +\item{types}{An optional vertex type vector to use instead of the \sQuote{\code{type}} vertex attribute. +You must supply this argument if the graph has no \sQuote{\code{type}} vertex attribute.} -\item{multiplicity}{If \code{TRUE}, then igraph keeps the multiplicity of -the edges as an edge attribute called \sQuote{weight}. -E.g. if there is an A-C-B and also an A-D-B -triple in the bipartite graph (but no more X, such that A-X-B is also in the -graph), then the multiplicity of the A-B edge in the projection will be 2.} +\item{multiplicity}{If \code{TRUE}, then igraph keeps the multiplicity of the edges as an edge attribute called \sQuote{weight}. +E.g. if there is an A-C-B and also an A-D-B triple in the bipartite graph (but no more X, such that A-X-B is also in the graph), +then the multiplicity of the A-B edge in the projection will be 2.} -\item{probe1}{This argument can be used to specify the order of the -projections in the resulting list. If given, then it is considered as a -vertex ID (or a symbolic vertex name); the projection containing this vertex -will be the first one in the result list. This argument is ignored if only -one projection is requested in argument \code{which}.} +\item{probe1}{This argument can be used to specify the order of the projections in the resulting list. +If given, then it is considered as a vertex ID (or a symbolic vertex name); +the projection containing this vertex will be the first one in the result list. +This argument is ignored if only one projection is requested in argument \code{which}.} \item{which}{A character scalar to specify which projection(s) to calculate. The default is to calculate both.} -\item{remove.type}{Logical, whether to remove the \code{type} vertex -attribute from the projections. This makes sense because these graphs are -not bipartite any more. However if you want to combine them with each other -(or other bipartite graphs), then it is worth keeping this attribute. By -default it will be removed.} +\item{remove.type}{Logical, whether to remove the \code{type} vertex attribute from the projections. +This makes sense because these graphs are not bipartite any more. +However if you want to combine them with each other (or other bipartite graphs), then it is worth keeping this attribute. +By default it will be removed.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{bipartite.projection()} was renamed to \code{\link[=bipartite_projection]{bipartite_projection()}} to create a more -consistent API. +\code{bipartite.projection()} was renamed to \code{\link[=bipartite_projection]{bipartite_projection()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/bipartite.projection.size.Rd b/man/bipartite.projection.size.Rd index 1922a4b10a4..15bd86020ad 100644 --- a/man/bipartite.projection.size.Rd +++ b/man/bipartite.projection.size.Rd @@ -7,18 +7,16 @@ bipartite.projection.size(graph, types = NULL) } \arguments{ -\item{graph}{The input graph. It can be directed, but edge directions are -ignored during the computation.} +\item{graph}{The input graph. +It can be directed, but edge directions are ignored during the computation.} -\item{types}{An optional vertex type vector to use instead of the -\sQuote{\code{type}} vertex attribute. You must supply this argument if the -graph has no \sQuote{\code{type}} vertex attribute.} +\item{types}{An optional vertex type vector to use instead of the \sQuote{\code{type}} vertex attribute. +You must supply this argument if the graph has no \sQuote{\code{type}} vertex attribute.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{bipartite.projection.size()} was renamed to \code{\link[=bipartite_projection_size]{bipartite_projection_size()}} to create a more -consistent API. +\code{bipartite.projection.size()} was renamed to \code{\link[=bipartite_projection_size]{bipartite_projection_size()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Bipartite.html#igraph_bipartite_projection_size}{\code{bipartite_projection_size()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/bipartite.random.game.Rd b/man/bipartite.random.game.Rd index 8610754eae3..e9566046711 100644 --- a/man/bipartite.random.game.Rd +++ b/man/bipartite.random.game.Rd @@ -19,30 +19,29 @@ bipartite.random.game( \item{n2}{Integer scalar, the number of top vertices.} -\item{type}{Character scalar, the type of the graph, \sQuote{gnp} creates a -\eqn{G(n,p)} graph, \sQuote{gnm} creates a \eqn{G(n,m)} graph. See details below.} +\item{type}{Character scalar, the type of the graph, \sQuote{gnp} creates a \eqn{G(n,p)} graph, +\sQuote{gnm} creates a \eqn{G(n,m)} graph. +See details below.} -\item{p}{Real scalar, connection probability for \eqn{G(n,p)} graphs. Should not -be given for \eqn{G(n,m)} graphs.} +\item{p}{Real scalar, connection probability for \eqn{G(n,p)} graphs. +Should not be given for \eqn{G(n,m)} graphs.} -\item{m}{Integer scalar, the number of edges for \eqn{G(n,m)} graphs. Should not -be given for \eqn{G(n,p)} graphs.} +\item{m}{Integer scalar, the number of edges for \eqn{G(n,m)} graphs. +Should not be given for \eqn{G(n,p)} graphs.} -\item{directed}{Logical, whether to create a directed graph. See also -the \code{mode} argument.} +\item{directed}{Logical, whether to create a directed graph. +See also the \code{mode} argument.} -\item{mode}{Character scalar, specifies how to direct the edges in directed -graphs. If it is \sQuote{out}, then directed edges point from bottom -vertices to top vertices. If it is \sQuote{in}, edges point from top -vertices to bottom vertices. \sQuote{out} and \sQuote{in} do not generate -mutual edges. If this argument is \sQuote{all}, then each edge direction is -considered independently and mutual edges might be generated. This argument -is ignored for undirected graphs.} +\item{mode}{Character scalar, specifies how to direct the edges in directed graphs. +If it is \sQuote{out}, then directed edges point from bottom vertices to top vertices. +If it is \sQuote{in}, edges point from top vertices to bottom vertices. +\sQuote{out} and \sQuote{in} do not generate mutual edges. +If this argument is \sQuote{all}, then each edge direction is considered independently and mutual edges might be generated. +This argument is ignored for undirected graphs.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{bipartite.random.game()} was renamed to \code{\link[=sample_bipartite]{sample_bipartite()}} to create a more -consistent API. +\code{bipartite.random.game()} was renamed to \code{\link[=sample_bipartite]{sample_bipartite()}} to create a more consistent API. } \keyword{internal} diff --git a/man/bipartite_mapping.Rd b/man/bipartite_mapping.Rd index 16852b34d8c..c7e1adfd0c9 100644 --- a/man/bipartite_mapping.Rd +++ b/man/bipartite_mapping.Rd @@ -22,24 +22,20 @@ If no such mapping exists, then an empty vector. } } \description{ -This function decides whether the vertices of a network can be mapped to two -vertex types in a way that no vertices of the same type are connected. +This function decides whether the vertices of a network can be mapped to two vertex types in a way that no vertices of the same type are connected. } \details{ -A bipartite graph in igraph has a \sQuote{\code{type}} vertex attribute -giving the two vertex types. +A bipartite graph in igraph has a \sQuote{\code{type}} vertex attribute giving the two vertex types. -This function simply checks whether a graph \emph{could} be bipartite. It -tries to find a mapping that gives a possible division of the vertices into -two classes, such that no two vertices of the same class are connected by an -edge. +This function simply checks whether a graph \emph{could} be bipartite. +It tries to find a mapping that gives a possible division of the vertices into two classes, +such that no two vertices of the same class are connected by an edge. -The existence of such a mapping is equivalent of having no circuits of odd -length in the graph. A graph with loop edges cannot bipartite. +The existence of such a mapping is equivalent of having no circuits of odd length in the graph. +A graph with loop edges cannot bipartite. -Note that the mapping is not necessarily unique, e.g. if the graph has at -least two components, then the vertices in the separate components can be -mapped independently. +Note that the mapping is not necessarily unique, e.g. if the graph has at least two components, +then the vertices in the separate components can be mapped independently. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Bipartite.html#igraph_is_bipartite}{\code{is_bipartite()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/bipartite_projection.Rd b/man/bipartite_projection.Rd index 5d15d940311..1e307d4a497 100644 --- a/man/bipartite_projection.Rd +++ b/man/bipartite_projection.Rd @@ -18,56 +18,49 @@ bipartite_projection( bipartite_projection_size(graph, types = NULL) } \arguments{ -\item{graph}{The input graph. It can be directed, but edge directions are -ignored during the computation.} +\item{graph}{The input graph. +It can be directed, but edge directions are ignored during the computation.} -\item{types}{An optional vertex type vector to use instead of the -\sQuote{\code{type}} vertex attribute. You must supply this argument if the -graph has no \sQuote{\code{type}} vertex attribute.} +\item{types}{An optional vertex type vector to use instead of the \sQuote{\code{type}} vertex attribute. +You must supply this argument if the graph has no \sQuote{\code{type}} vertex attribute.} \item{...}{These dots are for future extensions and must be empty.} -\item{multiplicity}{If \code{TRUE}, then igraph keeps the multiplicity of -the edges as an edge attribute called \sQuote{weight}. -E.g. if there is an A-C-B and also an A-D-B -triple in the bipartite graph (but no more X, such that A-X-B is also in the -graph), then the multiplicity of the A-B edge in the projection will be 2.} +\item{multiplicity}{If \code{TRUE}, then igraph keeps the multiplicity of the edges as an edge attribute called \sQuote{weight}. +E.g. if there is an A-C-B and also an A-D-B triple in the bipartite graph (but no more X, such that A-X-B is also in the graph), +then the multiplicity of the A-B edge in the projection will be 2.} -\item{probe1}{This argument can be used to specify the order of the -projections in the resulting list. If given, then it is considered as a -vertex ID (or a symbolic vertex name); the projection containing this vertex -will be the first one in the result list. This argument is ignored if only -one projection is requested in argument \code{which}.} +\item{probe1}{This argument can be used to specify the order of the projections in the resulting list. +If given, then it is considered as a vertex ID (or a symbolic vertex name); +the projection containing this vertex will be the first one in the result list. +This argument is ignored if only one projection is requested in argument \code{which}.} \item{which}{A character scalar to specify which projection(s) to calculate. The default is to calculate both.} -\item{remove.type}{Logical, whether to remove the \code{type} vertex -attribute from the projections. This makes sense because these graphs are -not bipartite any more. However if you want to combine them with each other -(or other bipartite graphs), then it is worth keeping this attribute. By -default it will be removed.} +\item{remove.type}{Logical, whether to remove the \code{type} vertex attribute from the projections. +This makes sense because these graphs are not bipartite any more. +However if you want to combine them with each other (or other bipartite graphs), then it is worth keeping this attribute. +By default it will be removed.} } \value{ -A list of two undirected graphs. See details above. +A list of two undirected graphs. +See details above. } \description{ A bipartite graph is projected into two one-mode networks } \details{ -Bipartite graphs have a \code{type} vertex attribute in igraph, this is -boolean and \code{FALSE} for the vertices of the first kind and \code{TRUE} -for vertices of the second kind. +Bipartite graphs have a \code{type} vertex attribute in igraph, +this is boolean and \code{FALSE} for the vertices of the first kind and \code{TRUE} for vertices of the second kind. -\code{bipartite_projection_size()} calculates the number of vertices and edges -in the two projections of the bipartite graphs, without calculating the -projections themselves. This is useful to check how much memory the -projections would need if you have a large bipartite graph. +\code{bipartite_projection_size()} calculates the number of vertices and edges in the two projections of the bipartite graphs, +without calculating the projections themselves. +This is useful to check how much memory the projections would need if you have a large bipartite graph. -\code{bipartite_projection()} calculates the actual projections. You can use -the \code{probe1} argument to specify the order of the projections in the -result. By default vertex type \code{FALSE} is the first and \code{TRUE} is -the second. +\code{bipartite_projection()} calculates the actual projections. +You can use the \code{probe1} argument to specify the order of the projections in the result. +By default vertex type \code{FALSE} is the first and \code{TRUE} is the second. \code{bipartite_projection()} keeps vertex attributes. } diff --git a/man/blockGraphs.Rd b/man/blockGraphs.Rd index edd5ab77085..137a003bb61 100644 --- a/man/blockGraphs.Rd +++ b/man/blockGraphs.Rd @@ -7,18 +7,15 @@ blockGraphs(blocks, graph) } \arguments{ -\item{graph}{For \code{cohesive_blocks()} a graph object of class -\code{igraph}. It must be undirected and simple. (See -\code{\link[=is_simple]{is_simple()}}.) +\item{graph}{For \code{cohesive_blocks()} a graph object of class \code{igraph}. +It must be undirected and simple. +(See \code{\link[=is_simple]{is_simple()}}.) -For \code{graphs_from_cohesive_blocks()} and \code{export_pajek()} the same graph must be -supplied whose cohesive block structure is given in the \code{blocks()} -argument.} +For \code{graphs_from_cohesive_blocks()} and \code{export_pajek()} the same graph must be supplied whose cohesive block structure is given in the \code{blocks()} argument.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{blockGraphs()} was renamed to \code{\link[=graphs_from_cohesive_blocks]{graphs_from_cohesive_blocks()}} to create a more -consistent API. +\code{blockGraphs()} was renamed to \code{\link[=graphs_from_cohesive_blocks]{graphs_from_cohesive_blocks()}} to create a more consistent API. } \keyword{internal} diff --git a/man/bonpow.Rd b/man/bonpow.Rd index b2afd4d8004..d3e08a77e65 100644 --- a/man/bonpow.Rd +++ b/man/bonpow.Rd @@ -17,31 +17,27 @@ bonpow( \arguments{ \item{graph}{the input graph.} -\item{nodes}{vertex sequence indicating which vertices are to be included in -the calculation. The default \code{NULL} selects all vertices.} +\item{nodes}{vertex sequence indicating which vertices are to be included in the calculation. +The default \code{NULL} selects all vertices.} -\item{loops}{Logical indicating whether or not the diagonal should be -treated as valid data. Set this true if and only if the data can contain -loops. \code{loops} is \code{FALSE} by default.} +\item{loops}{Logical indicating whether or not the diagonal should be treated as valid data. +Set this true if and only +if the data can contain loops. +\code{loops} is \code{FALSE} by default.} -\item{exponent}{exponent (decay rate) for the Bonacich power centrality -score; can be negative} +\item{exponent}{exponent (decay rate) for the Bonacich power centrality score; can be negative} -\item{rescale}{if true, centrality scores are rescaled such that they sum to -1.} +\item{rescale}{if true, centrality scores are rescaled such that they sum to 1.} -\item{tol}{tolerance for near-singularities during matrix inversion (see -\code{\link[Matrix:solve]{Matrix::solve()}})} +\item{tol}{tolerance for near-singularities during matrix inversion (see \code{\link[Matrix:solve]{Matrix::solve()}})} -\item{sparse}{Logical, whether to use sparse matrices for the -calculation. The \sQuote{Matrix} package is required for sparse matrix -support} +\item{sparse}{Logical, whether to use sparse matrices for the calculation. +The \sQuote{Matrix} package is required for sparse matrix support} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{bonpow()} was renamed to \code{\link[=power_centrality]{power_centrality()}} to create a more -consistent API. +\code{bonpow()} was renamed to \code{\link[=power_centrality]{power_centrality()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Operators.html#igraph_simplify}{\code{simplify()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_adjacency}{\code{get_adjacency()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_adjacency_sparse}{\code{get_adjacency_sparse()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/c.igraph.es.Rd b/man/c.igraph.es.Rd index bcc88147c2d..d8150cdcca6 100644 --- a/man/c.igraph.es.Rd +++ b/man/c.igraph.es.Rd @@ -7,11 +7,10 @@ \method{c}{igraph.es}(..., recursive = FALSE) } \arguments{ -\item{...}{The edge sequences to concatenate. They must -all refer to the same graph.} +\item{...}{The edge sequences to concatenate. +They must all refer to the same graph.} -\item{recursive}{Ignored, included for S3 compatibility with the -base \code{c} function.} +\item{recursive}{Ignored, included for S3 compatibility with the base \code{c} function.} } \value{ An edge sequence, the input sequences concatenated. diff --git a/man/c.igraph.vs.Rd b/man/c.igraph.vs.Rd index 5a66ddec65d..79d3ae393e2 100644 --- a/man/c.igraph.vs.Rd +++ b/man/c.igraph.vs.Rd @@ -7,11 +7,10 @@ \method{c}{igraph.vs}(..., recursive = FALSE) } \arguments{ -\item{...}{The vertex sequences to concatenate. They must -refer to the same graph.} +\item{...}{The vertex sequences to concatenate. +They must refer to the same graph.} -\item{recursive}{Ignored, included for S3 compatibility with -the base \code{c} function.} +\item{recursive}{Ignored, included for S3 compatibility with the base \code{c} function.} } \value{ A vertex sequence, the input sequences concatenated. diff --git a/man/callaway.traits.game.Rd b/man/callaway.traits.game.Rd index 487c8855995..bd0c0c5b622 100644 --- a/man/callaway.traits.game.Rd +++ b/man/callaway.traits.game.Rd @@ -20,11 +20,12 @@ callaway.traits.game( \item{edge.per.step}{The number of edges to add to the graph per time step.} -\item{type.dist}{The distribution of the vertex types. This is assumed to be -stationary in time. The default \code{NULL} gives a uniform distribution.} +\item{type.dist}{The distribution of the vertex types. +This is assumed to be stationary in time. +The default \code{NULL} gives a uniform distribution.} -\item{pref.matrix}{A matrix giving the preferences of the given vertex -types. These should be probabilities, i.e. numbers between zero and one. +\item{pref.matrix}{A matrix giving the preferences of the given vertex types. +These should be probabilities, i.e. numbers between zero and one. The default \code{NULL} sets all preferences to one.} \item{directed}{Logical, whether to generate directed graphs.} @@ -32,8 +33,7 @@ The default \code{NULL} sets all preferences to one.} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{callaway.traits.game()} was renamed to \code{\link[=sample_traits_callaway]{sample_traits_callaway()}} to create a more -consistent API. +\code{callaway.traits.game()} was renamed to \code{\link[=sample_traits_callaway]{sample_traits_callaway()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_callaway_traits_game}{\code{callaway_traits_game()}} diff --git a/man/canonical.permutation.Rd b/man/canonical.permutation.Rd index d7de6784375..b24e8d44958 100644 --- a/man/canonical.permutation.Rd +++ b/man/canonical.permutation.Rd @@ -13,21 +13,19 @@ canonical.permutation( \arguments{ \item{graph}{The input graph, treated as undirected.} -\item{colors}{The colors of the individual vertices of the graph; only -vertices having the same color are allowed to match each other in an -automorphism. When omitted, igraph uses the \code{color} attribute of the -vertices, or, if there is no such vertex attribute, it simply assumes that -all vertices have the same color. Pass NULL explicitly if the graph has a -\code{color} vertex attribute but you do not want to use it.} +\item{colors}{The colors of the individual vertices of the graph; +only vertices having the same color are allowed to match each other in an automorphism. +When omitted, igraph uses the \code{color} attribute of the vertices, or, if there is no such vertex attribute, +it simply assumes that all vertices have the same color. +Pass NULL explicitly if the graph has a \code{color} vertex attribute but you do not want to use it.} -\item{sh}{Type of the heuristics to use for the BLISS algorithm. See details -for possible values.} +\item{sh}{Type of the heuristics to use for the BLISS algorithm. +See details for possible values.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{canonical.permutation()} was renamed to \code{\link[=canonical_permutation]{canonical_permutation()}} to create a more -consistent API. +\code{canonical.permutation()} was renamed to \code{\link[=canonical_permutation]{canonical_permutation()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Isomorphism.html#igraph_canonical_permutation}{\code{canonical_permutation()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/canonical_permutation.Rd b/man/canonical_permutation.Rd index 9963a306968..4154cb98c59 100644 --- a/man/canonical_permutation.Rd +++ b/man/canonical_permutation.Rd @@ -14,17 +14,16 @@ canonical_permutation( \arguments{ \item{graph}{The input graph, treated as undirected.} -\item{colors}{The colors of the individual vertices of the graph; only -vertices having the same color are allowed to match each other in an -automorphism. When omitted, igraph uses the \code{color} attribute of the -vertices, or, if there is no such vertex attribute, it simply assumes that -all vertices have the same color. Pass NULL explicitly if the graph has a -\code{color} vertex attribute but you do not want to use it.} +\item{colors}{The colors of the individual vertices of the graph; +only vertices having the same color are allowed to match each other in an automorphism. +When omitted, igraph uses the \code{color} attribute of the vertices, or, if there is no such vertex attribute, +it simply assumes that all vertices have the same color. +Pass NULL explicitly if the graph has a \code{color} vertex attribute but you do not want to use it.} \item{...}{These dots are for future extensions and must be empty.} -\item{sh}{Type of the heuristics to use for the BLISS algorithm. See details -for possible values.} +\item{sh}{Type of the heuristics to use for the BLISS algorithm. +See details for possible values.} } \value{ A list with the following members: @@ -61,16 +60,14 @@ can easily exceed values that are exactly representable in floating point. } } \description{ -The canonical permutation brings every isomorphic graphs into the same -(labeled) graph. +The canonical permutation brings every isomorphic graphs into the same (labeled) graph. } \details{ -\code{canonical_permutation()} computes a permutation which brings the graph -into canonical form, as defined by the BLISS algorithm. All isomorphic -graphs have the same canonical form. +\code{canonical_permutation()} computes a permutation which brings the graph into canonical form, as defined by the BLISS algorithm. +All isomorphic graphs have the same canonical form. -See the paper below for the details about BLISS. This and more information -is available at \url{http://www.tcs.hut.fi/Software/bliss/index.html}. +See the paper below for the details about BLISS. +This and more information is available at \url{http://www.tcs.hut.fi/Software/bliss/index.html}. The possible values for the \code{sh} argument are: \describe{ @@ -93,8 +90,7 @@ Largest maximally non-trivially connected non-singleton cell. Smallest maximally non-trivially connected non-singleton cell. } } -See the paper in references for details -about these. +See the paper in references for details about these. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Isomorphism.html#igraph_canonical_permutation}{\code{canonical_permutation()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} @@ -126,9 +122,8 @@ the Ninth Workshop on Algorithm Engineering and Experiments and the Fourth Workshop on Analytic Algorithms and Combinatorics.} 2007. } \seealso{ -\code{\link[=permute]{permute()}} to apply a permutation to a graph, -\code{\link[=isomorphic]{isomorphic()}} for deciding graph isomorphism, possibly -based on canonical labels. +\code{\link[=permute]{permute()}} to apply a permutation to a graph, \code{\link[=isomorphic]{isomorphic()}} for deciding graph isomorphism, +possibly based on canonical labels. Other graph isomorphism: \code{\link[=count_isomorphisms]{count_isomorphisms()}}, diff --git a/man/categorical_pal.Rd b/man/categorical_pal.Rd index 70aab393ba7..a4342b70ac2 100644 --- a/man/categorical_pal.Rd +++ b/man/categorical_pal.Rd @@ -7,19 +7,18 @@ categorical_pal(n) } \arguments{ -\item{n}{The number of colors in the palette. We simply take the first -\code{n} colors from the total 8.} +\item{n}{The number of colors in the palette. +We simply take the first \code{n} colors from the total 8.} } \value{ A character vector of RGB color codes. } \description{ -This is a color blind friendly palette from -\url{https://jfly.uni-koeln.de/color/}. It has 8 colors. +This is a color blind friendly palette from \url{https://jfly.uni-koeln.de/color/}. +It has 8 colors. } \details{ -This is the suggested palette for visualizations where vertex colors -mark categories, e.g. community membership. +This is the suggested palette for visualizations where vertex colors mark categories, e.g. community membership. } \section{Examples}{ diff --git a/man/centr_betw.Rd b/man/centr_betw.Rd index 3b4190b3514..092674a897c 100644 --- a/man/centr_betw.Rd +++ b/man/centr_betw.Rd @@ -11,11 +11,10 @@ centr_betw(graph, ..., directed = TRUE, normalized = TRUE) \item{...}{These dots are for future extensions and must be empty.} -\item{directed}{Logical, whether to use directed shortest paths for -calculating betweenness.} +\item{directed}{Logical, whether to use directed shortest paths for calculating betweenness.} -\item{normalized}{Logical. Whether to normalize the graph level -centrality score by dividing by the theoretical maximum.} +\item{normalized}{Logical. +Whether to normalize the graph level centrality score by dividing by the theoretical maximum.} } \value{ A named list with the following components: diff --git a/man/centr_betw_tmax.Rd b/man/centr_betw_tmax.Rd index 6da3968daf7..1ed8694ac38 100644 --- a/man/centr_betw_tmax.Rd +++ b/man/centr_betw_tmax.Rd @@ -7,22 +7,20 @@ centr_betw_tmax(graph = NULL, nodes = 0, ..., directed = TRUE) } \arguments{ -\item{graph}{The input graph. It can also be \code{NULL} if -\code{nodes} and \code{directed} are both given.} +\item{graph}{The input graph. +It can also be \code{NULL} if \code{nodes} and \code{directed} are both given.} -\item{nodes}{The number of vertices. This is ignored if the graph is -given.} +\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.} +\item{directed}{Logical, whether to use directed shortest paths for calculating betweenness. +Ignored if an undirected graph was given.} } \value{ -Real scalar, the theoretical maximum (unnormalized) graph -betweenness centrality score for graphs with given order and other -parameters. +Real scalar, +the theoretical maximum (unnormalized) graph betweenness centrality score for graphs with given order and other parameters. } \description{ See \code{\link[=centralize]{centralize()}} for a summary of graph centralization. diff --git a/man/centr_clo.Rd b/man/centr_clo.Rd index e3f708d9ea7..65fd45c3fcb 100644 --- a/man/centr_clo.Rd +++ b/man/centr_clo.Rd @@ -11,11 +11,10 @@ centr_clo(graph, ..., mode = c("out", "in", "all", "total"), normalized = TRUE) \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()}.} +\item{mode}{This is the same as the \code{mode} argument of \code{closeness()}.} -\item{normalized}{Logical. Whether to normalize the graph level -centrality score by dividing by the theoretical maximum.} +\item{normalized}{Logical. +Whether to normalize the graph level centrality score by dividing by the theoretical maximum.} } \value{ A named list with the following components: diff --git a/man/centr_clo_tmax.Rd b/man/centr_clo_tmax.Rd index 93fbe09cde8..9cf262ecf6b 100644 --- a/man/centr_clo_tmax.Rd +++ b/man/centr_clo_tmax.Rd @@ -12,21 +12,20 @@ centr_clo_tmax( ) } \arguments{ -\item{graph}{The input graph. It can also be \code{NULL} if -\code{nodes} is given.} +\item{graph}{The input graph. +It can also be \code{NULL} if \code{nodes} is given.} -\item{nodes}{The number of vertices. This is ignored if the graph is -given.} +\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.} +\item{mode}{This is the same as the \code{mode} argument of \code{closeness()}. +Ignored if an undirected graph is given.} } \value{ -Real scalar, the theoretical maximum (unnormalized) graph -closeness centrality score for graphs with given order and other -parameters. +Real scalar, +the theoretical maximum (unnormalized) graph closeness centrality score for graphs with given order and other parameters. } \description{ See \code{\link[=centralize]{centralize()}} for a summary of graph centralization. diff --git a/man/centr_degree.Rd b/man/centr_degree.Rd index 0bed80e5c17..cb1f08207bc 100644 --- a/man/centr_degree.Rd +++ b/man/centr_degree.Rd @@ -17,14 +17,12 @@ centr_degree( \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()}.} +\item{mode}{This is the same as the \code{mode} argument of \code{degree()}.} -\item{loops}{Logical, whether to consider loops edges when -calculating the degree.} +\item{loops}{Logical, whether to consider loops edges when calculating the degree.} -\item{normalized}{Logical. Whether to normalize the graph level -centrality score by dividing by the theoretical maximum.} +\item{normalized}{Logical. +Whether to normalize the graph level centrality score by dividing by the theoretical maximum.} } \value{ A named list with the following components: diff --git a/man/centr_degree_tmax.Rd b/man/centr_degree_tmax.Rd index 7a6f8cae489..aa5c2a9088a 100644 --- a/man/centr_degree_tmax.Rd +++ b/man/centr_degree_tmax.Rd @@ -12,19 +12,20 @@ centr_degree_tmax( ) } \arguments{ -\item{graph}{The input graph. It can also be \code{NULL} if \code{nodes} is given.} +\item{graph}{The input graph. +It can also be \code{NULL} if \code{nodes} is given.} -\item{nodes}{The number of vertices. This is ignored if the graph is given.} +\item{nodes}{The number of vertices. +This is ignored if the graph is given.} -\item{mode}{This is the same as the \code{mode} argument of \code{degree()}. Ignored -if \code{graph} is given and the graph is undirected.} +\item{mode}{This is the same as the \code{mode} argument of \code{degree()}. +Ignored if \code{graph} is given and the graph is undirected.} -\item{loops}{Logical, whether to consider loops edges when -calculating the degree.} +\item{loops}{Logical, whether to consider loops edges when calculating the degree.} } \value{ -Real scalar, the theoretical maximum (unnormalized) graph degree -centrality score for graphs with given order and other parameters. +Real scalar, +the theoretical maximum (unnormalized) graph degree centrality score for graphs with given order and other parameters. } \description{ See \code{\link[=centralize]{centralize()}} for a summary of graph centralization. diff --git a/man/centr_eigen.Rd b/man/centr_eigen.Rd index 333a53501b5..e52023e858d 100644 --- a/man/centr_eigen.Rd +++ b/man/centr_eigen.Rd @@ -15,17 +15,15 @@ centr_eigen( \arguments{ \item{graph}{The input graph.} -\item{directed}{Logical, whether to use directed shortest paths for -calculating eigenvector centrality.} +\item{directed}{Logical, whether to use directed shortest paths for calculating eigenvector centrality.} -\item{scale}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Ignored. Computing -eigenvector centralization requires normalized eigenvector centrality scores.} +\item{scale}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Ignored. +Computing eigenvector centralization requires normalized eigenvector centrality scores.} -\item{options}{This is passed to \code{\link[=eigen_centrality]{eigen_centrality()}}, the options -for the ARPACK eigensolver.} +\item{options}{This is passed to \code{\link[=eigen_centrality]{eigen_centrality()}}, the options for the ARPACK eigensolver.} -\item{normalized}{Logical. Whether to normalize the graph level -centrality score by dividing by the theoretical maximum.} +\item{normalized}{Logical. +Whether to normalize the graph level centrality score by dividing by the theoretical maximum.} } \value{ A named list with the following components: diff --git a/man/centr_eigen_tmax.Rd b/man/centr_eigen_tmax.Rd index 86ce59f90da..20c465126c5 100644 --- a/man/centr_eigen_tmax.Rd +++ b/man/centr_eigen_tmax.Rd @@ -12,22 +12,21 @@ centr_eigen_tmax( ) } \arguments{ -\item{graph}{The input graph. It can also be \code{NULL}, if -\code{nodes} is given.} +\item{graph}{The input graph. +It can also be \code{NULL}, if \code{nodes} is given.} -\item{nodes}{The number of vertices. This is ignored if the graph is -given.} +\item{nodes}{The number of vertices. +This is ignored if the graph is given.} -\item{directed}{Logical, whether to consider edge directions -during the calculation. Ignored in undirected graphs.} +\item{directed}{Logical, whether to consider edge directions during the calculation. +Ignored in undirected graphs.} -\item{scale}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Ignored. Computing -eigenvector centralization requires normalized eigenvector centrality scores.} +\item{scale}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Ignored. +Computing eigenvector centralization requires normalized eigenvector centrality scores.} } \value{ -Real scalar, the theoretical maximum (unnormalized) graph -eigenvector centrality score for graphs with given vertex count and -other parameters. +Real scalar, +the theoretical maximum (unnormalized) graph eigenvector centrality score for graphs with given vertex count and other parameters. } \description{ See \code{\link[=centralize]{centralize()}} for a summary of graph centralization. diff --git a/man/centralization.betweenness.Rd b/man/centralization.betweenness.Rd index e9169ed9145..c88d5eef90c 100644 --- a/man/centralization.betweenness.Rd +++ b/man/centralization.betweenness.Rd @@ -9,17 +9,15 @@ centralization.betweenness(graph, directed = TRUE, normalized = TRUE) \arguments{ \item{graph}{The input graph.} -\item{directed}{Logical, whether to use directed shortest paths for -calculating betweenness.} +\item{directed}{Logical, whether to use directed shortest paths for calculating betweenness.} -\item{normalized}{Logical. Whether to normalize the graph level -centrality score by dividing by the theoretical maximum.} +\item{normalized}{Logical. +Whether to normalize the graph level centrality score by dividing by the theoretical maximum.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{centralization.betweenness()} was renamed to \code{\link[=centr_betw]{centr_betw()}} to create a more -consistent API. +\code{centralization.betweenness()} was renamed to \code{\link[=centr_betw]{centr_betw()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_centralization_betweenness}{\code{centralization_betweenness()}} diff --git a/man/centralization.betweenness.tmax.Rd b/man/centralization.betweenness.tmax.Rd index fb9bbfd5864..e0f90b9d7f4 100644 --- a/man/centralization.betweenness.tmax.Rd +++ b/man/centralization.betweenness.tmax.Rd @@ -7,21 +7,19 @@ centralization.betweenness.tmax(graph = NULL, nodes = 0, directed = TRUE) } \arguments{ -\item{graph}{The input graph. It can also be \code{NULL} if -\code{nodes} and \code{directed} are both given.} +\item{graph}{The input graph. +It can also be \code{NULL} if \code{nodes} and \code{directed} are both given.} -\item{nodes}{The number of vertices. This is ignored if the graph is -given.} +\item{nodes}{The number of vertices. +This is ignored if the graph is given.} -\item{directed}{Logical, whether to use directed shortest paths -for calculating betweenness. Ignored if an undirected graph was -given.} +\item{directed}{Logical, whether to use directed shortest paths for calculating betweenness. +Ignored if an undirected graph was given.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{centralization.betweenness.tmax()} was renamed to \code{\link[=centr_betw_tmax]{centr_betw_tmax()}} to create a more -consistent API. +\code{centralization.betweenness.tmax()} was renamed to \code{\link[=centr_betw_tmax]{centr_betw_tmax()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_centralization_betweenness_tmax}{\code{centralization_betweenness_tmax()}} diff --git a/man/centralization.closeness.Rd b/man/centralization.closeness.Rd index caf53f309ae..d6a8be28e39 100644 --- a/man/centralization.closeness.Rd +++ b/man/centralization.closeness.Rd @@ -13,17 +13,15 @@ centralization.closeness( \arguments{ \item{graph}{The input graph.} -\item{mode}{This is the same as the \code{mode} argument of -\code{closeness()}.} +\item{mode}{This is the same as the \code{mode} argument of \code{closeness()}.} -\item{normalized}{Logical. Whether to normalize the graph level -centrality score by dividing by the theoretical maximum.} +\item{normalized}{Logical. +Whether to normalize the graph level centrality score by dividing by the theoretical maximum.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{centralization.closeness()} was renamed to \code{\link[=centr_clo]{centr_clo()}} to create a more -consistent API. +\code{centralization.closeness()} was renamed to \code{\link[=centr_clo]{centr_clo()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_centralization_closeness}{\code{centralization_closeness()}} diff --git a/man/centralization.closeness.tmax.Rd b/man/centralization.closeness.tmax.Rd index e1560171fcd..76db0303235 100644 --- a/man/centralization.closeness.tmax.Rd +++ b/man/centralization.closeness.tmax.Rd @@ -11,20 +11,19 @@ centralization.closeness.tmax( ) } \arguments{ -\item{graph}{The input graph. It can also be \code{NULL} if -\code{nodes} is given.} +\item{graph}{The input graph. +It can also be \code{NULL} if \code{nodes} is given.} -\item{nodes}{The number of vertices. This is ignored if the graph is -given.} +\item{nodes}{The number of vertices. +This is ignored if the graph is given.} -\item{mode}{This is the same as the \code{mode} argument of -\code{closeness()}. Ignored if an undirected graph is given.} +\item{mode}{This is the same as the \code{mode} argument of \code{closeness()}. +Ignored if an undirected graph is given.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{centralization.closeness.tmax()} was renamed to \code{\link[=centr_clo_tmax]{centr_clo_tmax()}} to create a more -consistent API. +\code{centralization.closeness.tmax()} was renamed to \code{\link[=centr_clo_tmax]{centr_clo_tmax()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_centralization_closeness_tmax}{\code{centralization_closeness_tmax()}} diff --git a/man/centralization.degree.Rd b/man/centralization.degree.Rd index f508c372e7b..c0fd91c9650 100644 --- a/man/centralization.degree.Rd +++ b/man/centralization.degree.Rd @@ -14,20 +14,17 @@ centralization.degree( \arguments{ \item{graph}{The input graph.} -\item{mode}{This is the same as the \code{mode} argument of -\code{degree()}.} +\item{mode}{This is the same as the \code{mode} argument of \code{degree()}.} -\item{loops}{Logical, whether to consider loops edges when -calculating the degree.} +\item{loops}{Logical, whether to consider loops edges when calculating the degree.} -\item{normalized}{Logical. Whether to normalize the graph level -centrality score by dividing by the theoretical maximum.} +\item{normalized}{Logical. +Whether to normalize the graph level centrality score by dividing by the theoretical maximum.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{centralization.degree()} was renamed to \code{\link[=centr_degree]{centr_degree()}} to create a more -consistent API. +\code{centralization.degree()} was renamed to \code{\link[=centr_degree]{centr_degree()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_centralization_degree}{\code{centralization_degree()}} diff --git a/man/centralization.degree.tmax.Rd b/man/centralization.degree.tmax.Rd index 29d7b242e75..d0ff870f6d8 100644 --- a/man/centralization.degree.tmax.Rd +++ b/man/centralization.degree.tmax.Rd @@ -12,21 +12,21 @@ centralization.degree.tmax( ) } \arguments{ -\item{graph}{The input graph. It can also be \code{NULL} if \code{nodes} is given.} +\item{graph}{The input graph. +It can also be \code{NULL} if \code{nodes} is given.} -\item{nodes}{The number of vertices. This is ignored if the graph is given.} +\item{nodes}{The number of vertices. +This is ignored if the graph is given.} -\item{mode}{This is the same as the \code{mode} argument of \code{degree()}. Ignored -if \code{graph} is given and the graph is undirected.} +\item{mode}{This is the same as the \code{mode} argument of \code{degree()}. +Ignored if \code{graph} is given and the graph is undirected.} -\item{loops}{Logical, whether to consider loops edges when -calculating the degree.} +\item{loops}{Logical, whether to consider loops edges when calculating the degree.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{centralization.degree.tmax()} was renamed to \code{\link[=centr_degree_tmax]{centr_degree_tmax()}} to create a more -consistent API. +\code{centralization.degree.tmax()} was renamed to \code{\link[=centr_degree_tmax]{centr_degree_tmax()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_centralization_degree_tmax}{\code{centralization_degree_tmax()}} diff --git a/man/centralization.evcent.Rd b/man/centralization.evcent.Rd index dd83655867c..cc483e1d7ab 100644 --- a/man/centralization.evcent.Rd +++ b/man/centralization.evcent.Rd @@ -15,23 +15,20 @@ centralization.evcent( \arguments{ \item{graph}{The input graph.} -\item{directed}{Logical, whether to use directed shortest paths for -calculating eigenvector centrality.} +\item{directed}{Logical, whether to use directed shortest paths for calculating eigenvector centrality.} -\item{scale}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Ignored. Computing -eigenvector centralization requires normalized eigenvector centrality scores.} +\item{scale}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Ignored. +Computing eigenvector centralization requires normalized eigenvector centrality scores.} -\item{options}{This is passed to \code{\link[=eigen_centrality]{eigen_centrality()}}, the options -for the ARPACK eigensolver.} +\item{options}{This is passed to \code{\link[=eigen_centrality]{eigen_centrality()}}, the options for the ARPACK eigensolver.} -\item{normalized}{Logical. Whether to normalize the graph level -centrality score by dividing by the theoretical maximum.} +\item{normalized}{Logical. +Whether to normalize the graph level centrality score by dividing by the theoretical maximum.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{centralization.evcent()} was renamed to \code{\link[=centr_eigen]{centr_eigen()}} to create a more -consistent API. +\code{centralization.evcent()} was renamed to \code{\link[=centr_eigen]{centr_eigen()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_centralization_eigenvector_centrality}{\code{centralization_eigenvector_centrality()}} diff --git a/man/centralization.evcent.tmax.Rd b/man/centralization.evcent.tmax.Rd index 7800a83252c..990299ac7e6 100644 --- a/man/centralization.evcent.tmax.Rd +++ b/man/centralization.evcent.tmax.Rd @@ -12,23 +12,22 @@ centralization.evcent.tmax( ) } \arguments{ -\item{graph}{The input graph. It can also be \code{NULL}, if -\code{nodes} is given.} +\item{graph}{The input graph. +It can also be \code{NULL}, if \code{nodes} is given.} -\item{nodes}{The number of vertices. This is ignored if the graph is -given.} +\item{nodes}{The number of vertices. +This is ignored if the graph is given.} -\item{directed}{Logical, whether to consider edge directions -during the calculation. Ignored in undirected graphs.} +\item{directed}{Logical, whether to consider edge directions during the calculation. +Ignored in undirected graphs.} -\item{scale}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Ignored. Computing -eigenvector centralization requires normalized eigenvector centrality scores.} +\item{scale}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Ignored. +Computing eigenvector centralization requires normalized eigenvector centrality scores.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{centralization.evcent.tmax()} was renamed to \code{\link[=centr_eigen_tmax]{centr_eigen_tmax()}} to create a more -consistent API. +\code{centralization.evcent.tmax()} was renamed to \code{\link[=centr_eigen_tmax]{centr_eigen_tmax()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_centralization_eigenvector_centrality_tmax}{\code{centralization_eigenvector_centrality_tmax()}} diff --git a/man/centralize.Rd b/man/centralize.Rd index 5574cc67f67..abc0f27a054 100644 --- a/man/centralize.Rd +++ b/man/centralize.Rd @@ -12,42 +12,34 @@ centralize(scores, ..., theoretical.max = 0, normalized = TRUE) \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 -to \code{TRUE}.} +\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 to \code{TRUE}.} -\item{normalized}{Logical. Whether to normalize the graph level -centrality score by dividing by the supplied theoretical maximum.} +\item{normalized}{Logical. +Whether to normalize the graph level centrality score by dividing by the supplied theoretical maximum.} } \value{ -A real scalar, the centralization of the graph from which -\code{scores} were derived. +A real scalar, the centralization of the graph from which \code{scores} were derived. } \description{ -Centralization is a method for creating a graph level centralization -measure from the centrality scores of the vertices. +Centralization is a method for creating a graph level centralization measure from the centrality scores of the vertices. } \details{ -Centralization is a general method for calculating a graph-level -centrality score based on node-level centrality measure. The formula for -this is +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. +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 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). +For eigenvector centrality the most centralized structure is the graph with a single edge (and potentially many isolates). -\code{centralize()} implements general centralization formula to calculate -a graph-level score from vertex-level scores. +\code{centralize()} implements general centralization formula to calculate a graph-level score from vertex-level scores. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_centralization}{\code{centralization()}} diff --git a/man/centralize.scores.Rd b/man/centralize.scores.Rd index 35ed7653490..ec0d1057608 100644 --- a/man/centralize.scores.Rd +++ b/man/centralize.scores.Rd @@ -9,19 +9,17 @@ centralize.scores(scores, theoretical.max = 0, normalized = TRUE) \arguments{ \item{scores}{The vertex level centrality scores.} -\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 -to \code{TRUE}.} +\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 to \code{TRUE}.} -\item{normalized}{Logical. Whether to normalize the graph level -centrality score by dividing by the supplied theoretical maximum.} +\item{normalized}{Logical. +Whether to normalize the graph level centrality score by dividing by the supplied theoretical maximum.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{centralize.scores()} was renamed to \code{\link[=centralize]{centralize()}} to create a more -consistent API. +\code{centralize.scores()} was renamed to \code{\link[=centralize]{centralize()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_centralization}{\code{centralization()}} diff --git a/man/cited.type.game.Rd b/man/cited.type.game.Rd index 36274fe1084..49558a99037 100644 --- a/man/cited.type.game.Rd +++ b/man/cited.type.game.Rd @@ -19,25 +19,20 @@ cited.type.game( \item{edges}{Number of edges per step.} \item{types}{Vector of length \sQuote{\code{n}}, the types of the vertices. -Types are numbered from zero. The default \code{NULL} gives all vertices -type zero.} +Types are numbered from zero. +The default \code{NULL} gives all vertices type zero.} -\item{pref}{Vector (\code{sample_last_cit()} and \code{sample_cit_types()} or -matrix (\code{sample_cit_cit_types()}) giving the (unnormalized) citation -probabilities for the different vertex types. The default \code{NULL} uses -\code{(1:(agebins + 1))^-3} for \code{sample_last_cit()} and all-one probabilities -for the other two.} +\item{pref}{Vector (\code{sample_last_cit()} and \code{sample_cit_types()} or matrix (\code{sample_cit_cit_types()}) giving the (unnormalized) citation probabilities for the different vertex types. +The default \code{NULL} uses \code{(1:(agebins + 1))^-3} for \code{sample_last_cit()} and all-one probabilities for the other two.} \item{directed}{Logical, whether to generate directed networks.} -\item{attr}{Logical, whether to add the vertex types to the generated -graph as a vertex attribute called \sQuote{\code{type}}.} +\item{attr}{Logical, whether to add the vertex types to the generated graph as a vertex attribute called \sQuote{\code{type}}.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{cited.type.game()} was renamed to \code{\link[=sample_cit_types]{sample_cit_types()}} to create a more -consistent API. +\code{cited.type.game()} was renamed to \code{\link[=sample_cit_types]{sample_cit_types()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_cited_type_game}{\code{cited_type_game()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/citing.cited.type.game.Rd b/man/citing.cited.type.game.Rd index 151924096cc..3022d860166 100644 --- a/man/citing.cited.type.game.Rd +++ b/man/citing.cited.type.game.Rd @@ -19,25 +19,20 @@ citing.cited.type.game( \item{edges}{Number of edges per step.} \item{types}{Vector of length \sQuote{\code{n}}, the types of the vertices. -Types are numbered from zero. The default \code{NULL} gives all vertices -type zero.} +Types are numbered from zero. +The default \code{NULL} gives all vertices type zero.} -\item{pref}{Vector (\code{sample_last_cit()} and \code{sample_cit_types()} or -matrix (\code{sample_cit_cit_types()}) giving the (unnormalized) citation -probabilities for the different vertex types. The default \code{NULL} uses -\code{(1:(agebins + 1))^-3} for \code{sample_last_cit()} and all-one probabilities -for the other two.} +\item{pref}{Vector (\code{sample_last_cit()} and \code{sample_cit_types()} or matrix (\code{sample_cit_cit_types()}) giving the (unnormalized) citation probabilities for the different vertex types. +The default \code{NULL} uses \code{(1:(agebins + 1))^-3} for \code{sample_last_cit()} and all-one probabilities for the other two.} \item{directed}{Logical, whether to generate directed networks.} -\item{attr}{Logical, whether to add the vertex types to the generated -graph as a vertex attribute called \sQuote{\code{type}}.} +\item{attr}{Logical, whether to add the vertex types to the generated graph as a vertex attribute called \sQuote{\code{type}}.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{citing.cited.type.game()} was renamed to \code{\link[=sample_cit_cit_types]{sample_cit_cit_types()}} to create a more -consistent API. +\code{citing.cited.type.game()} was renamed to \code{\link[=sample_cit_cit_types]{sample_cit_cit_types()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_citing_cited_type_game}{\code{citing_cited_type_game()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/clique.number.Rd b/man/clique.number.Rd index 2a3cc5941cb..5e9467fbc35 100644 --- a/man/clique.number.Rd +++ b/man/clique.number.Rd @@ -12,8 +12,7 @@ clique.number(graph) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{clique.number()} was renamed to \code{\link[=clique_num]{clique_num()}} to create a more -consistent API. +\code{clique.number()} was renamed to \code{\link[=clique_num]{clique_num()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Cliques.html#igraph_clique_number}{\code{clique_number()}} diff --git a/man/cliques.Rd b/man/cliques.Rd index d9d1cc4e967..048c759d5e5 100644 --- a/man/cliques.Rd +++ b/man/cliques.Rd @@ -49,91 +49,78 @@ is_clique(graph, candidate, ..., directed = FALSE) \item{...}{These dots are for future extensions and must be empty.} -\item{callback}{Optional function to call for each clique found. If provided, -the function should accept one argument: \code{clique} (integer vector of vertex -IDs in the clique, 1-based indexing). The function should return \code{FALSE} to -continue the search or \code{TRUE} to stop it. If \code{NULL} (the default), all -cliques are collected and returned as a list. - -\strong{Important limitation:} Callback functions must NOT call any igraph -functions (including simple queries like \code{vcount()} or \code{ecount()}). Doing -so will cause R to crash due to reentrancy issues. Extract -any needed graph information before calling the function with a callback, or -use collector mode (the default) and process results afterward.} - -\item{subset}{If not \code{NULL}, then it must be a vector of vertex IDs, -numeric or symbolic if the graph is named. The algorithm is run from these -vertices only, so only a subset of all maximal cliques is returned. See the -Eppstein paper for details. This argument makes it possible to easily -parallelize the finding of maximal cliques.} - -\item{file}{If not \code{NULL}, then it must be a file name, i.e. a -character scalar. The output of the algorithm is written to this file. (If -it exists, then it will be overwritten.) Each clique will be a separate line -in the file, given with the numeric IDs of its vertices, separated by -whitespace.} - -\item{vertex.weights}{Vertex weight vector. If the graph has a \code{weight} -vertex attribute, then this is used by default. If the graph does not have a -\code{weight} vertex attribute and this argument is \code{NULL}, then every -vertex is assumed to have a weight of 1. Note that the current implementation -of the weighted clique finder supports positive integer weights only.} - -\item{maximal}{Specifies whether to look for all weighted cliques (\code{FALSE}) -or only the maximal ones (\code{TRUE}).} +\item{callback}{Optional function to call for each clique found. +If provided, the function should accept one argument: \code{clique} (integer vector of vertex IDs in the clique, 1-based indexing). +The function should return \code{FALSE} to continue the search or \code{TRUE} to stop it. +If \code{NULL} (the default), all cliques are collected and returned as a list. + +\strong{Important limitation:} Callback functions must NOT call any igraph functions (including simple queries like \code{vcount()} or \code{ecount()}). +Doing so will cause R to crash due to reentrancy issues. +Extract any needed graph information before calling the function with a callback, +or use collector mode (the default) and process results afterward.} + +\item{subset}{If not \code{NULL}, then it must be a vector of vertex IDs, numeric or symbolic if the graph is named. +The algorithm is run from these vertices only, so only a subset of all maximal cliques is returned. +See the Eppstein paper for details. +This argument makes it possible to easily parallelize the finding of maximal cliques.} + +\item{file}{If not \code{NULL}, then it must be a file name, i.e. a character scalar. +The output of the algorithm is written to this file. +(If it exists, then it will be overwritten.) +Each clique will be a separate line in the file, given with the numeric IDs of its vertices, separated by whitespace.} + +\item{vertex.weights}{Vertex weight vector. +If the graph has a \code{weight} vertex attribute, then this is used by default. +If the graph does not have a \code{weight} vertex attribute and this argument is \code{NULL}, +then every vertex is assumed to have a weight of 1. Note that the current implementation of the weighted clique finder supports positive integer weights only.} + +\item{maximal}{Specifies whether to look for all weighted cliques (\code{FALSE}) or only the maximal ones (\code{TRUE}).} \item{candidate}{The vertex set to test for being a clique.} \item{directed}{Whether to consider edge directions.} } \value{ -\code{cliques()} returns a list containing numeric vectors of vertex IDs if -\code{callback} is \code{NULL}. Each list element is a clique, i.e. a vertex sequence -of class \link[=V]{igraph.vs}. If \code{callback} is provided, returns \code{NULL} invisibly. +\code{cliques()} returns a list containing numeric vectors of vertex IDs if \code{callback} is \code{NULL}. +Each list element is a clique, i.e. a vertex sequence of class \link[=V]{igraph.vs}. +If \code{callback} is provided, returns \code{NULL} invisibly. -\code{largest_cliques()} and \code{clique_num()} return a list containing numeric -vectors of vertex IDs. Each list element is a clique, i.e. a vertex sequence -of class \link[=V]{igraph.vs}. +\code{largest_cliques()} and \code{clique_num()} return a list containing numeric vectors of vertex IDs. +Each list element is a clique, i.e. a vertex sequence of class \link[=V]{igraph.vs}. -\code{max_cliques()} returns \code{NULL}, invisibly, if its \code{file} -argument is not \code{NULL}. The output is written to the specified file in -this case. +\code{max_cliques()} returns \code{NULL}, invisibly, if its \code{file} argument is not \code{NULL}. +The output is written to the specified file in this case. -\code{clique_num()} and \code{count_max_cliques()} return an integer -scalar. +\code{clique_num()} and \code{count_max_cliques()} return an integer scalar. -\code{clique_size_counts()} returns a numeric vector with the clique sizes such that -the i-th item belongs to cliques of size i. Trailing zeros are currently -truncated, but this might change in future versions. +\code{clique_size_counts()} returns a numeric vector with the clique sizes such that the i-th item belongs to cliques of size i. +Trailing zeros are currently truncated, but this might change in future versions. -\code{is_clique()} returns \code{TRUE} if the candidate vertex set forms -a clique. +\code{is_clique()} returns \code{TRUE} if the candidate vertex set forms a clique. } \description{ -These functions find all, the largest or all the maximal cliques in an -undirected graph. The size of the largest clique can also be calculated. +These functions find all, the largest or all the maximal cliques in an undirected graph. +The size of the largest clique can also be calculated. -Tests if all pairs within a set of vertices are adjacent, i.e. whether they -form a clique. An empty set and singleton set are considered to be a clique. +Tests if all pairs within a set of vertices are adjacent, i.e. whether they form a clique. +An empty set and singleton set are considered to be a clique. } \details{ -\code{cliques()} find all complete subgraphs in the input graph, obeying the -size limitations given in the \code{min} and \code{max} arguments. +\code{cliques()} find all complete subgraphs in the input graph, obeying the size limitations given in the \code{min} and \code{max} arguments. -\code{largest_cliques()} finds all largest cliques in the input graph. A -clique is largest if there is no other clique including more vertices. +\code{largest_cliques()} finds all largest cliques in the input graph. +A clique is largest if there is no other clique including more vertices. -\code{max_cliques()} finds all maximal cliques in the input graph. A -clique is maximal if it cannot be extended to a larger clique. The largest -cliques are always maximal, but a maximal clique is not necessarily the -largest. +\code{max_cliques()} finds all maximal cliques in the input graph. +A clique is maximal if it cannot be extended to a larger clique. +The largest cliques are always maximal, but a maximal clique is not necessarily the largest. \code{count_max_cliques()} counts the maximal cliques. \code{clique_num()} calculates the size of the largest clique(s). -\code{clique_size_counts()} returns a numeric vector representing a histogram -of clique sizes, between the given minimum and maximum clique size. +\code{clique_size_counts()} returns a numeric vector representing a histogram of clique sizes, +between the given minimum and maximum clique size. \code{is_clique()} tests whether all pairs within a vertex set are connected. } diff --git a/man/closeness.Rd b/man/closeness.Rd index 3103521ed9b..e7b96a71592 100644 --- a/man/closeness.Rd +++ b/man/closeness.Rd @@ -23,52 +23,41 @@ The default \code{NULL} selects all vertices.} \item{...}{These dots are for future extensions and must be empty.} -\item{mode}{Character string, defined the types of the paths used for -measuring the distance in directed graphs. \dQuote{in} measures the paths -\emph{to} a vertex, \dQuote{out} measures paths \emph{from} a vertex, -\emph{all} uses undirected paths. This argument is ignored for undirected -graphs.} +\item{mode}{Character string, defined the types of the paths used for measuring the distance in directed graphs. +\dQuote{in} measures the paths \emph{to} a vertex, \dQuote{out} measures paths \emph{from} a vertex, \emph{all} uses undirected paths. +This argument is ignored for undirected graphs.} -\item{weights}{Optional positive weight vector for calculating weighted -closeness. If the graph has a \code{weight} edge attribute, then this is -used by default. Weights are used for calculating weighted shortest -paths, so they are interpreted as distances.} +\item{weights}{Optional positive weight vector for calculating weighted closeness. +If the graph has a \code{weight} edge attribute, then this is used by default. +Weights are used for calculating weighted shortest paths, so they are interpreted as distances.} -\item{normalized}{Logical, whether to calculate the normalized -closeness, i.e. the inverse average distance to all reachable vertices. -The non-normalized closeness is the inverse of the sum of distances to -all reachable vertices.} +\item{normalized}{Logical, whether to calculate the normalized closeness, i.e. the inverse average distance to all reachable vertices. +The non-normalized closeness is the inverse of the sum of distances to all reachable vertices.} -\item{cutoff}{The maximum path length to consider when calculating the -closeness. If zero or negative then there is no such limit.} +\item{cutoff}{The maximum path length to consider when calculating the closeness. +If zero or negative then there is no such limit.} } \value{ -Numeric vector with the closeness values of all the vertices in -\code{v}. +Numeric vector with the closeness values of all the vertices in \code{v}. } \description{ -Closeness centrality measures how many steps are required to access every other -vertex from a given vertex. +Closeness centrality measures how many steps are required to access every other vertex from a given vertex. } \details{ -The closeness centrality of a vertex is defined as the inverse of the -sum of distances to all the other vertices in the graph: +The closeness centrality of a vertex is defined as the inverse of the sum of distances to all the other vertices in the graph: \deqn{\frac{1}{\sum_{i\ne v} d_{vi}}}{1/sum( d(v,i), i != v)} -If there is no (directed) path between vertex \code{v} and \code{i}, then -\code{i} is omitted from the calculation. If no other vertices are reachable -from \code{v}, then its closeness is returned as NaN. +If there is no (directed) path between vertex \code{v} and \code{i}, then \code{i} is omitted from the calculation. +If no other vertices are reachable from \code{v}, then its closeness is returned as NaN. -\code{cutoff} or smaller. This can be run for larger graphs, as the running -time is not quadratic (if \code{cutoff} is small). If \code{cutoff} is -negative (which is the default), then the function calculates the exact -closeness scores. Since igraph 1.6.0, a \code{cutoff} value of zero is treated -literally, i.e. path with a length greater than zero are ignored. +\code{cutoff} or smaller. +This can be run for larger graphs, as the running time is not quadratic (if \code{cutoff} is small). +If \code{cutoff} is negative (which is the default), then the function calculates the exact closeness scores. +Since igraph 1.6.0, a \code{cutoff} value of zero is treated literally, i.e. path with a length greater than zero are ignored. -Closeness centrality is meaningful only for connected graphs. In disconnected -graphs, consider using the harmonic centrality with -\code{\link[=harmonic_centrality]{harmonic_centrality()}} +Closeness centrality is meaningful only for connected graphs. +In disconnected graphs, consider using the harmonic centrality with \code{\link[=harmonic_centrality]{harmonic_centrality()}} } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_closeness_cutoff}{\code{closeness_cutoff()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/cluster.distribution.Rd b/man/cluster.distribution.Rd index 6075fd30f11..f3be0a1645b 100644 --- a/man/cluster.distribution.Rd +++ b/man/cluster.distribution.Rd @@ -9,21 +9,18 @@ cluster.distribution(graph, cumulative = FALSE, mul.size = FALSE, ...) \arguments{ \item{graph}{The graph to analyze.} -\item{cumulative}{Logical, if TRUE the cumulative distirubution (relative -frequency) is calculated.} +\item{cumulative}{Logical, if TRUE the cumulative distirubution (relative frequency) is calculated.} -\item{mul.size}{Logical. If TRUE the relative frequencies will be multiplied -by the cluster sizes.} +\item{mul.size}{Logical. +If TRUE the relative frequencies will be multiplied by the cluster sizes.} \item{...}{For \code{component_distribution()}, forwarded to \code{components()}. -For \code{components()}, \code{is_connected()}, \code{count_components()} and -\code{largest_component()}, these dots must be empty.} +For \code{components()}, \code{is_connected()}, \code{count_components()} and \code{largest_component()}, these dots must be empty.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{cluster.distribution()} was renamed to \code{\link[=component_distribution]{component_distribution()}} to create a more -consistent API. +\code{cluster.distribution()} was renamed to \code{\link[=component_distribution]{component_distribution()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_connected_components}{\code{connected_components()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/cluster_edge_betweenness.Rd b/man/cluster_edge_betweenness.Rd index bc7791975a6..d16b9050303 100644 --- a/man/cluster_edge_betweenness.Rd +++ b/man/cluster_edge_betweenness.Rd @@ -21,69 +21,56 @@ cluster_edge_betweenness( \item{...}{These dots are for future extensions and must be empty.} -\item{weights}{The weights of the edges. It must be a positive numeric vector, -\code{NULL} or \code{NA}. If it is \code{NULL} and the input graph has a -\sQuote{weight} edge attribute, then that attribute will be used. If -\code{NULL} and no such attribute is present, then the edges will have equal -weights. Set this to \code{NA} if the graph was a \sQuote{weight} edge -attribute, but you don't want to use it for community detection. Edge weights -are used to calculate weighted edge betweenness. This means that edges are -interpreted as distances, not as connection strengths.} +\item{weights}{The weights of the edges. +It must be a positive numeric vector, \code{NULL} or \code{NA}. +If it is \code{NULL} and the input graph has a \sQuote{weight} edge attribute, then that attribute will be used. +If \code{NULL} and no such attribute is present, then the edges will have equal weights. +Set this to \code{NA} if the graph was a \sQuote{weight} edge attribute, but you don't want to use it for community detection. +Edge weights are used to calculate weighted edge betweenness. +This means that edges are interpreted as distances, not as connection strengths.} -\item{directed}{Logical, whether to calculate directed edge -betweenness for directed graphs. It is ignored for undirected graphs.} +\item{directed}{Logical, whether to calculate directed edge betweenness for directed graphs. +It is ignored for undirected graphs.} -\item{edge.betweenness}{Logical, whether to return the edge -betweenness of the edges at the time of their removal.} +\item{edge.betweenness}{Logical, whether to return the edge betweenness of the edges at the time of their removal.} -\item{merges}{Logical, whether to return the merge matrix -representing the hierarchical community structure of the network. This -argument is called \code{merges}, even if the community structure algorithm -itself is divisive and not agglomerative: it builds the tree from top to -bottom. There is one line for each merge (i.e. split) in matrix, the first -line is the first merge (last split). The communities are identified by -integer number starting from one. Community IDs smaller than or equal to -\eqn{N}, the number of vertices in the graph, belong to singleton -communities, i.e. individual vertices. Before the first merge we have \eqn{N} -communities numbered from one to \eqn{N}. The first merge, the first line of -the matrix creates community \eqn{N+1}, the second merge creates community -\eqn{N+2}, etc.} +\item{merges}{Logical, +whether to return the merge matrix representing the hierarchical community structure of the network. +This argument is called \code{merges}, even if the community structure algorithm itself is divisive and not agglomerative: +it builds the tree from top to bottom. +There is one line for each merge (i.e. split) in matrix, the first line is the first merge (last split). +The communities are identified by integer number starting from one. +Community IDs smaller than or equal to \eqn{N}, the number of vertices in the graph, belong to singleton communities, +i.e. individual vertices. +Before the first merge we have \eqn{N} communities numbered from one to \eqn{N}. +The first merge, the first line of the matrix creates community \eqn{N+1}, the second merge creates community \eqn{N+2}, etc.} -\item{bridges}{Logical, whether to return a list the edge removals -which actually splitted a component of the graph.} +\item{bridges}{Logical, whether to return a list the edge removals which actually splitted a component of the graph.} -\item{modularity}{Logical, whether to calculate the maximum -modularity score, considering all possibly community structures along the -edge-betweenness based edge removals.} +\item{modularity}{Logical, whether to calculate the maximum modularity score, +considering all possibly community structures along the edge-betweenness based edge removals.} -\item{membership}{Logical, whether to calculate the membership -vector corresponding to the highest possible modularity score.} +\item{membership}{Logical, whether to calculate the membership vector corresponding to the highest possible modularity score.} } \value{ -\code{cluster_edge_betweenness()} returns a -\code{\link[=communities]{communities()}} object, please see the \code{\link[=communities]{communities()}} -manual page for details. +\code{cluster_edge_betweenness()} returns a \code{\link[=communities]{communities()}} object, please see the \code{\link[=communities]{communities()}} manual page for details. } \description{ -Community structure detection based on the betweenness of the edges -in the network. This method is also known as the Girvan-Newman -algorithm. +Community structure detection based on the betweenness of the edges in the network. +This method is also known as the Girvan-Newman algorithm. } \details{ -The idea behind this method is that the betweenness of the edges connecting -two communities is typically high, as many of the shortest paths between -vertices in separate communities pass through them. The algorithm -successively removes edges with the highest betweenness, recalculating -betweenness values after each removal. This way eventually the network splits -into two components, then one of these components splits again, and so on, -until all edges are removed. The resulting hierarhical partitioning of the -vertices can be encoded as a dendrogram. +The idea behind this method is that the betweenness of the edges connecting two communities is typically high, +as many of the shortest paths between vertices in separate communities pass through them. +The algorithm successively removes edges with the highest betweenness, recalculating betweenness values after each removal. +This way eventually the network splits into two components, then one of these components splits again, and so on, +until all edges are removed. +The resulting hierarhical partitioning of the vertices can be encoded as a dendrogram. -\code{cluster_edge_betweenness()} returns various information collected -through the run of the algorithm. Specifically, \code{removed.edges} contains -the edge IDs in order of the edges' removal; \code{edge.betweenness} contains -the betweenness of each of these at the time of their removal; and -\code{bridges} contains the IDs of edges whose removal caused a split. +\code{cluster_edge_betweenness()} returns various information collected through the run of the algorithm. +Specifically, \code{removed.edges} contains the edge IDs in order of the edges' removal; +\code{edge.betweenness} contains the betweenness of each of these at the time of their removal; +and \code{bridges} contains the IDs of edges whose removal caused a split. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} @@ -105,14 +92,10 @@ M Newman and M Girvan: Finding and evaluating community structure in networks, \emph{Physical Review E} 69, 026113 (2004) } \seealso{ -\code{\link[=edge_betweenness]{edge_betweenness()}} for the definition and calculation -of the edge betweenness, \code{\link[=cluster_walktrap]{cluster_walktrap()}}, -\code{\link[=cluster_fast_greedy]{cluster_fast_greedy()}}, -\code{\link[=cluster_leading_eigen]{cluster_leading_eigen()}} for other community detection -methods. +\code{\link[=edge_betweenness]{edge_betweenness()}} for the definition and calculation of the edge betweenness, \code{\link[=cluster_walktrap]{cluster_walktrap()}}, \code{\link[=cluster_fast_greedy]{cluster_fast_greedy()}}, +\code{\link[=cluster_leading_eigen]{cluster_leading_eigen()}} for other community detection methods. -See \code{\link[=communities]{communities()}} for extracting the results of the community -detection. +See \code{\link[=communities]{communities()}} for extracting the results of the community detection. Community detection: \code{\link[=as_membership]{as_membership()}}, diff --git a/man/cluster_fast_greedy.Rd b/man/cluster_fast_greedy.Rd index 9dfe46e537f..2794dd942c7 100644 --- a/man/cluster_fast_greedy.Rd +++ b/man/cluster_fast_greedy.Rd @@ -14,41 +14,34 @@ cluster_fast_greedy( ) } \arguments{ -\item{graph}{The input graph. It must be undirected and must not have -multi-edges.} +\item{graph}{The input graph. +It must be undirected and must not have multi-edges.} \item{...}{These dots are for future extensions and must be empty.} \item{merges}{Logical, whether to return the merge matrix.} -\item{modularity}{Logical, whether to return a vector containing the -modularity after each merge.} +\item{modularity}{Logical, whether to return a vector containing the modularity after each merge.} -\item{membership}{Logical, whether to calculate the membership vector -corresponding to the maximum modularity score, considering all possible -community structures along the merges.} +\item{membership}{Logical, whether to calculate the membership vector corresponding to the maximum modularity score, +considering all possible community structures along the merges.} -\item{weights}{The weights of the edges. It must be a positive numeric vector, -\code{NULL} or \code{NA}. If it is \code{NULL} and the input graph has a -\sQuote{weight} edge attribute, then that attribute will be used. If -\code{NULL} and no such attribute is present, then the edges will have equal -weights. Set this to \code{NA} if the graph was a \sQuote{weight} edge -attribute, but you don't want to use it for community detection. A larger -edge weight means a stronger connection for this function.} +\item{weights}{The weights of the edges. +It must be a positive numeric vector, \code{NULL} or \code{NA}. +If it is \code{NULL} and the input graph has a \sQuote{weight} edge attribute, then that attribute will be used. +If \code{NULL} and no such attribute is present, then the edges will have equal weights. +Set this to \code{NA} if the graph was a \sQuote{weight} edge attribute, but you don't want to use it for community detection. +A larger edge weight means a stronger connection for this function.} } \value{ -\code{cluster_fast_greedy()} returns a \code{\link[=communities]{communities()}} -object, please see the \code{\link[=communities]{communities()}} manual page for details. +\code{cluster_fast_greedy()} returns a \code{\link[=communities]{communities()}} object, please see the \code{\link[=communities]{communities()}} manual page for details. } \description{ -This function tries to find dense subgraph, also called communities in -graphs via directly optimizing a modularity score. +This function tries to find dense subgraph, also called communities in graphs via directly optimizing a modularity score. } \details{ -This function implements the fast greedy modularity optimization algorithm -for finding community structure, see A Clauset, MEJ Newman, C Moore: Finding -community structure in very large networks, -http://www.arxiv.org/abs/cond-mat/0408187 for the details. +This function implements the fast greedy modularity optimization algorithm for finding community structure, see A Clauset, MEJ Newman, +C Moore: Finding community structure in very large networks, http://www.arxiv.org/abs/cond-mat/0408187 for the details. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} @@ -70,11 +63,8 @@ very large networks, http://www.arxiv.org/abs/cond-mat/0408187 \seealso{ \code{\link[=communities]{communities()}} for extracting the results. -See also \code{\link[=cluster_walktrap]{cluster_walktrap()}}, -\code{\link[=cluster_spinglass]{cluster_spinglass()}}, -\code{\link[=cluster_leading_eigen]{cluster_leading_eigen()}} and -\code{\link[=cluster_edge_betweenness]{cluster_edge_betweenness()}}, \code{\link[=cluster_louvain]{cluster_louvain()}} -\code{\link[=cluster_leiden]{cluster_leiden()}} for other methods. +See also \code{\link[=cluster_walktrap]{cluster_walktrap()}}, \code{\link[=cluster_spinglass]{cluster_spinglass()}}, \code{\link[=cluster_leading_eigen]{cluster_leading_eigen()}} and \code{\link[=cluster_edge_betweenness]{cluster_edge_betweenness()}}, +\code{\link[=cluster_louvain]{cluster_louvain()}} \code{\link[=cluster_leiden]{cluster_leiden()}} for other methods. Community detection: \code{\link[=as_membership]{as_membership()}}, diff --git a/man/cluster_fluid_communities.Rd b/man/cluster_fluid_communities.Rd index a5f0a50531f..dce8a319917 100644 --- a/man/cluster_fluid_communities.Rd +++ b/man/cluster_fluid_communities.Rd @@ -7,22 +7,21 @@ cluster_fluid_communities(graph, no.of.communities) } \arguments{ -\item{graph}{The input graph. The graph must be simple and connected. +\item{graph}{The input graph. +The graph must be simple and connected. Empty graphs are not supported as well as single vertex graphs. -Edge directions are ignored. Weights are not considered.} +Edge directions are ignored. +Weights are not considered.} -\item{no.of.communities}{The number of communities to be found. Must be -greater than 0 and fewer than number of vertices in the graph.} +\item{no.of.communities}{The number of communities to be found. +Must be greater than 0 and fewer than number of vertices in the graph.} } \value{ -\code{cluster_fluid_communities()} returns a \code{\link[=communities]{communities()}} -object, please see the \code{\link[=communities]{communities()}} manual page for details. +\code{cluster_fluid_communities()} returns a \code{\link[=communities]{communities()}} object, please see the \code{\link[=communities]{communities()}} manual page for details. } \description{ -The algorithm detects communities based on the simple idea of -several fluids interacting in a non-homogeneous environment -(the graph topology), expanding and contracting based on their -interaction and density. +The algorithm detects communities based on the simple idea of several fluids interacting in a non-homogeneous environment (the graph topology), +expanding and contracting based on their interaction and density. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Community.html#igraph_community_fluid_communities}{\code{community_fluid_communities()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} @@ -43,14 +42,8 @@ Springer, vol 689, p 229, doi: 10.1007/978-3-319-72150-7_19 See \code{\link[=communities]{communities()}} for extracting the membership, modularity scores, etc. from the results. -Other community detection algorithms: \code{\link[=cluster_walktrap]{cluster_walktrap()}}, -\code{\link[=cluster_spinglass]{cluster_spinglass()}}, -\code{\link[=cluster_leading_eigen]{cluster_leading_eigen()}}, -\code{\link[=cluster_edge_betweenness]{cluster_edge_betweenness()}}, -\code{\link[=cluster_fast_greedy]{cluster_fast_greedy()}}, -\code{\link[=cluster_label_prop]{cluster_label_prop()}} -\code{\link[=cluster_louvain]{cluster_louvain()}}, -\code{\link[=cluster_leiden]{cluster_leiden()}} +Other community detection algorithms: \code{\link[=cluster_walktrap]{cluster_walktrap()}}, \code{\link[=cluster_spinglass]{cluster_spinglass()}}, \code{\link[=cluster_leading_eigen]{cluster_leading_eigen()}}, +\code{\link[=cluster_edge_betweenness]{cluster_edge_betweenness()}}, \code{\link[=cluster_fast_greedy]{cluster_fast_greedy()}}, \code{\link[=cluster_label_prop]{cluster_label_prop()}} \code{\link[=cluster_louvain]{cluster_louvain()}}, \code{\link[=cluster_leiden]{cluster_leiden()}} Community detection: \code{\link[=as_membership]{as_membership()}}, diff --git a/man/cluster_infomap.Rd b/man/cluster_infomap.Rd index 4fdd32e356d..c313b9fe68f 100644 --- a/man/cluster_infomap.Rd +++ b/man/cluster_infomap.Rd @@ -14,37 +14,34 @@ cluster_infomap( ) } \arguments{ -\item{graph}{The input graph. Edge directions will be taken into account.} +\item{graph}{The input graph. +Edge directions will be taken into account.} \item{...}{These dots are for future extensions and must be empty.} \item{e.weights}{Numeric vector of edge weights. -The length must match the number of edges in the graph. By default (\code{NULL}) the -\sQuote{\code{weight}} edge attribute is used as weights. If it is not -present, then all edges are considered to have the same weight. +The length must match the number of edges in the graph. +By default (\code{NULL}) the \sQuote{\code{weight}} edge attribute is used as weights. +If it is not present, then all edges are considered to have the same weight. Larger edge weights correspond to stronger connections.} -\item{v.weights}{Numeric vector of vertex -weights. The length must match the number of vertices in the graph. By -default (\code{NULL}) the \sQuote{\code{weight}} vertex attribute is used as weights. If -it is not present, then all vertices are considered to have the same weight. -A larger vertex weight means a larger probability that the random surfer -jumps to that vertex.} +\item{v.weights}{Numeric vector of vertex weights. +The length must match the number of vertices in the graph. +By default (\code{NULL}) the \sQuote{\code{weight}} vertex attribute is used as weights. +If it is not present, then all vertices are considered to have the same weight. +A larger vertex weight means a larger probability that the random surfer jumps to that vertex.} -\item{nb.trials}{The number of attempts to partition the network (can be any -integer value equal or larger than 1).} +\item{nb.trials}{The number of attempts to partition the network (can be any integer value equal or larger than 1).} -\item{modularity}{Logical, whether to calculate the modularity score -of the detected community structure.} +\item{modularity}{Logical, whether to calculate the modularity score of the detected community structure.} } \value{ \code{cluster_infomap()} returns a \code{\link[=communities]{communities()}} object, please see the \code{\link[=communities]{communities()}} manual page for details. } \description{ -Find community structure that minimizes the expected description length of a -random walker trajectory. If the graph is directed, edge directions will -be taken into account. +Find community structure that minimizes the expected description length of a random walker trajectory. +If the graph is directed, edge directions will be taken into account. } \details{ Please see the details of this method in the references given below. @@ -98,8 +95,8 @@ Community detection: } \author{ Martin Rosvall wrote the original C++ code. This was ported to -be more igraph-like by Emmanuel Navarro. The R interface and -some cosmetics was done by Gabor Csardi \email{csardi.gabor@gmail.com}. +be more igraph-like by Emmanuel Navarro. +The R interface and some cosmetics was done by Gabor Csardi \email{csardi.gabor@gmail.com}. } \concept{community} \keyword{graphs} diff --git a/man/cluster_label_prop.Rd b/man/cluster_label_prop.Rd index c8e4ded1b7c..14bcb821511 100644 --- a/man/cluster_label_prop.Rd +++ b/man/cluster_label_prop.Rd @@ -14,53 +14,47 @@ cluster_label_prop( ) } \arguments{ -\item{graph}{The input graph. Note that the algorithm was originally -defined for undirected graphs. You are advised to set \sQuote{mode} to -\code{all} if you pass a directed graph here to treat it as -undirected.} +\item{graph}{The input graph. +Note that the algorithm was originally defined for undirected graphs. +You are advised to set \sQuote{mode} to \code{all} if you pass a directed graph here to treat it as undirected.} -\item{weights}{The weights of the edges. It must be a positive numeric vector, -\code{NULL} or \code{NA}. If it is \code{NULL} and the input graph has a -\sQuote{weight} edge attribute, then that attribute will be used. If -\code{NULL} and no such attribute is present, then the edges will have equal -weights. Set this to \code{NA} if the graph was a \sQuote{weight} edge -attribute, but you don't want to use it for community detection. A larger -edge weight means a stronger connection for this function.} +\item{weights}{The weights of the edges. +It must be a positive numeric vector, \code{NULL} or \code{NA}. +If it is \code{NULL} and the input graph has a \sQuote{weight} edge attribute, then that attribute will be used. +If \code{NULL} and no such attribute is present, then the edges will have equal weights. +Set this to \code{NA} if the graph was a \sQuote{weight} edge attribute, but you don't want to use it for community detection. +A larger edge weight means a stronger connection for this function.} \item{...}{These dots are for future extensions and must be empty.} -\item{mode}{Logical, whether to consider edge directions for the label propagation, -and if so, in which direction the labels should propagate. Ignored for undirected graphs. +\item{mode}{Logical, whether to consider edge directions for the label propagation, and if so, +in which direction the labels should propagate. +Ignored for undirected graphs. "all" means to ignore edge directions (even in directed graphs). "out" means to propagate labels along the natural direction of the edges. "in" means to propagate labels backwards (i.e. from head to tail).} -\item{initial}{The initial state. If \code{NULL}, every vertex will have a -different label at the beginning. Otherwise it must be a vector with an -entry for each vertex. Non-negative values denote different labels, negative -entries denote vertices without labels.} +\item{initial}{The initial state. +If \code{NULL}, every vertex will have a different label at the beginning. +Otherwise it must be a vector with an entry for each vertex. +Non-negative values denote different labels, negative entries denote vertices without labels.} -\item{fixed}{Logical vector denoting which labels are fixed. Of course this -makes sense only if you provided an initial state, otherwise this element -will be ignored. Also note that vertices without labels cannot be fixed.} +\item{fixed}{Logical vector denoting which labels are fixed. +Of course this makes sense only if you provided an initial state, otherwise this element will be ignored. +Also note that vertices without labels cannot be fixed.} } \value{ -\code{cluster_label_prop()} returns a -\code{\link[=communities]{communities()}} object, please see the \code{\link[=communities]{communities()}} -manual page for details. +\code{cluster_label_prop()} returns a \code{\link[=communities]{communities()}} object, please see the \code{\link[=communities]{communities()}} manual page for details. } \description{ -This is a fast, nearly linear time algorithm for detecting community -structure in networks. In works by labeling the vertices with unique labels -and then updating the labels by majority voting in the neighborhood of the -vertex. +This is a fast, nearly linear time algorithm for detecting community structure in networks. +In works by labeling the vertices with unique labels and then updating the labels by majority voting in the neighborhood of the vertex. } \details{ -This function implements the community detection method described in: -Raghavan, U.N. and Albert, R. and Kumara, S.: Near linear time algorithm to -detect community structures in large-scale networks. Phys Rev E 76, 036106. -(2007). This version extends the original method by the ability to take edge -weights into consideration and also by allowing some labels to be fixed. +This function implements the community detection method described in: Raghavan, U.N. and Albert, R. and Kumara, S.: +Near linear time algorithm to detect community structures in large-scale networks. +Phys Rev E 76, 036106. (2007). +This version extends the original method by the ability to take edge weights into consideration and also by allowing some labels to be fixed. From the abstract of the paper: \dQuote{In our algorithm every node is initialized with a unique label and at every step each node adopts the label @@ -87,9 +81,8 @@ Rev E} 76, 036106. (2007) \seealso{ \code{\link[=communities]{communities()}} for extracting the actual results. -\code{\link[=cluster_fast_greedy]{cluster_fast_greedy()}}, \code{\link[=cluster_walktrap]{cluster_walktrap()}}, -\code{\link[=cluster_spinglass]{cluster_spinglass()}}, \code{\link[=cluster_louvain]{cluster_louvain()}} and -\code{\link[=cluster_leiden]{cluster_leiden()}} for other community detection methods. +\code{\link[=cluster_fast_greedy]{cluster_fast_greedy()}}, \code{\link[=cluster_walktrap]{cluster_walktrap()}}, \code{\link[=cluster_spinglass]{cluster_spinglass()}}, +\code{\link[=cluster_louvain]{cluster_louvain()}} and \code{\link[=cluster_leiden]{cluster_leiden()}} for other community detection methods. Community detection: \code{\link[=as_membership]{as_membership()}}, diff --git a/man/cluster_leading_eigen.Rd b/man/cluster_leading_eigen.Rd index 0d0930fe880..62ecffba98b 100644 --- a/man/cluster_leading_eigen.Rd +++ b/man/cluster_leading_eigen.Rd @@ -2,8 +2,7 @@ % Please edit documentation in R/community.R \name{cluster_leading_eigen} \alias{cluster_leading_eigen} -\title{Community structure detecting based on the leading eigenvector of the -community matrix} +\title{Community structure detecting based on the leading eigenvector of the community matrix} \usage{ cluster_leading_eigen( graph, @@ -17,36 +16,34 @@ cluster_leading_eigen( ) } \arguments{ -\item{graph}{The input graph. Should be undirected as the method needs a -symmetric matrix.} +\item{graph}{The input graph. +Should be undirected as the method needs a symmetric matrix.} -\item{steps}{The number of steps to take, this is actually the number of -tries to make a step. It is not a particularly useful parameter.} +\item{steps}{The number of steps to take, this is actually the number of tries to make a step. +It is not a particularly useful parameter.} -\item{weights}{The weights of the edges. It must be a positive numeric vector, -\code{NULL} or \code{NA}. If it is \code{NULL} and the input graph has a -\sQuote{weight} edge attribute, then that attribute will be used. If -\code{NULL} and no such attribute is present, then the edges will have equal -weights. Set this to \code{NA} if the graph was a \sQuote{weight} edge -attribute, but you don't want to use it for community detection. A larger -edge weight means a stronger connection for this function.} +\item{weights}{The weights of the edges. +It must be a positive numeric vector, \code{NULL} or \code{NA}. +If it is \code{NULL} and the input graph has a \sQuote{weight} edge attribute, then that attribute will be used. +If \code{NULL} and no such attribute is present, then the edges will have equal weights. +Set this to \code{NA} if the graph was a \sQuote{weight} edge attribute, but you don't want to use it for community detection. +A larger edge weight means a stronger connection for this function.} -\item{start}{\code{NULL}, or a numeric membership vector, giving the start -configuration of the algorithm.} +\item{start}{\code{NULL}, or a numeric membership vector, giving the start configuration of the algorithm.} \item{options}{A named list to override some ARPACK options.} -\item{callback}{Callback function. This -is called after each iteration, after calculating the leading eigenvector of -the modularity matrix. See details below. Default: \code{NULL}.} +\item{callback}{Callback function. +This is called after each iteration, after calculating the leading eigenvector of the modularity matrix. +See details below. +Default: \code{NULL}.} \item{extra}{Additional argument to supply to the callback function.} \item{env}{The environment in which the callback function is evaluated.} } \value{ -\code{cluster_leading_eigen()} returns a named list with the -following members: +\code{cluster_leading_eigen()} returns a named list with the following members: \describe{ \item{membership}{ The membership vector at the end of the algorithm, @@ -66,34 +63,26 @@ Information about the underlying ARPACK computation, see \code{\link[=arpack]{ar } } \description{ -This function tries to find densely connected subgraphs in a graph by -calculating the leading non-negative eigenvector of the modularity matrix of -the graph. +This function tries to find densely connected subgraphs in a graph by calculating the leading non-negative eigenvector of the modularity matrix of the graph. } \details{ The function documented in these section implements the \sQuote{leading eigenvector} method developed by Mark Newman, see the reference below. -The heart of the method is the definition of the modularity matrix, -\code{B}, which is \code{B=A-P}, \code{A} being the adjacency matrix of the -(undirected) network, and \code{P} contains the probability that certain -edges are present according to the \sQuote{configuration model}. In other -words, a \code{P[i,j]} element of \code{P} is the probability that there is -an edge between vertices \code{i} and \code{j} in a random network in which -the degrees of all vertices are the same as in the input graph. - -The leading eigenvector method works by calculating the eigenvector of the -modularity matrix for the largest positive eigenvalue and then separating -vertices into two community based on the sign of the corresponding element -in the eigenvector. If all elements in the eigenvector are of the same sign -that means that the network has no underlying comuunity structure. Check -Newman's paper to understand why this is a good method for detecting -community structure. +The heart of the method is the definition of the modularity matrix, \code{B}, which is \code{B=A-P}, +\code{A} being the adjacency matrix of the (undirected) network, +and \code{P} contains the probability that certain edges are present according to the \sQuote{configuration model}. +In other words, +a \code{P[i,j]} element of \code{P} is the probability that there is an edge between vertices \code{i} and \code{j} in a random network in which the degrees of all vertices are the same as in the input graph. + +The leading eigenvector method works by calculating the eigenvector of the modularity matrix for the largest positive eigenvalue and then separating vertices into two community based on the sign of the corresponding element in the eigenvector. +If all elements in the eigenvector are of the same sign that means that the network has no underlying comuunity structure. +Check Newman's paper to understand why this is a good method for detecting community structure. } \section{Callback functions}{ The \code{callback} argument can be used to -supply a function that is called after each eigenvector calculation. The -following arguments are supplied to this function: +supply a function that is called after each eigenvector calculation. +The following arguments are supplied to this function: \describe{ \item{membership}{ @@ -119,8 +108,8 @@ The \code{extra} argument that was passed to \code{cluster_leading_eigen()}. } } -The callback function should return a scalar number. If this number -is non-zero, then the clustering is terminated. +The callback function should return a scalar number. +If this number is non-zero, then the clustering is terminated. } \section{Related documentation in the C library}{ diff --git a/man/cluster_leiden.Rd b/man/cluster_leiden.Rd index cb4b00aacef..3c71294751f 100644 --- a/man/cluster_leiden.Rd +++ b/man/cluster_leiden.Rd @@ -19,91 +19,78 @@ cluster_leiden( ) } \arguments{ -\item{graph}{The input graph. It must be undirected.} +\item{graph}{The input graph. +It must be undirected.} -\item{objective_function}{Whether to use the Constant Potts Model (CPM) or -modularity. Must be either \code{"CPM"} or \code{"modularity"}.} +\item{objective_function}{Whether to use the Constant Potts Model (CPM) or modularity. +Must be either \code{"CPM"} or \code{"modularity"}.} \item{...}{These dots are for future extensions and must be empty.} -\item{weights}{The weights of the edges. It must be a positive numeric vector, -\code{NULL} or \code{NA}. If it is \code{NULL} and the input graph has a -\sQuote{weight} edge attribute, then that attribute will be used. If -\code{NULL} and no such attribute is present, then the edges will have equal -weights. Set this to \code{NA} if the graph was a \sQuote{weight} edge -attribute, but you don't want to use it for community detection. A larger -edge weight means a stronger connection for this function.} +\item{weights}{The weights of the edges. +It must be a positive numeric vector, \code{NULL} or \code{NA}. +If it is \code{NULL} and the input graph has a \sQuote{weight} edge attribute, then that attribute will be used. +If \code{NULL} and no such attribute is present, then the edges will have equal weights. +Set this to \code{NA} if the graph was a \sQuote{weight} edge attribute, but you don't want to use it for community detection. +A larger edge weight means a stronger connection for this function.} -\item{resolution}{The resolution parameter to use. Higher -resolutions lead to more smaller communities, while lower resolutions lead -to fewer larger communities.} +\item{resolution}{The resolution parameter to use. +Higher resolutions lead to more smaller communities, while lower resolutions lead to fewer larger communities.} \item{resolution_parameter}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#superseded}{\figure{lifecycle-superseded.svg}{options: alt='[Superseded]'}}}{\strong{[Superseded]}} Use \code{resolution} instead.} \item{beta}{Parameter affecting the randomness in the Leiden algorithm. This affects only the refinement step of the algorithm.} -\item{initial_membership}{If provided, the Leiden algorithm -will try to improve this provided membership. If no argument is -provided, the aglorithm simply starts from the singleton partition.} +\item{initial_membership}{If provided, the Leiden algorithm will try to improve this provided membership. +If no argument is provided, the aglorithm simply starts from the singleton partition.} -\item{n_iterations}{the number of iterations to iterate the Leiden -algorithm. Each iteration may improve the partition further.} +\item{n_iterations}{the number of iterations to iterate the Leiden algorithm. +Each iteration may improve the partition further.} \item{vertex_weights}{the vertex weights used in the Leiden algorithm. -If this is not provided, it will be automatically determined on the basis -of the \code{objective_function}. Please see the details of this function -how to interpret the vertex weights.} +If this is not provided, it will be automatically determined on the basis of the \code{objective_function}. +Please see the details of this function how to interpret the vertex weights.} } \value{ -\code{cluster_leiden()} returns a \code{\link[=communities]{communities()}} -object, please see the \code{\link[=communities]{communities()}} manual page for details. +\code{cluster_leiden()} returns a \code{\link[=communities]{communities()}} object, please see the \code{\link[=communities]{communities()}} manual page for details. } \description{ -The Leiden algorithm is similar to the Louvain algorithm, -\code{\link[=cluster_louvain]{cluster_louvain()}}, but it is faster and yields higher quality -solutions. It can optimize both modularity and the Constant Potts Model, -which does not suffer from the resolution-limit (see preprint -\url{https://arxiv.org/abs/1104.3083}). +The Leiden algorithm is similar to the Louvain algorithm, \code{\link[=cluster_louvain]{cluster_louvain()}}, but it is faster and yields higher quality solutions. +It can optimize both modularity and the Constant Potts Model, +which does not suffer from the resolution-limit (see preprint \url{https://arxiv.org/abs/1104.3083}). } \details{ The Leiden algorithm consists of three phases: (1) local moving of nodes, -(2) refinement of the partition and (3) aggregation of the network based on -the refined partition, using the non-refined partition to create an initial -partition for the aggregate network. In the local move procedure in the -Leiden algorithm, only nodes whose neighborhood has changed are visited. The -refinement is done by restarting from a singleton partition within each -cluster and gradually merging the subclusters. When aggregating, a single -cluster may then be represented by several nodes (which are the subclusters -identified in the refinement). - -The Leiden algorithm provides several guarantees. The Leiden algorithm is -typically iterated: the output of one iteration is used as the input for the -next iteration. At each iteration all clusters are guaranteed to be -connected and well-separated. After an iteration in which nothing has -changed, all nodes and some parts are guaranteed to be locally optimally -assigned. Finally, asymptotically, all subsets of all clusters are -guaranteed to be locally optimally assigned. For more details, please see -Traag, Waltman & van Eck (2019). +(2) refinement of the partition and (3) aggregation of the network based on the refined partition, +using the non-refined partition to create an initial partition for the aggregate network. +In the local move procedure in the Leiden algorithm, only nodes whose neighborhood has changed are visited. +The refinement is done by restarting from a singleton partition within each cluster and gradually merging the subclusters. +When aggregating, a single cluster may then be represented by several nodes (which are the subclusters identified in the refinement). + +The Leiden algorithm provides several guarantees. +The Leiden algorithm is typically iterated: the output of one iteration is used as the input for the next iteration. +At each iteration all clusters are guaranteed to be connected and well-separated. +After an iteration in which nothing has changed, all nodes and some parts are guaranteed to be locally optimally assigned. +Finally, asymptotically, all subsets of all clusters are guaranteed to be locally optimally assigned. +For more details, please see Traag, Waltman & van Eck (2019). The objective function being optimized is \deqn{\frac{1}{2m} \sum_{ij} (A_{ij} - \gamma n_i n_j)\delta(\sigma_i, \sigma_j)}{1 / 2m sum_ij (A_ij - gamma n_i n_j)d(s_i, s_j)} -where \eqn{m}{m} is the total edge weight, \eqn{A_{ij}}{A_ij} is the weight -of edge \eqn{(i, j)}, \eqn{\gamma}{gamma} is the so-called resolution -parameter, \eqn{n_i} is the node weight of node \eqn{i}, \eqn{\sigma_i}{s_i} -is the cluster of node \eqn{i} and \eqn{\delta(x, y) = 1}{d(x, y) = 1} if and -only if \eqn{x = y} and \eqn{0} otherwise. By setting \eqn{n_i = k_i}, the -degree of node \eqn{i}, and dividing \eqn{\gamma}{gamma} by \eqn{2m}, you -effectively obtain an expression for modularity. - -Hence, the standard modularity will be optimized when you supply the degrees -as \code{vertex_weights} and by supplying as a resolution parameter -\eqn{\frac{1}{2m}}{1/(2m)}, with \eqn{m} the number of edges. If you do not -specify any \code{vertex_weights}, the correct vertex weights and scaling of -\eqn{\gamma}{gamma} is determined automatically by the -\code{objective_function} argument. +where \eqn{m}{m} is the total edge weight, \eqn{A_{ij}}{A_ij} is the weight of edge \eqn{(i, j)}, +\eqn{\gamma}{gamma} is the so-called resolution parameter, \eqn{n_i} is the node weight of node \eqn{i}, +\eqn{\sigma_i}{s_i} is the cluster of node \eqn{i} and \eqn{\delta(x, y) = 1}{d(x, y) = 1} if and only +if \eqn{x = y} and \eqn{0} otherwise. +By setting \eqn{n_i = k_i}, the degree of node \eqn{i}, and dividing \eqn{\gamma}{gamma} by \eqn{2m}, +you effectively obtain an expression for modularity. + +Hence, the standard modularity will be optimized +when you supply the degrees as \code{vertex_weights} and by supplying as a resolution parameter \eqn{\frac{1}{2m}}{1/(2m)}, +with \eqn{m} the number of edges. +If you do not specify any \code{vertex_weights}, +the correct vertex weights and scaling of \eqn{\gamma}{gamma} is determined automatically by the \code{objective_function} argument. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Community.html#igraph_community_leiden}{\code{community_leiden()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_strength}{\code{strength()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} @@ -128,17 +115,9 @@ reports, 9(1), 5233. doi: 10.1038/s41598-019-41695-z, arXiv:1810.08473v3 [cs.SI] See \code{\link[=communities]{communities()}} for extracting the membership, modularity scores, etc. from the results. -Other community detection algorithms: \code{\link[=cluster_walktrap]{cluster_walktrap()}}, -\code{\link[=cluster_spinglass]{cluster_spinglass()}}, -\code{\link[=cluster_leading_eigen]{cluster_leading_eigen()}}, -\code{\link[=cluster_edge_betweenness]{cluster_edge_betweenness()}}, -\code{\link[=cluster_fast_greedy]{cluster_fast_greedy()}}, -\code{\link[=cluster_label_prop]{cluster_label_prop()}} -\code{\link[=cluster_louvain]{cluster_louvain()}} -\code{\link[=cluster_fluid_communities]{cluster_fluid_communities()}} -\code{\link[=cluster_infomap]{cluster_infomap()}} -\code{\link[=cluster_optimal]{cluster_optimal()}} -\code{\link[=cluster_walktrap]{cluster_walktrap()}} +Other community detection algorithms: \code{\link[=cluster_walktrap]{cluster_walktrap()}}, \code{\link[=cluster_spinglass]{cluster_spinglass()}}, \code{\link[=cluster_leading_eigen]{cluster_leading_eigen()}}, +\code{\link[=cluster_edge_betweenness]{cluster_edge_betweenness()}}, \code{\link[=cluster_fast_greedy]{cluster_fast_greedy()}}, +\code{\link[=cluster_label_prop]{cluster_label_prop()}} \code{\link[=cluster_louvain]{cluster_louvain()}} \code{\link[=cluster_fluid_communities]{cluster_fluid_communities()}} \code{\link[=cluster_infomap]{cluster_infomap()}} \code{\link[=cluster_optimal]{cluster_optimal()}} \code{\link[=cluster_walktrap]{cluster_walktrap()}} Community detection: \code{\link[=as_membership]{as_membership()}}, diff --git a/man/cluster_louvain.Rd b/man/cluster_louvain.Rd index 0d211308e7b..d4de4e25171 100644 --- a/man/cluster_louvain.Rd +++ b/man/cluster_louvain.Rd @@ -7,48 +7,42 @@ cluster_louvain(graph, ..., weights = NULL, resolution = 1) } \arguments{ -\item{graph}{The input graph. It must be undirected.} +\item{graph}{The input graph. +It must be undirected.} \item{...}{These dots are for future extensions and must be empty.} -\item{weights}{The weights of the edges. It must be a positive numeric vector, -\code{NULL} or \code{NA}. If it is \code{NULL} and the input graph has a -\sQuote{weight} edge attribute, then that attribute will be used. If -\code{NULL} and no such attribute is present, then the edges will have equal -weights. Set this to \code{NA} if the graph was a \sQuote{weight} edge -attribute, but you don't want to use it for community detection. A larger -edge weight means a stronger connection for this function.} +\item{weights}{The weights of the edges. +It must be a positive numeric vector, \code{NULL} or \code{NA}. +If it is \code{NULL} and the input graph has a \sQuote{weight} edge attribute, then that attribute will be used. +If \code{NULL} and no such attribute is present, then the edges will have equal weights. +Set this to \code{NA} if the graph was a \sQuote{weight} edge attribute, but you don't want to use it for community detection. +A larger edge weight means a stronger connection for this function.} -\item{resolution}{Optional resolution parameter that allows the user to -adjust the resolution parameter of the modularity function that the algorithm -uses internally. Lower values typically yield fewer, larger clusters. The -original definition of modularity is recovered when the resolution parameter -is set to 1.} +\item{resolution}{Optional resolution parameter that allows the user to adjust the resolution parameter of the modularity function that the algorithm uses internally. +Lower values typically yield fewer, larger clusters. +The original definition of modularity is recovered when the resolution parameter is set to 1.} } \value{ -\code{cluster_louvain()} returns a \code{\link[=communities]{communities()}} -object, please see the \code{\link[=communities]{communities()}} manual page for details. +\code{cluster_louvain()} returns a \code{\link[=communities]{communities()}} object, please see the \code{\link[=communities]{communities()}} manual page for details. } \description{ -This function implements the multi-level modularity optimization algorithm -for finding community structure, see references below. It is based on the -modularity measure and a hierarchical approach. +This function implements the multi-level modularity optimization algorithm for finding community structure, see references below. +It is based on the modularity measure and a hierarchical approach. } \details{ -This function implements the multi-level modularity optimization algorithm -for finding community structure, see VD Blondel, J-L Guillaume, R Lambiotte -and E Lefebvre: Fast unfolding of community hierarchies in large networks, +This function implements the multi-level modularity optimization algorithm for finding community structure, see VD Blondel, +J-L Guillaume, R Lambiotte and E Lefebvre: Fast unfolding of community hierarchies in large networks, \url{https://arxiv.org/abs/0803.0476} for the details. It is based on the modularity measure and a hierarchical approach. -Initially, each vertex is assigned to a community on its own. In every step, -vertices are re-assigned to communities in a local, greedy way: each vertex -is moved to the community with which it achieves the highest contribution to -modularity. When no vertices can be reassigned, each community is considered -a vertex on its own, and the process starts again with the merged -communities. The process stops when there is only a single vertex left or -when the modularity cannot be increased any more in a step. Since igraph 1.3, -vertices are processed in a random order. +Initially, each vertex is assigned to a community on its own. +In every step, vertices are re-assigned to communities in a local, greedy way: +each vertex is moved to the community with which it achieves the highest contribution to modularity. +When no vertices can be reassigned, each community is considered a vertex on its own, +and the process starts again with the merged communities. +The process stops when there is only a single vertex left or when the modularity cannot be increased any more in a step. +Since igraph 1.3, vertices are processed in a random order. This function was contributed by Tom Gregorovic. } @@ -73,13 +67,8 @@ Mech. (2008) P10008 See \code{\link[=communities]{communities()}} for extracting the membership, modularity scores, etc. from the results. -Other community detection algorithms: \code{\link[=cluster_walktrap]{cluster_walktrap()}}, -\code{\link[=cluster_spinglass]{cluster_spinglass()}}, -\code{\link[=cluster_leading_eigen]{cluster_leading_eigen()}}, -\code{\link[=cluster_edge_betweenness]{cluster_edge_betweenness()}}, -\code{\link[=cluster_fast_greedy]{cluster_fast_greedy()}}, -\code{\link[=cluster_label_prop]{cluster_label_prop()}} -\code{\link[=cluster_leiden]{cluster_leiden()}} +Other community detection algorithms: \code{\link[=cluster_walktrap]{cluster_walktrap()}}, \code{\link[=cluster_spinglass]{cluster_spinglass()}}, \code{\link[=cluster_leading_eigen]{cluster_leading_eigen()}}, +\code{\link[=cluster_edge_betweenness]{cluster_edge_betweenness()}}, \code{\link[=cluster_fast_greedy]{cluster_fast_greedy()}}, \code{\link[=cluster_label_prop]{cluster_label_prop()}} \code{\link[=cluster_leiden]{cluster_leiden()}} Community detection: \code{\link[=as_membership]{as_membership()}}, diff --git a/man/cluster_optimal.Rd b/man/cluster_optimal.Rd index 22fff574cff..7c9105ab0b9 100644 --- a/man/cluster_optimal.Rd +++ b/man/cluster_optimal.Rd @@ -7,39 +7,35 @@ cluster_optimal(graph, ..., weights = NULL) } \arguments{ -\item{graph}{The input graph. It may be undirected or directed.} +\item{graph}{The input graph. +It may be undirected or directed.} \item{...}{These dots are for future extensions and must be empty.} -\item{weights}{The weights of the edges. It must be a positive numeric -vector, \code{NULL} or \code{NA}. If it is \code{NULL} and the input graph has a -\sQuote{weight} edge attribute, then that attribute will be used. If -\code{NULL} and no such attribute is present, then the edges will have equal -weights. Set this to \code{NA} if the graph was a \sQuote{weight} edge -attribute, but you don't want to use it for community detection. A larger -edge weight means a stronger connection for this function.} +\item{weights}{The weights of the edges. +It must be a positive numeric vector, \code{NULL} or \code{NA}. +If it is \code{NULL} and the input graph has a \sQuote{weight} edge attribute, then that attribute will be used. +If \code{NULL} and no such attribute is present, then the edges will have equal weights. +Set this to \code{NA} if the graph was a \sQuote{weight} edge attribute, but you don't want to use it for community detection. +A larger edge weight means a stronger connection for this function.} } \value{ \code{cluster_optimal()} returns a \code{\link[=communities]{communities()}} object, please see the \code{\link[=communities]{communities()}} manual page for details. } \description{ -This function calculates the optimal community structure of a graph, by -maximizing the modularity measure over all possible partitions. +This function calculates the optimal community structure of a graph, by maximizing the modularity measure over all possible partitions. } \details{ -This function calculates the optimal community structure for a graph, in -terms of maximal modularity score. +This function calculates the optimal community structure for a graph, in terms of maximal modularity score. -The calculation is done by transforming the modularity maximization into an -integer programming problem, and then calling the GLPK library to solve -that. Please the reference below for details. +The calculation is done by transforming the modularity maximization into an integer programming problem, +and then calling the GLPK library to solve that. +Please the reference below for details. -Note that modularity optimization is an NP-complete problem, and all known -algorithms for it have exponential time complexity. This means that you -probably don't want to run this function on larger graphs. Graphs with up to -fifty vertices should be fine, graphs with a couple of hundred vertices -might be possible. +Note that modularity optimization is an NP-complete problem, and all known algorithms for it have exponential time complexity. +This means that you probably don't want to run this function on larger graphs. +Graphs with up to fifty vertices should be fine, graphs with a couple of hundred vertices might be possible. } \section{Examples}{ @@ -75,9 +71,8 @@ Martin Hoefer, Zoran Nikoloski, Dorothea Wagner: On Modularity Clustering, 2008. } \seealso{ -\code{\link[=communities]{communities()}} for the documentation of the result, -\code{\link[=modularity]{modularity()}}. See also \code{\link[=cluster_fast_greedy]{cluster_fast_greedy()}} for a -fast greedy optimizer. +\code{\link[=communities]{communities()}} for the documentation of the result, \code{\link[=modularity]{modularity()}}. +See also \code{\link[=cluster_fast_greedy]{cluster_fast_greedy()}} for a fast greedy optimizer. Community detection: \code{\link[=as_membership]{as_membership()}}, diff --git a/man/cluster_spinglass.Rd b/man/cluster_spinglass.Rd index e34349b282a..a16e102d25e 100644 --- a/man/cluster_spinglass.Rd +++ b/man/cluster_spinglass.Rd @@ -21,79 +21,68 @@ cluster_spinglass( ) } \arguments{ -\item{graph}{The input graph. Edge directions are ignored in directed graphs.} +\item{graph}{The input graph. +Edge directions are ignored in directed graphs.} \item{...}{These dots are for future extensions and must be empty.} -\item{weights}{The weights of the edges. It must be a positive numeric vector, -\code{NULL} or \code{NA}. If it is \code{NULL} and the input graph has a -\sQuote{weight} edge attribute, then that attribute will be used. If -\code{NULL} and no such attribute is present, then the edges will have equal -weights. Set this to \code{NA} if the graph was a \sQuote{weight} edge -attribute, but you don't want to use it for community detection. A larger -edge weight means a stronger connection for this function.} - -\item{vertex}{This parameter can be used to calculate the community of a -given vertex without calculating all communities. Note that if this argument -is present then some other arguments are ignored.} - -\item{spins}{Integer constant, the number of spins to use. This is the upper -limit for the number of communities. It is not a problem to supply a -(reasonably) big number here, in which case some spin states will be -unpopulated.} - -\item{parupdate}{Logical, whether to update the spins of the -vertices in parallel (synchronously) or not. This argument is ignored if the -second form of the function is used (i.e. the \sQuote{\code{vertex}} argument -is present). It is also not implemented in the \dQuote{neg} implementation.} - -\item{start.temp}{Real constant, the start temperature. This argument is -ignored if the second form of the function is used (i.e. the -\sQuote{\code{vertex}} argument is present).} - -\item{stop.temp}{Real constant, the stop temperature. The simulation -terminates if the temperature lowers below this level. This argument is -ignored if the second form of the function is used (i.e. the -\sQuote{\code{vertex}} argument is present).} - -\item{cool.fact}{Cooling factor for the simulated annealing. This argument -is ignored if the second form of the function is used (i.e. the -\sQuote{\code{vertex}} argument is present).} - -\item{update.rule}{Character constant giving the \sQuote{null-model} of the -simulation. Possible values: \dQuote{simple} and \dQuote{config}. -\dQuote{simple} uses a random graph with the same number of edges as the -baseline probability and \dQuote{config} uses a random graph with the same -vertex degrees as the input graph.} - -\item{gamma}{Real constant, the gamma argument of the algorithm. This -specifies the balance between the importance of present and non-present -edges in a community. Roughly, a comunity is a set of vertices having many -edges inside the community and few edges outside the community. The default -1.0 value makes existing and non-existing links equally important. Smaller -values make the existing links, greater values the missing links more -important.} - -\item{implementation}{Character scalar. Currently igraph contains two -implementations for the Spin-glass community finding algorithm. The faster -original implementation is the default. The other implementation, that takes -into account negative weights, can be chosen by supplying \sQuote{neg} here.} - -\item{gamma.minus}{Real constant, the gamma.minus parameter of the -algorithm. This specifies the balance between the importance of present and -non-present negative weighted edges in a community. Smaller values of -gamma.minus, leads to communities with lesser negative intra-connectivity. -If this argument is set to zero, the algorithm reduces to a graph coloring -algorithm, using the number of spins as the number of colors. This argument -is ignored if the \sQuote{orig} implementation is chosen.} +\item{weights}{The weights of the edges. +It must be a positive numeric vector, \code{NULL} or \code{NA}. +If it is \code{NULL} and the input graph has a \sQuote{weight} edge attribute, then that attribute will be used. +If \code{NULL} and no such attribute is present, then the edges will have equal weights. +Set this to \code{NA} if the graph was a \sQuote{weight} edge attribute, but you don't want to use it for community detection. +A larger edge weight means a stronger connection for this function.} + +\item{vertex}{This parameter can be used to calculate the community of a given vertex without calculating all communities. +Note that if this argument is present then some other arguments are ignored.} + +\item{spins}{Integer constant, the number of spins to use. +This is the upper limit for the number of communities. +It is not a problem to supply a (reasonably) big number here, in which case some spin states will be unpopulated.} + +\item{parupdate}{Logical, whether to update the spins of the vertices in parallel (synchronously) or not. +This argument is ignored if the second form of the function is used (i.e. the \sQuote{\code{vertex}} argument is present). +It is also not implemented in the \dQuote{neg} implementation.} + +\item{start.temp}{Real constant, +the start temperature. +This argument is ignored if the second form of the function is used (i.e. the \sQuote{\code{vertex}} argument is present).} + +\item{stop.temp}{Real constant, the stop temperature. +The simulation terminates if the temperature lowers below this level. +This argument is ignored if the second form of the function is used (i.e. the \sQuote{\code{vertex}} argument is present).} + +\item{cool.fact}{Cooling factor for the simulated annealing. +This argument is ignored +if the second form of the function is used (i.e. the \sQuote{\code{vertex}} argument is present).} + +\item{update.rule}{Character constant giving the \sQuote{null-model} of the simulation. +Possible values: \dQuote{simple} and \dQuote{config}. +\dQuote{simple} uses a random graph with the same number of edges as the baseline probability and \dQuote{config} uses a random graph with the same vertex degrees as the input graph.} + +\item{gamma}{Real constant, the gamma argument of the algorithm. +This specifies the balance between the importance of present and non-present edges in a community. +Roughly, a comunity is a set of vertices having many edges inside the community and few edges outside the community. +The default 1.0 value makes existing and non-existing links equally important. +Smaller values make the existing links, greater values the missing links more important.} + +\item{implementation}{Character scalar. +Currently igraph contains two implementations for the Spin-glass community finding algorithm. +The faster original implementation is the default. +The other implementation, that takes into account negative weights, can be chosen by supplying \sQuote{neg} here.} + +\item{gamma.minus}{Real constant, the gamma.minus parameter of the algorithm. +This specifies the balance between the importance of present and non-present negative weighted edges in a community. +Smaller values of gamma.minus, leads to communities with lesser negative intra-connectivity. +If this argument is set to zero, the algorithm reduces to a graph coloring algorithm, +using the number of spins as the number of colors. +This argument is ignored if the \sQuote{orig} implementation is chosen.} } \value{ -If the \code{vertex} argument is not given, i.e. the first form is -used then a \code{\link[=cluster_spinglass]{cluster_spinglass()}} returns a -\code{\link[=communities]{communities()}} object. +If the \code{vertex} argument is not given, +i.e. the first form is used then a \code{\link[=cluster_spinglass]{cluster_spinglass()}} returns a \code{\link[=communities]{communities()}} object. -If the \code{vertex} argument is present, i.e. the second form is used then a -named list is returned with the following components: +If the \code{vertex} argument is present, i.e. the second form is used then a named list is returned with the following components: \describe{ \item{community}{ Numeric vector giving the IDs of the vertices in the same community as \code{vertex}. @@ -113,27 +102,23 @@ The number of edges between the community of \code{vertex} and the rest of the g } } \description{ -This function tries to find communities in graphs via a spin-glass model and -simulated annealing. +This function tries to find communities in graphs via a spin-glass model and simulated annealing. } \details{ -This function tries to find communities in a graph. A community is a set of -nodes with many edges inside the community and few edges between outside it -(i.e. between the community itself and the rest of the graph.) - -This idea is reversed for edges having a negative weight, i.e. few negative -edges inside a community and many negative edges between communities. Note -that only the \sQuote{neg} implementation supports negative edge weights. - -The \code{spinglass.cummunity} function can solve two problems related to -community detection. If the \code{vertex} argument is not given (or it is -\code{NULL}), then the regular community detection problem is solved -(approximately), i.e. partitioning the vertices into communities, by -optimizing the an energy function. - -If the \code{vertex} argument is given and it is not \code{NULL}, then it -must be a vertex ID, and the same energy function is used to find the -community of the the given vertex. See also the examples below. +This function tries to find communities in a graph. +A community is a set of nodes with many edges inside the community and few edges between outside it (i.e. between the community itself and the rest of the graph.) + +This idea is reversed for edges having a negative weight, +i.e. few negative edges inside a community and many negative edges between communities. +Note that only the \sQuote{neg} implementation supports negative edge weights. + +The \code{spinglass.cummunity} function can solve two problems related to community detection. +If the \code{vertex} argument is not given (or it is \code{NULL}), then the regular community detection problem is solved (approximately), +i.e. partitioning the vertices into communities, by optimizing the an energy function. + +If the \code{vertex} argument is given and it is not \code{NULL}, then it must be a vertex ID, +and the same energy function is used to find the community of the the given vertex. +See also the examples below. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/cluster_walktrap.Rd b/man/cluster_walktrap.Rd index c8aa1de35cb..08f39f7fb82 100644 --- a/man/cluster_walktrap.Rd +++ b/man/cluster_walktrap.Rd @@ -15,45 +15,38 @@ cluster_walktrap( ) } \arguments{ -\item{graph}{The input graph. Edge directions are ignored in directed -graphs.} +\item{graph}{The input graph. +Edge directions are ignored in directed graphs.} \item{...}{These dots are for future extensions and must be empty.} -\item{weights}{The weights of the edges. It must be a positive numeric vector, -\code{NULL} or \code{NA}. If it is \code{NULL} and the input graph has a -\sQuote{weight} edge attribute, then that attribute will be used. If -\code{NULL} and no such attribute is present, then the edges will have equal -weights. Set this to \code{NA} if the graph was a \sQuote{weight} edge -attribute, but you don't want to use it for community detection. Larger edge -weights increase the probability that an edge is selected by the random -walker. In other words, larger edge weights correspond to stronger connections.} +\item{weights}{The weights of the edges. +It must be a positive numeric vector, \code{NULL} or \code{NA}. +If it is \code{NULL} and the input graph has a \sQuote{weight} edge attribute, then that attribute will be used. +If \code{NULL} and no such attribute is present, then the edges will have equal weights. +Set this to \code{NA} if the graph was a \sQuote{weight} edge attribute, but you don't want to use it for community detection. +Larger edge weights increase the probability that an edge is selected by the random walker. +In other words, larger edge weights correspond to stronger connections.} \item{steps}{The length of the random walks to perform.} -\item{merges}{Logical, whether to include the merge matrix in the -result.} +\item{merges}{Logical, whether to include the merge matrix in the result.} -\item{modularity}{Logical, whether to include the vector of the -modularity scores in the result. If the \code{membership} argument is true, -then it will always be calculated.} +\item{modularity}{Logical, whether to include the vector of the modularity scores in the result. +If the \code{membership} argument is true, then it will always be calculated.} -\item{membership}{Logical, whether to calculate the membership vector -for the split corresponding to the highest modularity value.} +\item{membership}{Logical, whether to calculate the membership vector for the split corresponding to the highest modularity value.} } \value{ -\code{cluster_walktrap()} returns a \code{\link[=communities]{communities()}} -object, please see the \code{\link[=communities]{communities()}} manual page for details. +\code{cluster_walktrap()} returns a \code{\link[=communities]{communities()}} object, please see the \code{\link[=communities]{communities()}} manual page for details. } \description{ -This function tries to find densely connected subgraphs, also called -communities in a graph via random walks. The idea is that short random walks -tend to stay in the same community. +This function tries to find densely connected subgraphs, also called communities in a graph via random walks. +The idea is that short random walks tend to stay in the same community. } \details{ -This function is the implementation of the Walktrap community finding -algorithm, see Pascal Pons, Matthieu Latapy: Computing communities in large -networks using random walks, https://arxiv.org/abs/physics/0512106 +This function is the implementation of the Walktrap community finding algorithm, see Pascal Pons, Matthieu Latapy: +Computing communities in large networks using random walks, https://arxiv.org/abs/physics/0512106 } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} @@ -71,15 +64,10 @@ Pascal Pons, Matthieu Latapy: Computing communities in large networks using random walks, https://arxiv.org/abs/physics/0512106 } \seealso{ -See \code{\link[=communities]{communities()}} on getting the actual membership -vector, merge matrix, modularity score, etc. +See \code{\link[=communities]{communities()}} on getting the actual membership vector, merge matrix, modularity score, etc. -\code{\link[=modularity]{modularity()}} and \code{\link[=cluster_fast_greedy]{cluster_fast_greedy()}}, -\code{\link[=cluster_spinglass]{cluster_spinglass()}}, -\code{\link[=cluster_leading_eigen]{cluster_leading_eigen()}}, -\code{\link[=cluster_edge_betweenness]{cluster_edge_betweenness()}}, \code{\link[=cluster_louvain]{cluster_louvain()}}, -and \code{\link[=cluster_leiden]{cluster_leiden()}} for other community detection -methods. +\code{\link[=modularity]{modularity()}} and \code{\link[=cluster_fast_greedy]{cluster_fast_greedy()}}, \code{\link[=cluster_spinglass]{cluster_spinglass()}}, \code{\link[=cluster_leading_eigen]{cluster_leading_eigen()}}, \code{\link[=cluster_edge_betweenness]{cluster_edge_betweenness()}}, +\code{\link[=cluster_louvain]{cluster_louvain()}}, and \code{\link[=cluster_leiden]{cluster_leiden()}} for other community detection methods. Community detection: \code{\link[=as_membership]{as_membership()}}, diff --git a/man/clusters.Rd b/man/clusters.Rd index 554aa0f266a..ea63c6d3d4e 100644 --- a/man/clusters.Rd +++ b/man/clusters.Rd @@ -9,15 +9,15 @@ clusters(graph, mode = c("weak", "strong")) \arguments{ \item{graph}{The graph to analyze.} -\item{mode}{Character string, either \dQuote{weak} or \dQuote{strong}. For -directed graphs \dQuote{weak} implies weakly, \dQuote{strong} strongly -connected components to search. It is ignored for undirected graphs.} +\item{mode}{Character string, either \dQuote{weak} or \dQuote{strong}. +For directed graphs \dQuote{weak} implies weakly, +\dQuote{strong} strongly connected components to search. +It is ignored for undirected graphs.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{clusters()} was renamed to \code{\link[=components]{components()}} to create a more -consistent API. +\code{clusters()} was renamed to \code{\link[=components]{components()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_connected_components}{\code{connected_components()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/cocitation.Rd b/man/cocitation.Rd index e148aecbf82..07eb621dec7 100644 --- a/man/cocitation.Rd +++ b/man/cocitation.Rd @@ -12,31 +12,26 @@ bibcoupling(graph, v = NULL) \arguments{ \item{graph}{The graph object to analyze} -\item{v}{Vertex sequence or numeric vector, the vertex IDs for which the -cocitation or bibliographic coupling values we want to calculate. The -default \code{NULL} selects all vertices.} +\item{v}{Vertex sequence or numeric vector, +the vertex IDs for which the cocitation or bibliographic coupling values we want to calculate. +The default \code{NULL} selects all vertices.} } \value{ -A numeric matrix with \code{length(v)} lines and -\code{vcount(graph)} columns. Element \verb{(i,j)} contains the cocitation -or bibliographic coupling for vertices \code{v[i]} and \code{j}. +A numeric matrix with \code{length(v)} lines and \code{vcount(graph)} columns. +Element \verb{(i,j)} contains the cocitation or bibliographic coupling for vertices \code{v[i]} and \code{j}. } \description{ Two vertices are cocited if there is another vertex citing both of them. -\code{cocitation()} simply counts how many types two vertices are cocited. The -bibliographic coupling of two vertices is the number of other vertices they -both cite, \code{bibcoupling()} calculates this. +\code{cocitation()} simply counts how many types two vertices are cocited. +The bibliographic coupling of two vertices is the number of other vertices they both cite, \code{bibcoupling()} calculates this. } \details{ -\code{cocitation()} calculates the cocitation counts for the vertices in the -\code{v} argument and all vertices in the graph. +\code{cocitation()} calculates the cocitation counts for the vertices in the \code{v} argument and all vertices in the graph. -\code{bibcoupling()} calculates the bibliographic coupling for vertices in -\code{v} and all vertices in the graph. +\code{bibcoupling()} calculates the bibliographic coupling for vertices in \code{v} and all vertices in the graph. -Calculating the cocitation or bibliographic coupling for only one vertex -costs the same amount of computation as for all vertices. This might change -in the future. +Calculating the cocitation or bibliographic coupling for only one vertex costs the same amount of computation as for all vertices. +This might change in the future. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_cocitation}{\code{cocitation()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_bibcoupling}{\code{bibcoupling()}} diff --git a/man/code.length.Rd b/man/code.length.Rd index 940946cb5d6..da11bdf70c2 100644 --- a/man/code.length.Rd +++ b/man/code.length.Rd @@ -9,7 +9,6 @@ code.length(communities) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{code.length()} was renamed to \code{\link[=code_len]{code_len()}} to create a more -consistent API. +\code{code.length()} was renamed to \code{\link[=code_len]{code_len()}} to create a more consistent API. } \keyword{internal} diff --git a/man/cohesive.blocks.Rd b/man/cohesive.blocks.Rd index 2bda8400d28..a3337b8f586 100644 --- a/man/cohesive.blocks.Rd +++ b/man/cohesive.blocks.Rd @@ -7,23 +7,19 @@ cohesive.blocks(graph, labels = TRUE) } \arguments{ -\item{graph}{For \code{cohesive_blocks()} a graph object of class -\code{igraph}. It must be undirected and simple. (See -\code{\link[=is_simple]{is_simple()}}.) +\item{graph}{For \code{cohesive_blocks()} a graph object of class \code{igraph}. +It must be undirected and simple. +(See \code{\link[=is_simple]{is_simple()}}.) -For \code{graphs_from_cohesive_blocks()} and \code{export_pajek()} the same graph must be -supplied whose cohesive block structure is given in the \code{blocks()} -argument.} +For \code{graphs_from_cohesive_blocks()} and \code{export_pajek()} the same graph must be supplied whose cohesive block structure is given in the \code{blocks()} argument.} -\item{labels}{Logical, whether to add the vertex labels to the result -object. These labels can be then used when reporting and plotting the -cohesive blocks.} +\item{labels}{Logical, whether to add the vertex labels to the result object. +These labels can be then used when reporting and plotting the cohesive blocks.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{cohesive.blocks()} was renamed to \code{\link[=cohesive_blocks]{cohesive_blocks()}} to create a more -consistent API. +\code{cohesive.blocks()} was renamed to \code{\link[=cohesive_blocks]{cohesive_blocks()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Flows.html#igraph_cohesive_blocks}{\code{cohesive_blocks()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/cohesive_blocks.Rd b/man/cohesive_blocks.Rd index 80162d81f0b..2d84835ef4a 100644 --- a/man/cohesive_blocks.Rd +++ b/man/cohesive_blocks.Rd @@ -51,62 +51,53 @@ export_pajek(blocks, graph, file, ..., project.file = TRUE) max_cohesion(blocks) } \arguments{ -\item{graph}{For \code{cohesive_blocks()} a graph object of class -\code{igraph}. It must be undirected and simple. (See -\code{\link[=is_simple]{is_simple()}}.) +\item{graph}{For \code{cohesive_blocks()} a graph object of class \code{igraph}. +It must be undirected and simple. +(See \code{\link[=is_simple]{is_simple()}}.) -For \code{graphs_from_cohesive_blocks()} and \code{export_pajek()} the same graph must be -supplied whose cohesive block structure is given in the \code{blocks()} -argument.} +For \code{graphs_from_cohesive_blocks()} and \code{export_pajek()} the same graph must be supplied whose cohesive block structure is given in the \code{blocks()} argument.} -\item{\dots}{Additional arguments. \code{plot_hierarchy()} and \code{\link[=plot]{plot()}} pass -them to \code{plot.igraph()}. \code{\link[=print]{print()}} and \code{\link[=summary]{summary()}} ignore them. -\code{cohesive_blocks()} and \code{export_pajek()} do not accept extra arguments; -these dots must be empty for them.} +\item{\dots}{Additional arguments. +\code{plot_hierarchy()} and \code{\link[=plot]{plot()}} pass them to \code{plot.igraph()}. +\code{\link[=print]{print()}} and \code{\link[=summary]{summary()}} ignore them. +\code{cohesive_blocks()} and \code{export_pajek()} do not accept extra arguments; these dots must be empty for them.} -\item{labels}{Logical, whether to add the vertex labels to the result -object. These labels can be then used when reporting and plotting the -cohesive blocks.} +\item{labels}{Logical, whether to add the vertex labels to the result object. +These labels can be then used when reporting and plotting the cohesive blocks.} -\item{blocks, x, object}{A \code{cohesiveBlocks} object, created with the -\code{cohesive_blocks()} function.} +\item{blocks, x, object}{A \code{cohesiveBlocks} object, created with the \code{cohesive_blocks()} function.} -\item{y}{The graph whose cohesive blocks are supplied in the \code{x} -argument.} +\item{y}{The graph whose cohesive blocks are supplied in the \code{x} argument.} -\item{colbar}{Color bar for the vertex colors. Its length should be at least -\eqn{m+1}, where \eqn{m} is the maximum cohesion in the graph. -Alternatively, the vertex colors can also be directly specified via the -\code{col} argument.} +\item{colbar}{Color bar for the vertex colors. +Its length should be at least \eqn{m+1}, where \eqn{m} is the maximum cohesion in the graph. +Alternatively, the vertex colors can also be directly specified via the \code{col} argument.} -\item{col}{A vector of vertex colors, in any of the usual formats. (Symbolic -color names (e.g. \sQuote{red}, \sQuote{blue}, etc.) , RGB colors (e.g. -\sQuote{#FF9900FF}), integer numbers referring to the current palette. By -default the given \code{colbar} is used and vertices with the same maximal -cohesion will have the same color.} +\item{col}{A vector of vertex colors, in any of the usual formats. +(Symbolic color names (e.g. \sQuote{red}, \sQuote{blue}, etc.) , RGB colors (e.g. \sQuote{#FF9900FF}), +integer numbers referring to the current palette. +By default the given \code{colbar} is used and vertices with the same maximal cohesion will have the same color.} -\item{mark.groups}{A list of vertex sets to mark on the plot by circling -them. By default all cohesive blocks are marked, except the one -corresponding to the all vertices.} +\item{mark.groups}{A list of vertex sets to mark on the plot by circling them. +By default all cohesive blocks are marked, except the one corresponding to the all vertices.} -\item{layout}{The layout of a plot, it is simply passed on to -\code{plot.igraph()}, see the possible formats there. The default \code{NULL} uses -the Reingold-Tilford layout generator.} +\item{layout}{The layout of a plot, it is simply passed on to \code{plot.igraph()}, see the possible formats there. +The default \code{NULL} uses the Reingold-Tilford layout generator.} \item{file}{Defines the file (or connection) the Pajek file is written to. -If the \code{project.file} argument is \code{TRUE}, then it can be a -filename (with extension), a file object, or in general any king of -connection object. The file/connection will be opened if it wasn't already. +If the \code{project.file} argument is \code{TRUE}, then it can be a filename (with extension), a file object, +or in general any king of connection object. +The file/connection will be opened if it wasn't already. -If the \code{project.file} argument is \code{FALSE}, then several files are -created and \code{file} must be a character scalar containing the base name -of the files, without extension. (But it can contain the path to the files.) +If the \code{project.file} argument is \code{FALSE}, +then several files are created and \code{file} must be a character scalar containing the base name of the files, without extension. +(But it can contain the path to the files.) See also details below.} -\item{project.file}{Logical, whether to create a single Pajek project -file containing all the data, or to create separated files for each item. +\item{project.file}{Logical, whether to create a single Pajek project file containing all the data, +or to create separated files for each item. See details below.} } \value{ @@ -114,17 +105,14 @@ See details below.} \code{blocks()} returns a list of numeric vectors, containing vertex IDs. -\code{graphs_from_cohesive_blocks()} returns a list of igraph graphs, corresponding to the -cohesive blocks. +\code{graphs_from_cohesive_blocks()} returns a list of igraph graphs, corresponding to the cohesive blocks. \code{cohesion()} returns a numeric vector, the cohesion of each block. -\code{hierarchy()} returns an igraph graph, the representation of the cohesive -block hierarchy. +\code{hierarchy()} returns an igraph graph, the representation of the cohesive block hierarchy. -\code{parent()} returns a numeric vector giving the parent block of each -cohesive block, in the block hierarchy. The block at the root of the -hierarchy has no parent and \code{0} is returned for it. +\code{parent()} returns a numeric vector giving the parent block of each cohesive block, in the block hierarchy. +The block at the root of the hierarchy has no parent and \code{0} is returned for it. \code{plot_hierarchy()}, \code{\link[=plot]{plot()}} and \code{export_pajek()} return \code{NULL}, invisibly. @@ -132,8 +120,7 @@ invisibly. \code{max_cohesion()} returns a numeric vector with one entry for each vertex, giving the cohesion of its most cohesive block. -\code{\link[=print]{print()}} and \code{\link[=summary]{summary()}} return the \code{cohesiveBlocks} object -itself, invisibly. +\code{\link[=print]{print()}} and \code{\link[=summary]{summary()}} return the \code{cohesiveBlocks} object itself, invisibly. \code{length} returns a numeric scalar, the number of blocks. } @@ -141,88 +128,71 @@ itself, invisibly. Calculates cohesive blocks for objects of class \code{igraph}. } \details{ -Cohesive blocking is a method of determining hierarchical subsets of graph -vertices based on their structural cohesion (or vertex connectivity). For a -given graph \eqn{G}, a subset of its vertices \eqn{S\subset V(G)}{S} is said -to be maximally \eqn{k}-cohesive if there is no superset of \eqn{S} with -vertex connectivity greater than or equal to \eqn{k}. Cohesive blocking is a -process through which, given a \eqn{k}-cohesive set of vertices, maximally -\eqn{l}-cohesive subsets are recursively identified with \eqn{l>k}. Thus a -hierarchy of vertex subsets is found, with the entire graph \eqn{G} at its -root. - -The function \code{cohesive_blocks()} implements cohesive blocking. It -returns a \code{cohesiveBlocks} object. \code{cohesiveBlocks} should be -handled as an opaque class, i.e. its internal structure should not be -accessed directly, but through the functions listed here. - -The function \code{length} can be used on \code{cohesiveBlocks} objects and -it gives the number of blocks. - -The function \code{blocks()} returns the actual blocks stored in the -\code{cohesiveBlocks} object. They are returned in a list of numeric -vectors, each containing vertex IDs. - -The function \code{graphs_from_cohesive_blocks()} is similar, but returns the blocks as -(induced) subgraphs of the input graph. The various (graph, vertex and edge) -attributes are kept in the subgraph. - -The function \code{cohesion()} returns a numeric vector, the cohesion of the -different blocks. The order of the blocks is the same as for the -\code{blocks()} and \code{graphs_from_cohesive_blocks()} functions. - -The block hierarchy can be queried using the \code{hierarchy()} function. It -returns an igraph graph, its vertex IDs are ordered according the order of -the blocks in the \code{blocks()} and \code{graphs_from_cohesive_blocks()}, \code{cohesion()}, +Cohesive blocking is a method of determining hierarchical subsets of graph vertices based on their structural cohesion (or vertex connectivity). +For a given graph \eqn{G}, +a subset of its vertices \eqn{S\subset V(G)}{S} is said to be maximally \eqn{k}-cohesive +if there is no superset of \eqn{S} with vertex connectivity greater than or equal to \eqn{k}. +Cohesive blocking is a process through which, given a \eqn{k}-cohesive set of vertices, +maximally \eqn{l}-cohesive subsets are recursively identified with \eqn{l>k}. +Thus a hierarchy of vertex subsets is found, with the entire graph \eqn{G} at its root. + +The function \code{cohesive_blocks()} implements cohesive blocking. +It returns a \code{cohesiveBlocks} object. +\code{cohesiveBlocks} should be handled as an opaque class, i.e. its internal structure should not be accessed directly, +but through the functions listed here. + +The function \code{length} can be used on \code{cohesiveBlocks} objects and it gives the number of blocks. + +The function \code{blocks()} returns the actual blocks stored in the \code{cohesiveBlocks} object. +They are returned in a list of numeric vectors, each containing vertex IDs. + +The function \code{graphs_from_cohesive_blocks()} is similar, but returns the blocks as (induced) subgraphs of the input graph. +The various (graph, vertex and edge) attributes are kept in the subgraph. + +The function \code{cohesion()} returns a numeric vector, the cohesion of the different blocks. +The order of the blocks is the same as for the \code{blocks()} and \code{graphs_from_cohesive_blocks()} functions. + +The block hierarchy can be queried using the \code{hierarchy()} function. +It returns an igraph graph, +its vertex IDs are ordered according the order of the blocks in the \code{blocks()} and \code{graphs_from_cohesive_blocks()}, \code{cohesion()}, etc. functions. \code{parent()} gives the parent vertex of each block, in the block hierarchy, for the root vertex it gives 0. -\code{plot_hierarchy()} plots the hierarchy tree of the cohesive blocks on the -active graphics device, by calling \code{igraph.plot}. - -The \code{export_pajek()} function can be used to export the graph and its -cohesive blocks in Pajek format. It can either export a single Pajek project -file with all the information, or a set of files, depending on its -\code{project.file} argument. If \code{project.file} is \code{TRUE}, then -the following information is written to the file (or connection) given in -the \code{file} argument: (1) the input graph, together with its attributes, -see \code{\link[=write_graph]{write_graph()}} for details; (2) the hierarchy graph; and (3) -one binary partition for each cohesive block. If \code{project.file} is -\code{FALSE}, then the \code{file} argument must be a character scalar and -it is used as the base name for the generated files. If \code{file} is -\sQuote{basename}, then the following files are created: (1) -\sQuote{basename.net} for the original graph; (2) -\sQuote{basename_hierarchy.net} for the hierarchy graph; (3) -\sQuote{basename_block_x.net} for each cohesive block, where \sQuote{x} is -the number of the block, starting with one. - -\code{max_cohesion()} returns the maximal cohesion of each vertex, i.e. the -cohesion of the most cohesive block of the vertex. - -The generic function \code{\link[=summary]{summary()}} works on \code{cohesiveBlocks} objects -and it prints a one line summary to the terminal. - -The generic function \code{\link[=print]{print()}} is also defined on \code{cohesiveBlocks} -objects and it is invoked automatically if the name of the -\code{cohesiveBlocks} object is typed in. It produces an output like this: +\code{plot_hierarchy()} plots the hierarchy tree of the cohesive blocks on the active graphics device, by calling \code{igraph.plot}. + +The \code{export_pajek()} function can be used to export the graph and its cohesive blocks in Pajek format. +It can either export a single Pajek project file with all the information, or a set of files, depending on its \code{project.file} argument. +If \code{project.file} is \code{TRUE}, then the following information is written to the file (or connection) given in the \code{file} argument: +(1) the input graph, together with its attributes, see \code{\link[=write_graph]{write_graph()}} for details; (2) the hierarchy graph; +and (3) one binary partition for each cohesive block. +If \code{project.file} is \code{FALSE}, +then the \code{file} argument must be a character scalar and it is used as the base name for the generated files. +If \code{file} is \sQuote{basename}, then the following files are created: (1) \sQuote{basename.net} for the original graph; +(2) \sQuote{basename_hierarchy.net} for the hierarchy graph; (3) \sQuote{basename_block_x.net} for each cohesive block, +where \sQuote{x} is the number of the block, starting with one. + +\code{max_cohesion()} returns the maximal cohesion of each vertex, i.e. the cohesion of the most cohesive block of the vertex. + +The generic function \code{\link[=summary]{summary()}} works on \code{cohesiveBlocks} objects and it prints a one line summary to the terminal. + +The generic function \code{\link[=print]{print()}} is also defined on \code{cohesiveBlocks} objects and it is invoked automatically +if the name of the \code{cohesiveBlocks} object is typed in. +It produces an output like this: \preformatted{ Cohesive block structure: B-1 c 1, n 23 '- B-2 c 2, n 14 oooooooo.. .o......oo ooo '- B-4 c 5, n 7 ooooooo... .......... ... '- B-3 c 2, n 10 ......o.oo o.oooooo.. ... '- B-5 c 3, n 4 ......o.oo o......... ... } -The left part shows the block structure, in this case for five -blocks. The first block always corresponds to the whole graph, even if its -cohesion is zero. Then cohesion of the block and the number of vertices in -the block are shown. The last part is only printed if the display is wide -enough and shows the vertices in the blocks, ordered by vertex IDs. -\sQuote{o} means that the vertex is included, a dot means that it is not, -and the vertices are shown in groups of ten. - -The generic function \code{\link[=plot]{plot()}} plots the graph, showing one or more -cohesive blocks in it. +The left part shows the block structure, in this case for five blocks. +The first block always corresponds to the whole graph, even if its cohesion is zero. +Then cohesion of the block and the number of vertices in the block are shown. +The last part is only printed if the display is wide enough and shows the vertices in the blocks, ordered by vertex IDs. +\sQuote{o} means that the vertex is included, a dot means that it is not, and the vertices are shown in groups of ten. + +The generic function \code{\link[=plot]{plot()}} plots the graph, showing one or more cohesive blocks in it. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Flows.html#igraph_cohesive_blocks}{\code{cohesive_blocks()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Foreign.html#igraph_write_graph_edgelist}{\code{write_graph_edgelist()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Foreign.html#igraph_write_graph_pajek}{\code{write_graph_pajek()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Foreign.html#igraph_write_graph_graphml}{\code{write_graph_graphml()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Foreign.html#igraph_write_graph_gml}{\code{write_graph_gml()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Foreign.html#igraph_write_graph_dot}{\code{write_graph_dot()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Foreign.html#igraph_write_graph_leda}{\code{write_graph_leda()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_is_directed}{\code{is_directed()}} diff --git a/man/communities.Rd b/man/communities.Rd index c0696e218da..304decc02f2 100644 --- a/man/communities.Rd +++ b/man/communities.Rd @@ -59,57 +59,52 @@ show_trace(communities) communities(x) } \arguments{ -\item{communities, x, object}{A \code{communities} object, the result of an -igraph community detection function.} +\item{communities, x, object}{A \code{communities} object, the result of an igraph community detection function.} -\item{\dots}{Additional arguments. \code{plot.communities} passes these to -\code{\link[=plot.igraph]{plot.igraph()}}. The other functions silently ignore -them.} +\item{\dots}{Additional arguments. +\code{plot.communities} passes these to \code{\link[=plot.igraph]{plot.igraph()}}. +The other functions silently ignore them.} \item{graph}{An igraph graph object, corresponding to \code{communities}.} -\item{hang}{Numeric scalar indicating how the height of leaves should be -computed from the heights of their parents; see \code{\link[=plot.hclust]{plot.hclust()}}.} +\item{hang}{Numeric scalar indicating how the height of leaves should be computed from the heights of their parents; +see \code{\link[=plot.hclust]{plot.hclust()}}.} -\item{use.modularity}{Logical, whether to use the modularity values -to define the height of the branches.} +\item{use.modularity}{Logical, whether to use the modularity values to define the height of the branches.} -\item{no}{Integer scalar, the desired number of communities. If too low or -two high, then an error message is given. Exactly one of \code{no} and -\code{steps} must be supplied.} +\item{no}{Integer scalar, the desired number of communities. +If too low or two high, then an error message is given. +Exactly one of \code{no} and \code{steps} must be supplied.} -\item{steps}{The number of merge operations to perform to produce the -communities. Exactly one of \code{no} and \code{steps} must be supplied.} +\item{steps}{The number of merge operations to perform to produce the communities. +Exactly one of \code{no} and \code{steps} must be supplied.} -\item{y}{An igraph graph object, corresponding to the communities in -\code{x}.} +\item{y}{An igraph graph object, corresponding to the communities in \code{x}.} -\item{col}{A vector of colors, in any format that is accepted by the regular -R plotting methods. This vector gives the colors of the vertices explicitly.} +\item{col}{A vector of colors, in any format that is accepted by the regular R plotting methods. +This vector gives the colors of the vertices explicitly.} -\item{mark.groups}{A list of numeric vectors. The communities can be -highlighted using colored polygons. The groups for which the polygons are -drawn are given here. The default is to use the groups given by the -communities. Supply \code{NULL} here if you do not want to highlight any -groups.} +\item{mark.groups}{A list of numeric vectors. +The communities can be highlighted using colored polygons. +The groups for which the polygons are drawn are given here. +The default is to use the groups given by the communities. +Supply \code{NULL} here if you do not want to highlight any groups.} -\item{edge.color}{The colors of the edges. By default the edges within -communities are colored green and other edges are red.} +\item{edge.color}{The colors of the edges. +By default the edges within communities are colored green and other edges are red.} -\item{membership}{Numeric vector, one value for each vertex, the membership -vector of the community structure. Might also be \code{NULL} if the -community structure is given in another way, e.g. by a merge matrix.} +\item{membership}{Numeric vector, one value for each vertex, the membership vector of the community structure. +Might also be \code{NULL} if the community structure is given in another way, e.g. by a merge matrix.} -\item{algorithm}{Name of the algorithm that produced the community -structure (character scalar). Default: \code{NULL}, meaning an unknown algorithm.} +\item{algorithm}{Name of the algorithm that produced the community structure (character scalar). +Default: \code{NULL}, meaning an unknown algorithm.} -\item{merges}{Merge matrix of the hierarchical -community structure. See \code{merges()} below for more information on its -format. Default: \code{NULL}.} +\item{merges}{Merge matrix of the hierarchical community structure. +See \code{merges()} below for more information on its format. +Default: \code{NULL}.} -\item{modularity}{Numeric scalar or vector, the modularity value of the -community structure. It can also be \code{NULL}, if the modularity of the -(best) split is not available.} +\item{modularity}{Numeric scalar or vector, the modularity value of the community structure. +It can also be \code{NULL}, if the modularity of the (best) split is not available.} } \value{ \code{\link[=print]{print()}} returns the \code{communities} object itself, @@ -119,8 +114,7 @@ invisibly. \code{sizes()} returns a numeric vector. -\code{membership()} returns a numeric vector, one number for each vertex in -the graph that was the input of the community detection. +\code{membership()} returns a numeric vector, one number for each vertex in the graph that was the input of the community detection. \code{modularity()} returns a numeric scalar. @@ -132,110 +126,84 @@ the graph that was the input of the community detection. \code{merges()} returns a two-column numeric matrix. -\code{cut_at()} returns a numeric vector, the membership vector of the -vertices. +\code{cut_at()} returns a numeric vector, the membership vector of the vertices. \code{\link[=as.dendrogram]{as.dendrogram()}} returns a \link{dendrogram} object. \code{show_trace()} returns a character vector. -\code{code_len()} returns a numeric scalar for communities found with the -InfoMAP method and \code{NULL} for other methods. +\code{code_len()} returns a numeric scalar for communities found with the InfoMAP method and \code{NULL} for other methods. \code{\link[=plot]{plot()}} for \code{communities} objects returns \code{NULL}, invisibly. } \description{ -igraph community detection functions return their results as an object from -the \code{communities} class. This manual page describes the operations of -this class. +igraph community detection functions return their results as an object from the \code{communities} class. +This manual page describes the operations of this class. } \details{ -Community structure detection algorithms try to find dense subgraphs in -directed or undirected graphs, by optimizing some criteria, and usually -using heuristics. - -igraph implements a number of community detection methods (see them below), -all of which return an object of the class \code{communities}. Because the -community structure detection algorithms are different, \code{communities} -objects do not always have the same structure. Nevertheless, they have some -common operations, these are documented here. - -The \code{\link[=print]{print()}} generic function is defined for \code{communities}, it -prints a short summary. - -The \code{length} generic function call be called on \code{communities} and -returns the number of communities. - -The \code{sizes()} function returns the community sizes, in the order of their -IDs. - -\code{membership()} gives the division of the vertices, into communities. It -returns a numeric vector, one value for each vertex, the ID of its -community. Community IDs start from one. Note that some algorithms calculate -the complete (or incomplete) hierarchical structure of the communities, and -not just a single partitioning. For these algorithms typically the -membership for the highest modularity value is returned, but see also the -manual pages of the individual algorithms. - -\code{communities()} is also the name of a function, that returns a list of -communities, each identified by their vertices. The vertices will have -symbolic names if the \code{add.vertex.names} igraph option is set, and the -graph itself was named. Otherwise numeric vertex IDs are used. - -\code{modularity()} gives the modularity score of the partitioning. (See -\code{\link[=modularity.igraph]{modularity.igraph()}} for details. For algorithms that do not -result a single partitioning, the highest modularity value is returned. - -\code{algorithm()} gives the name of the algorithm that was used to calculate -the community structure. - -\code{crossing()} returns a logical vector, with one value for each edge, -ordered according to the edge IDs. The value is \code{TRUE} iff the edge -connects two different communities, according to the (best) membership -vector, as returned by \code{membership()}. - -\code{is_hierarchical()} checks whether a hierarchical algorithm was used to -find the community structure. Some functions only make sense for -hierarchical methods (e.g. \code{merges()}, \code{cut_at()} and -\code{\link[=as.dendrogram]{as.dendrogram()}}). - -\code{merges()} returns the merge matrix for hierarchical methods. An error -message is given, if a non-hierarchical method was used to find the -community structure. You can check this by calling \code{is_hierarchical()} on -the \code{communities} object. - -\code{cut_at()} cuts the merge tree of a hierarchical community finding method, -at the desired place and returns a membership vector. The desired place can -be expressed as the desired number of communities or as the number of merge -steps to make. The function gives an error message, if called with a -non-hierarchical method. - -\code{\link[=as.dendrogram]{as.dendrogram()}} converts a hierarchical community structure to a -\code{dendrogram} object. It only works for hierarchical methods, and gives -an error message to others. See \code{\link[stats:dendrogram]{stats::dendrogram()}} for details. - -\code{\link[stats:as.hclust]{stats::as.hclust()}} is similar to \code{\link[=as.dendrogram]{as.dendrogram()}}, but converts a -hierarchical community structure to a \code{hclust} object. - -\code{\link[ape:as.phylo]{ape::as.phylo()}} converts a hierarchical community structure to a \code{phylo} -object, you will need the \code{ape} package for this. - -\code{show_trace()} works (currently) only for communities found by the leading -eigenvector method (\code{\link[=cluster_leading_eigen]{cluster_leading_eigen()}}), and -returns a character vector that gives the steps performed by the algorithm -while finding the communities. - -\code{code_len()} is defined for the InfoMAP method -(\code{\link[=cluster_infomap]{cluster_infomap()}} and returns the code length of the -partition. - -It is possibly to call the \code{\link[=plot]{plot()}} function on \code{communities} -objects. This will plot the graph (and uses \code{\link[=plot.igraph]{plot.igraph()}} -internally), with the communities shown. By default it colores the vertices -according to their communities, and also marks the vertex groups -corresponding to the communities. It passes additional arguments to -\code{\link[=plot.igraph]{plot.igraph()}}, please see that and also -\link{igraph.plotting} on how to change the plot. +Community structure detection algorithms try to find dense subgraphs in directed or undirected graphs, by optimizing some criteria, +and usually using heuristics. + +igraph implements a number of community detection methods (see them below), all of which return an object of the class \code{communities}. +Because the community structure detection algorithms are different, \code{communities} objects do not always have the same structure. +Nevertheless, they have some common operations, these are documented here. + +The \code{\link[=print]{print()}} generic function is defined for \code{communities}, it prints a short summary. + +The \code{length} generic function call be called on \code{communities} and returns the number of communities. + +The \code{sizes()} function returns the community sizes, in the order of their IDs. + +\code{membership()} gives the division of the vertices, into communities. +It returns a numeric vector, one value for each vertex, the ID of its community. +Community IDs start from one. +Note that some algorithms calculate the complete (or incomplete) hierarchical structure of the communities, +and not just a single partitioning. +For these algorithms typically the membership for the highest modularity value is returned, +but see also the manual pages of the individual algorithms. + +\code{communities()} is also the name of a function, that returns a list of communities, each identified by their vertices. +The vertices will have symbolic names if the \code{add.vertex.names} igraph option is set, and the graph itself was named. +Otherwise numeric vertex IDs are used. + +\code{modularity()} gives the modularity score of the partitioning. +(See \code{\link[=modularity.igraph]{modularity.igraph()}} for details. +For algorithms that do not result a single partitioning, the highest modularity value is returned. + +\code{algorithm()} gives the name of the algorithm that was used to calculate the community structure. + +\code{crossing()} returns a logical vector, with one value for each edge, ordered according to the edge IDs. +The value is \code{TRUE} iff the edge connects two different communities, according to the (best) membership vector, +as returned by \code{membership()}. + +\code{is_hierarchical()} checks whether a hierarchical algorithm was used to find the community structure. +Some functions only make sense for hierarchical methods (e.g. \code{merges()}, \code{cut_at()} and \code{\link[=as.dendrogram]{as.dendrogram()}}). + +\code{merges()} returns the merge matrix for hierarchical methods. +An error message is given, if a non-hierarchical method was used to find the community structure. +You can check this by calling \code{is_hierarchical()} on the \code{communities} object. + +\code{cut_at()} cuts the merge tree of a hierarchical community finding method, at the desired place and returns a membership vector. +The desired place can be expressed as the desired number of communities or as the number of merge steps to make. +The function gives an error message, if called with a non-hierarchical method. + +\code{\link[=as.dendrogram]{as.dendrogram()}} converts a hierarchical community structure to a \code{dendrogram} object. +It only works for hierarchical methods, and gives an error message to others. +See \code{\link[stats:dendrogram]{stats::dendrogram()}} for details. + +\code{\link[stats:as.hclust]{stats::as.hclust()}} is similar to \code{\link[=as.dendrogram]{as.dendrogram()}}, but converts a hierarchical community structure to a \code{hclust} object. + +\code{\link[ape:as.phylo]{ape::as.phylo()}} converts a hierarchical community structure to a \code{phylo} object, you will need the \code{ape} package for this. + +\code{show_trace()} works (currently) only for communities found by the leading eigenvector method (\code{\link[=cluster_leading_eigen]{cluster_leading_eigen()}}), +and returns a character vector that gives the steps performed by the algorithm while finding the communities. + +\code{code_len()} is defined for the InfoMAP method (\code{\link[=cluster_infomap]{cluster_infomap()}} and returns the code length of the partition. + +It is possibly to call the \code{\link[=plot]{plot()}} function on \code{communities} objects. +This will plot the graph (and uses \code{\link[=plot.igraph]{plot.igraph()}} internally), with the communities shown. +By default it colores the vertices according to their communities, and also marks the vertex groups corresponding to the communities. +It passes additional arguments to \code{\link[=plot.igraph]{plot.igraph()}}, please see that and also \link{igraph.plotting} on how to change the plot. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_edgelist}{\code{get_edgelist()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Community.html#igraph_le_community_to_membership}{\code{le_community_to_membership()}} @@ -251,11 +219,9 @@ plot(wc, karate) } \seealso{ -See \code{\link[=plot_dendrogram]{plot_dendrogram()}} for plotting community structure -dendrograms. +See \code{\link[=plot_dendrogram]{plot_dendrogram()}} for plotting community structure dendrograms. -See \code{\link[=compare]{compare()}} for comparing two community structures -on the same graph. +See \code{\link[=compare]{compare()}} for comparing two community structures on the same graph. Community detection: \code{\link[=as_membership]{as_membership()}}, diff --git a/man/compare.Rd b/man/compare.Rd index d331fc49d72..e3489205538 100644 --- a/man/compare.Rd +++ b/man/compare.Rd @@ -13,22 +13,18 @@ compare( ) } \arguments{ -\item{comm1}{A \code{\link[=communities]{communities()}} object containing a community -structure; or a numeric vector, the membership vector of the first community -structure. The membership vector should contain the community ID of each -vertex, the numbering of the communities starts with one.} +\item{comm1}{A \code{\link[=communities]{communities()}} object containing a community structure; or a numeric vector, +the membership vector of the first community structure. +The membership vector should contain the community ID of each vertex, the numbering of the communities starts with one.} -\item{comm2}{A \code{\link[=communities]{communities()}} object containing a community -structure; or a numeric vector, the membership vector of the second -community structure, in the same format as for the previous argument.} +\item{comm2}{A \code{\link[=communities]{communities()}} object containing a community structure; or a numeric vector, +the membership vector of the second community structure, in the same format as for the previous argument.} -\item{method}{Character scalar, the comparison method to use. Possible -values: \sQuote{vi} is the variation of information (VI) metric of Meila -(2003), \sQuote{nmi} is the normalized mutual information measure proposed -by Danon et al. (2005), \sQuote{split.join} is the split-join distance of -can Dongen (2000), \sQuote{rand} is the Rand index of Rand (1971), -\sQuote{adjusted.rand} is the adjusted Rand index by Hubert and Arabie -(1985).} +\item{method}{Character scalar, the comparison method to use. +Possible values: \sQuote{vi} is the variation of information (VI) metric of Meila (2003), +\sQuote{nmi} is the normalized mutual information measure proposed by Danon et al. (2005), +\sQuote{split.join} is the split-join distance of can Dongen (2000), \sQuote{rand} is the Rand index of Rand (1971), +\sQuote{adjusted.rand} is the adjusted Rand index by Hubert and Arabie (1985).} } \value{ A real number. diff --git a/man/complementer.Rd b/man/complementer.Rd index 5e38be4b36a..266d34aa9f8 100644 --- a/man/complementer.Rd +++ b/man/complementer.Rd @@ -17,16 +17,13 @@ complementer(graph, ..., loops = FALSE) A new graph object. } \description{ -A complementer graph contains all edges that were not present in the input -graph. +A complementer graph contains all edges that were not present in the input graph. } \details{ -\code{complementer()} creates the complementer of a graph. Only edges -which are \emph{not} present in the original graph will be included in the -new graph. +\code{complementer()} creates the complementer of a graph. +Only edges which are \emph{not} present in the original graph will be included in the new graph. -\code{complementer()} keeps graph and vertex attriubutes, edge -attributes are lost. +\code{complementer()} keeps graph and vertex attriubutes, edge attributes are lost. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Operators.html#igraph_complementer}{\code{complementer()}} diff --git a/man/component_wise.Rd b/man/component_wise.Rd index 050e6882e4d..71428f9d47d 100644 --- a/man/component_wise.Rd +++ b/man/component_wise.Rd @@ -7,13 +7,10 @@ component_wise(merge_method = "dla") } \arguments{ -\item{merge_method}{Merging algorithm, the \code{method} -argument of \code{\link[=merge_coords]{merge_coords()}}.} +\item{merge_method}{Merging algorithm, the \code{method} argument of \code{\link[=merge_coords]{merge_coords()}}.} } \description{ -This is a layout modifier function, and it can be used -to calculate the layout separately for each component -of the graph. +This is a layout modifier function, and it can be used to calculate the layout separately for each component of the graph. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_decompose}{\code{decompose()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/components.Rd b/man/components.Rd index 7e90fda56ba..0f7c89e2130 100644 --- a/man/components.Rd +++ b/man/components.Rd @@ -21,19 +21,18 @@ count_components(graph, ..., mode = c("weak", "strong")) \arguments{ \item{graph}{The graph to analyze.} -\item{cumulative}{Logical, if TRUE the cumulative distirubution (relative -frequency) is calculated.} +\item{cumulative}{Logical, if TRUE the cumulative distirubution (relative frequency) is calculated.} -\item{mul.size}{Logical. If TRUE the relative frequencies will be multiplied -by the cluster sizes.} +\item{mul.size}{Logical. +If TRUE the relative frequencies will be multiplied by the cluster sizes.} \item{\dots}{For \code{component_distribution()}, forwarded to \code{components()}. -For \code{components()}, \code{is_connected()}, \code{count_components()} and -\code{largest_component()}, these dots must be empty.} +For \code{components()}, \code{is_connected()}, \code{count_components()} and \code{largest_component()}, these dots must be empty.} -\item{mode}{Character string, either \dQuote{weak} or \dQuote{strong}. For -directed graphs \dQuote{weak} implies weakly, \dQuote{strong} strongly -connected components to search. It is ignored for undirected graphs.} +\item{mode}{Character string, either \dQuote{weak} or \dQuote{strong}. +For directed graphs \dQuote{weak} implies weakly, +\dQuote{strong} strongly connected components to search. +It is ignored for undirected graphs.} } \value{ For \code{is_connected()} a Logical. @@ -53,10 +52,10 @@ numeric constant, the number of clusters. For \code{count_components()} an integer constant is returned. -For \code{component_distribution()} a numeric vector with the relative -frequencies. The length of the vector is the size of the largest component -plus one. Note that (for currently unknown reasons) the first element of the -vector is the number of clusters of size zero, so this is always zero. +For \code{component_distribution()} a numeric vector with the relative frequencies. +The length of the vector is the size of the largest component plus one. +Note that (for currently unknown reasons) the first element of the vector is the number of clusters of size zero, +so this is always zero. For \code{largest_component()} the largest connected component of the graph. } @@ -64,26 +63,22 @@ For \code{largest_component()} the largest connected component of the graph. Calculate the maximal (weakly or strongly) connected components of a graph } \details{ -\code{is_connected()} decides whether the graph is weakly or strongly -connected. The null graph is considered disconnected. +\code{is_connected()} decides whether the graph is weakly or strongly connected. +The null graph is considered disconnected. -\code{components()} finds the maximal (weakly or strongly) connected components -of a graph. +\code{components()} finds the maximal (weakly or strongly) connected components of a graph. -\code{count_components()} does almost the same as \code{components()} but returns only -the number of clusters found instead of returning the actual clusters. +\code{count_components()} does almost the same as \code{components()} but returns only the number of clusters found instead of returning the actual clusters. -\code{component_distribution()} creates a histogram for the maximal connected -component sizes. +\code{component_distribution()} creates a histogram for the maximal connected component sizes. -\code{largest_component()} returns the largest connected component of a graph. For -directed graphs, optionally the largest weakly or strongly connected component. -In case of a tie, the first component by vertex ID order is returned. Vertex -IDs from the original graph are not retained in the returned graph. +\code{largest_component()} returns the largest connected component of a graph. +For directed graphs, optionally the largest weakly or strongly connected component. +In case of a tie, the first component by vertex ID order is returned. +Vertex IDs from the original graph are not retained in the returned graph. The weakly connected components are found by a simple breadth-first search. -The strongly connected components are implemented by two consecutive -depth-first searches. +The strongly connected components are implemented by two consecutive depth-first searches. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_connected_components}{\code{connected_components()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Operators.html#igraph_induced_subgraph}{\code{induced_subgraph()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_connected}{\code{is_connected()}} diff --git a/man/compose.Rd b/man/compose.Rd index ff5e5adcf7b..16f9e967bef 100644 --- a/man/compose.Rd +++ b/man/compose.Rd @@ -22,18 +22,15 @@ compose( \item{...}{These dots are for future extensions and must be empty.} -\item{byname}{A Logical, or the character scalar \code{auto}. Whether -to perform the operation based on symbolic vertex names. If it is -\code{auto}, that means \code{TRUE} if both graphs are named and -\code{FALSE} otherwise. A warning is generated if \code{auto} and one graph, -but not both graphs are named.} +\item{byname}{A Logical, or the character scalar \code{auto}. +Whether to perform the operation based on symbolic vertex names. +If it is \code{auto}, that means \code{TRUE} if both graphs are named and \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 -\code{\link[=igraph_options]{igraph_options()}}). See \link{igraph-attribute-combination} for the available -combiners.} +\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 \code{\link[=igraph_options]{igraph_options()}}). +See \link{igraph-attribute-combination} for the available combiners.} } \value{ A new graph object. @@ -42,43 +39,38 @@ A new graph object. Relational composition of two graph. } \details{ -\code{compose()} creates the relational composition of two graphs. The -new graph will contain an (a,b) edge only if there is a vertex c, such that -edge (a,c) is included in the first graph and (c,b) is included in the -second graph. The corresponding operator is \verb{\%c\%}. +\code{compose()} creates the relational composition of two graphs. +The new graph will contain an (a,b) edge only if there is a vertex c, +such that edge (a,c) is included in the first graph and (c,b) is included in the second graph. +The corresponding operator is \verb{\%c\%}. -The function gives an error if one of the input graphs is directed and the -other is undirected. +The function gives an error if one of the input graphs is directed and the other is undirected. -If the \code{byname} argument is \code{TRUE} (or \code{auto} and the graphs -are all named), then the operation is performed based on symbolic vertex -names. Otherwise numeric vertex IDs are used. +If the \code{byname} argument is \code{TRUE} (or \code{auto} and the graphs are all named), +then the operation is performed based on symbolic vertex 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 -instead; see \link{igraph-attribute-combination} for the available combiners. +\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 instead; +see \link{igraph-attribute-combination} for the available combiners. -The \code{name} vertex attribute is treated specially if the operation is -performed based on symbolic vertex names. In this case \code{name} must be -present in both graphs, and it is not renamed in the result graph. +The \code{name} vertex attribute is treated specially if the operation is performed based on symbolic vertex names. +In this case \code{name} must be present in both graphs, and it is not renamed in the result graph. -Note that an edge in the result graph corresponds to two edges in the input, -one in the first graph, one in the second. This mapping is not injective and -several edges in the result might correspond to the same edge in the first -(and/or the second) graph. The edge attributes in the result graph are -updated accordingly. +Note that an edge in the result graph corresponds to two edges in the input, one in the first graph, one in the second. +This mapping is not injective and several edges in the result might correspond to the same edge in the first (and/or the second) graph. +The edge attributes in the result graph are updated accordingly. -Also note that the function may generate multigraphs, if there are more than -one way to find edges (a,b) in g1 and (b,c) in g2 for an edge (a,c) in the -result. See \code{\link[=simplify]{simplify()}} if you want to get rid of the multiple -edges. +Also note that the function may generate multigraphs, +if there are more than one way to find edges (a,b) in g1 and (b,c) in g2 for an edge (a,c) in the result. +See \code{\link[=simplify]{simplify()}} if you want to get rid of the multiple edges. -The function may create loop edges, if edges (a,b) and (b,a) are present in -g1 and g2, respectively, then (a,a) is included in the result. See -\code{\link[=simplify]{simplify()}} if you want to get rid of the self-loops. +The function may create loop edges, if edges (a,b) and (b,a) are present in g1 and g2, respectively, +then (a,a) is included in the result. +See \code{\link[=simplify]{simplify()}} if you want to get rid of the self-loops. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Isomorphism.html#igraph_permute_vertices}{\code{permute_vertices()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/connect.neighborhood.Rd b/man/connect.neighborhood.Rd index bb5a6af8fe5..86397bbc1fd 100644 --- a/man/connect.neighborhood.Rd +++ b/man/connect.neighborhood.Rd @@ -9,22 +9,20 @@ connect.neighborhood(graph, order, mode = c("all", "out", "in", "total")) \arguments{ \item{graph}{The input graph.} -\item{order}{Integer giving the order of the neighborhood. Negative values -indicate an infinite order.} +\item{order}{Integer giving the order of the neighborhood. +Negative values indicate an infinite order.} -\item{mode}{Character constant, it specifies how to use the direction of -the edges if a directed graph is analyzed. For \sQuote{out} only the -outgoing edges are followed, so all vertices reachable from the source -vertex in at most \code{order} steps are counted. For \sQuote{"in"} all -vertices from which the source vertex is reachable in at most \code{order} -steps are counted. \sQuote{"all"} ignores the direction of the edges. This -argument is ignored for undirected graphs.} +\item{mode}{Character constant, it specifies how to use the direction of the edges if a directed graph is analyzed. +For \sQuote{out} only the outgoing edges are followed, +so all vertices reachable from the source vertex in at most \code{order} steps are counted. +For \sQuote{"in"} all vertices from which the source vertex is reachable in at most \code{order} steps are counted. +\sQuote{"all"} ignores the direction of the edges. +This argument is ignored for undirected graphs.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{connect.neighborhood()} was renamed to \code{\link[=connect]{connect()}} to create a more -consistent API. +\code{connect.neighborhood()} was renamed to \code{\link[=connect]{connect()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Operators.html#igraph_connect_neighborhood}{\code{connect_neighborhood()}} diff --git a/man/consensus_tree.Rd b/man/consensus_tree.Rd index c9a69527bc4..f9abb94cb68 100644 --- a/man/consensus_tree.Rd +++ b/man/consensus_tree.Rd @@ -9,24 +9,19 @@ consensus_tree(graph, hrg = NULL, ..., start = FALSE, num.samples = 10000) \arguments{ \item{graph}{The graph the models were fitted to.} -\item{hrg}{A hierarchical random graph model, in the form of an -\code{igraphHRG} object. \code{consensus_tree()} allows this to be -\code{NULL} as well, then a HRG is fitted to the graph first, from a -random starting point.} +\item{hrg}{A hierarchical random graph model, in the form of an \code{igraphHRG} object. +\code{consensus_tree()} allows this to be \code{NULL} as well, then a HRG is fitted to the graph first, from a random starting point.} \item{...}{These dots are for future extensions and must be empty.} -\item{start}{Logical, whether to start the fitting/sampling from the -supplied \code{igraphHRG} object, or from a random starting point.} +\item{start}{Logical, whether to start the fitting/sampling from the supplied \code{igraphHRG} object, or from a random starting point.} -\item{num.samples}{Number of samples to use for consensus generation or -missing edge prediction.} +\item{num.samples}{Number of samples to use for consensus generation or missing edge prediction.} } \value{ -\code{consensus_tree()} returns a list of two objects. The first -is an \code{igraphHRGConsensus} object, the second is an -\code{igraphHRG} object. The \code{igraphHRGConsensus} object has the -following members: +\code{consensus_tree()} returns a list of two objects. +The first is an \code{igraphHRGConsensus} object, the second is an \code{igraphHRG} object. +The \code{igraphHRGConsensus} object has the following members: \describe{ \item{parents}{ For each vertex, the ID of its parent vertex is stored, @@ -42,11 +37,9 @@ The order is the same as in the \code{parents} vector. } } \description{ -\code{consensus_tree()} creates a consensus tree from several fitted -hierarchical random graph models, using phylogeny methods. If the \code{hrg()} -argument is given and \code{start} is set to \code{TRUE}, then it starts -sampling from the given HRG. Otherwise it optimizes the HRG log-likelihood -first, and then samples starting from the optimum. +\code{consensus_tree()} creates a consensus tree from several fitted hierarchical random graph models, using phylogeny methods. +If the \code{hrg()} argument is given and \code{start} is set to \code{TRUE}, then it starts sampling from the given HRG. +Otherwise it optimizes the HRG log-likelihood first, and then samples starting from the optimum. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-HRG.html#igraph_hrg_consensus}{\code{hrg_consensus()}} diff --git a/man/console.Rd b/man/console.Rd index d2280ed140e..88d20e8b4f6 100644 --- a/man/console.Rd +++ b/man/console.Rd @@ -10,17 +10,14 @@ console() \code{NULL}, invisibly. } \description{ -The igraph console is a GUI window that shows what the currently running -igraph function is doing. +The igraph console is a GUI window that shows what the currently running igraph function is doing. } \details{ The console can be started by calling the \code{console()} function. Then it stays open, until the user closes it. -Another way to start it to set the \code{verbose} igraph option to -\dQuote{tkconsole} via \code{igraph_options()}. Then the console (re)opens -each time an igraph function supporting it starts; to close it, set the -\code{verbose} option to another value. +Another way to start it to set the \code{verbose} igraph option to \dQuote{tkconsole} via \code{igraph_options()}. +Then the console (re)opens each time an igraph function supporting it starts; to close it, set the \code{verbose} option to another value. The console is written in Tcl/Tk and required the \code{tcltk} package. } diff --git a/man/constraint.Rd b/man/constraint.Rd index 3dd16200b38..fa170af55ee 100644 --- a/man/constraint.Rd +++ b/man/constraint.Rd @@ -14,34 +14,31 @@ The default \code{NULL} selects all vertices.} \item{...}{These dots are for future extensions and must be empty.} -\item{weights}{The weights of the edges. If this is \code{NULL} and there is -a \code{weight} edge attribute this is used. If there is no such edge -attribute all edges will have the same weight.} +\item{weights}{The weights of the edges. +If this is \code{NULL} and there is a \code{weight} edge attribute this is used. +If there is no such edge attribute all edges will have the same weight.} } \value{ A numeric vector of constraint scores } \description{ -Given a graph, \code{constraint()} calculates Burt's constraint for each -vertex. +Given a graph, \code{constraint()} calculates Burt's constraint for each vertex. } \details{ -Burt's constraint is higher if ego has less, or mutually -stronger related (i.e. more redundant) contacts. Burt's measure of -constraint, \eqn{C_i}{C[i]}, of vertex \eqn{i}'s ego network -\eqn{V_i}{V[i]}, is defined for directed and valued graphs, +Burt's constraint is higher if ego has less, or mutually stronger related (i.e. more redundant) contacts. +Burt's measure of constraint, \eqn{C_i}{C[i]}, of vertex \eqn{i}'s ego network \eqn{V_i}{V[i]}, +is defined for directed and valued graphs, \deqn{C_i=\sum_{j \in V_i \setminus \{i\}} (p_{ij}+\sum_{q \in V_i \setminus \{i,j\}} p_{iq} p_{qj})^2}{ C[i] = sum( [sum( p[i,j] + p[i,q] p[q,j], q in V[i], q != i,j )]^2, j in V[i], j != i). } -for a graph of order (i.e. number of vertices) \eqn{N}, where -proportional tie strengths are defined as +for a graph of order (i.e. number of vertices) \eqn{N}, where proportional tie strengths are defined as \deqn{p_{ij} = \frac{a_{ij}+a_{ji}}{\sum_{k \in V_i \setminus \{i\}}(a_{ik}+a_{ki})},}{ p[i,j]=(a[i,j]+a[j,i]) / sum(a[i,k]+a[k,i], k in V[i], k != i), } -\eqn{a_{ij}}{a[i,j]} are elements of \eqn{A} and the latter being the -graph adjacency matrix. For isolated vertices, constraint is undefined. +\eqn{a_{ij}}{a[i,j]} are elements of \eqn{A} and the latter being the graph adjacency matrix. +For isolated vertices, constraint is undefined. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_constraint}{\code{constraint()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/constructor_spec.Rd b/man/constructor_spec.Rd index 90efd2c4b27..4e00ecf9d16 100644 --- a/man/constructor_spec.Rd +++ b/man/constructor_spec.Rd @@ -26,20 +26,16 @@ deterministic; if \code{TRUE}, wraps \code{\link[=realize_degseq]{realize_degseq An object of class \code{igraph_constructor_spec}. } \description{ -Each of these functions builds a lazy constructor specification for the -given graph constructor, to be used with \code{\link[=graph_]{graph_()}}, \code{\link[=make_]{make_()}} or -\code{\link[=sample_]{sample_()}}. The specification is only evaluated when the graph is actually -constructed, so it can be combined with constructor modifiers such as -\code{\link[=with_vertex_]{with_vertex_()}} or \code{\link[=with_edge_]{with_edge_()}}. - -\code{from_data_frame()}, \code{from_edgelist()}, \code{tree()} and \code{degseq()} wrap -\code{\link[=graph_from_data_frame]{graph_from_data_frame()}}, \code{\link[=graph_from_edgelist]{graph_from_edgelist()}}, \code{\link[=make_tree]{make_tree()}} (or -\code{\link[=sample_tree]{sample_tree()}}) and \code{\link[=sample_degseq]{sample_degseq()}} (or \code{\link[=realize_degseq]{realize_degseq()}}), -respectively. - -The other constructors have specification functions as well; they are -documented together with the constructor they wrap, e.g. \code{ring()} on the -\code{\link[=make_ring]{make_ring()}} page. +Each of these functions builds a lazy constructor specification for the given graph constructor, to be used with \code{\link[=graph_]{graph_()}}, +\code{\link[=make_]{make_()}} or \code{\link[=sample_]{sample_()}}. +The specification is only evaluated when the graph is actually constructed, +so it can be combined with constructor modifiers such as \code{\link[=with_vertex_]{with_vertex_()}} or \code{\link[=with_edge_]{with_edge_()}}. + +\code{from_data_frame()}, \code{from_edgelist()}, \code{tree()} and \code{degseq()} wrap \code{\link[=graph_from_data_frame]{graph_from_data_frame()}}, \code{\link[=graph_from_edgelist]{graph_from_edgelist()}}, +\code{\link[=make_tree]{make_tree()}} (or \code{\link[=sample_tree]{sample_tree()}}) and \code{\link[=sample_degseq]{sample_degseq()}} (or \code{\link[=realize_degseq]{realize_degseq()}}), respectively. + +The other constructors have specification functions as well; they are documented together with the constructor they wrap, +e.g. \code{ring()} on the \code{\link[=make_ring]{make_ring()}} page. } \examples{ # Pass a constructor specification to graph_(), make_() or sample_() @@ -52,8 +48,7 @@ make_(tree(7)) make_(tree(7), with_vertex_(color = "red")) } \seealso{ -\code{\link[=graph_]{graph_()}}, \code{\link[=make_]{make_()}} and \code{\link[=sample_]{sample_()}} to apply a constructor -specification. +\code{\link[=graph_]{graph_()}}, \code{\link[=make_]{make_()}} and \code{\link[=sample_]{sample_()}} to apply a constructor specification. } \concept{constructor specifications} \keyword{graphs} diff --git a/man/contract.Rd b/man/contract.Rd index aa11b59eced..94de9e6d6ef 100644 --- a/man/contract.Rd +++ b/man/contract.Rd @@ -9,25 +9,23 @@ contract(graph, mapping, vertex.attr.comb = NULL) \arguments{ \item{graph}{The input graph, it can be directed or undirected.} -\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{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. The -default \code{NULL} uses the \code{vertex.attr.comb} igraph option.} +\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. +The default \code{NULL} uses the \code{vertex.attr.comb} igraph option.} } \value{ A new graph object. } \description{ -This function creates a new graph, by merging several vertices into one. The -vertices in the new graph correspond to sets of vertices in the input graph. +This function creates a new graph, by merging several vertices into one. +The 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. +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. } \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()}} diff --git a/man/contract.vertices.Rd b/man/contract.vertices.Rd index b527e63f73d..02bccd682be 100644 --- a/man/contract.vertices.Rd +++ b/man/contract.vertices.Rd @@ -13,19 +13,17 @@ contract.vertices( \arguments{ \item{graph}{The input graph, it can be directed or undirected.} -\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{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. The -default \code{NULL} uses the \code{vertex.attr.comb} igraph option.} +\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. +The default \code{NULL} uses the \code{vertex.attr.comb} igraph option.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{contract.vertices()} was renamed to \code{\link[=contract]{contract()}} to create a more -consistent API. +\code{contract.vertices()} was renamed to \code{\link[=contract]{contract()}} to create a more consistent API. } \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()}} diff --git a/man/convex.hull.Rd b/man/convex.hull.Rd index 24d33b9f750..2b8c5d5a8b8 100644 --- a/man/convex.hull.Rd +++ b/man/convex.hull.Rd @@ -12,8 +12,7 @@ convex.hull(data) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{convex.hull()} was renamed to \code{\link[=convex_hull]{convex_hull()}} to create a more -consistent API. +\code{convex.hull()} was renamed to \code{\link[=convex_hull]{convex_hull()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Nongraph.html#igraph_convex_hull_2d}{\code{convex_hull_2d()}} diff --git a/man/convex_hull.Rd b/man/convex_hull.Rd index 39096df0101..8ad48b5957a 100644 --- a/man/convex_hull.Rd +++ b/man/convex_hull.Rd @@ -21,8 +21,7 @@ The coordinates of the corners of the convex hull. } } \description{ -Calculate the convex hull of a set of points, i.e. the covering polygon that -has the smallest area. +Calculate the convex hull of a set of points, i.e. the covering polygon that has the smallest area. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Nongraph.html#igraph_convex_hull_2d}{\code{convex_hull_2d()}} diff --git a/man/coreness.Rd b/man/coreness.Rd index 86253a2c365..642a5e414a0 100644 --- a/man/coreness.Rd +++ b/man/coreness.Rd @@ -11,24 +11,21 @@ coreness(graph, ..., mode = c("all", "out", "in")) \item{...}{These dots are for future extensions and must be empty.} -\item{mode}{The type of the core in directed graphs. Character constant, -possible values: \verb{in}: in-cores are computed, \code{out}: out-cores are -computed, \code{all}: the corresponding undirected graph is considered. This -argument is ignored for undirected graphs.} +\item{mode}{The type of the core in directed graphs. +Character constant, possible values: \verb{in}: in-cores are computed, \code{out}: out-cores are computed, \code{all}: +the corresponding undirected graph is considered. +This argument is ignored for undirected graphs.} } \value{ -Numeric vector of integer numbers giving the coreness of each -vertex. +Numeric vector of integer numbers giving the coreness of each vertex. } \description{ -The k-core of graph is a maximal subgraph in which each vertex has at least -degree k. The coreness of a vertex is k if it belongs to the k-core but not -to the (k+1)-core. +The k-core of graph is a maximal subgraph in which each vertex has at least degree k. +The coreness of a vertex is k if it belongs to the k-core but not to the (k+1)-core. } \details{ -The k-core of a graph is the maximal subgraph in which every vertex has at -least degree k. The cores of a graph form layers: the (k+1)-core is always a -subgraph of the k-core. +The k-core of a graph is the maximal subgraph in which every vertex has at least degree k. +The cores of a graph form layers: the (k+1)-core is always a subgraph of the k-core. This function calculates the coreness for each vertex. } diff --git a/man/count.multiple.Rd b/man/count.multiple.Rd index a4e624fe0cb..3e75e580a3d 100644 --- a/man/count.multiple.Rd +++ b/man/count.multiple.Rd @@ -9,14 +9,13 @@ count.multiple(graph, eids = E(graph)) \arguments{ \item{graph}{The input graph.} -\item{eids}{The edges to which the query is restricted. The default -\code{NULL} selects all edges.} +\item{eids}{The edges to which the query is restricted. +The default \code{NULL} selects all edges.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{count.multiple()} was renamed to \code{\link[=count_multiple]{count_multiple()}} to create a more -consistent API. +\code{count.multiple()} was renamed to \code{\link[=count_multiple]{count_multiple()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_count_multiple}{\code{count_multiple()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/count_automorphisms.Rd b/man/count_automorphisms.Rd index 522ba3b2274..91286fdb977 100644 --- a/man/count_automorphisms.Rd +++ b/man/count_automorphisms.Rd @@ -14,18 +14,16 @@ count_automorphisms( \arguments{ \item{graph}{The input graph, it is treated as undirected.} -\item{colors}{The colors of the individual vertices of the graph; only -vertices having the same color are allowed to match each other in an -automorphism. When omitted, igraph uses the \code{color} attribute of the -vertices, or, if there is no such vertex attribute, it simply assumes that -all vertices have the same color. Pass NULL explicitly if the graph has a -\code{color} vertex attribute but you do not want to use it.} +\item{colors}{The colors of the individual vertices of the graph; +only vertices having the same color are allowed to match each other in an automorphism. +When omitted, igraph uses the \code{color} attribute of the vertices, or, if there is no such vertex attribute, +it simply assumes that all vertices have the same color. +Pass NULL explicitly if the graph has a \code{color} vertex attribute but you do not want to use it.} \item{...}{These dots are for future extensions and must be empty.} -\item{sh}{The splitting heuristics for the BLISS algorithm. Possible values -are: -\sQuote{\code{f}}: +\item{sh}{The splitting heuristics for the BLISS algorithm. +Possible values are: \sQuote{\code{f}}: first non-singleton cell, \sQuote{\code{fl}}: first largest non-singleton cell, @@ -65,18 +63,14 @@ Maximum level. } } \description{ -Calculate the number of automorphisms of a graph, i.e. the number of -isomorphisms to itself. +Calculate the number of automorphisms of a graph, i.e. the number of isomorphisms to itself. } \details{ -An automorphism of a graph is a permutation of its vertices which brings the -graph into itself. +An automorphism of a graph is a permutation of its vertices which brings the graph into itself. -This function calculates the number of automorphism of a graph using the -BLISS algorithm. See also the BLISS homepage at -\url{http://www.tcs.hut.fi/Software/bliss/index.html}. If you need the -automorphisms themselves, use \code{\link[=automorphism_group]{automorphism_group()}} to obtain -a compact representation of the automorphism group. +This function calculates the number of automorphism of a graph using the BLISS algorithm. +See also the BLISS homepage at \url{http://www.tcs.hut.fi/Software/bliss/index.html}. +If you need the automorphisms themselves, use \code{\link[=automorphism_group]{automorphism_group()}} to obtain a compact representation of the automorphism group. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Isomorphism.html#igraph_count_automorphisms}{\code{count_automorphisms()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} @@ -101,9 +95,7 @@ the Ninth Workshop on Algorithm Engineering and Experiments and the Fourth Workshop on Analytic Algorithms and Combinatorics.} 2007. } \seealso{ -\code{\link[=canonical_permutation]{canonical_permutation()}}, \code{\link[=permute]{permute()}}, -and \code{\link[=automorphism_group]{automorphism_group()}} for a compact representation of all -automorphisms +\code{\link[=canonical_permutation]{canonical_permutation()}}, \code{\link[=permute]{permute()}}, and \code{\link[=automorphism_group]{automorphism_group()}} for a compact representation of all automorphisms Other graph automorphism: \code{\link[=automorphism_group]{automorphism_group()}} diff --git a/man/count_isomorphisms.Rd b/man/count_isomorphisms.Rd index 2a11faae1a0..ca83cba7ac6 100644 --- a/man/count_isomorphisms.Rd +++ b/man/count_isomorphisms.Rd @@ -12,8 +12,7 @@ count_isomorphisms(graph1, graph2, method = "vf2", ...) \item{graph2}{The second graph.} -\item{method}{Currently only \sQuote{vf2} is supported, see -\code{\link[=isomorphic]{isomorphic()}} for details about it and extra arguments.} +\item{method}{Currently only \sQuote{vf2} is supported, see \code{\link[=isomorphic]{isomorphic()}} for details about it and extra arguments.} \item{...}{Passed to the individual methods.} } diff --git a/man/count_motifs.Rd b/man/count_motifs.Rd index 3c8e663d0cd..4173b2a5e71 100644 --- a/man/count_motifs.Rd +++ b/man/count_motifs.Rd @@ -13,21 +13,19 @@ count_motifs(graph, size = 3, ..., cut.prob = NULL) \item{...}{These dots are for future extensions and must be empty.} -\item{cut.prob}{Numeric vector giving the probabilities that the search -graph is cut at a certain level. Its length should be the same as the size -of the motif (the \code{size} argument). +\item{cut.prob}{Numeric vector giving the probabilities that the search graph is cut at a certain level. +Its length should be the same as the size of the motif (the \code{size} argument). If \code{NULL}, the default, no cuts are made.} } \value{ \code{count_motifs()} returns a numeric scalar. } \description{ -Graph motifs are small connected induced subgraphs with a well-defined -structure. These functions search a graph for various motifs. +Graph motifs are small connected induced subgraphs with a well-defined structure. +These functions search a graph for various motifs. } \details{ -\code{count_motifs()} calculates the total number of motifs of a given -size in graph. +\code{count_motifs()} calculates the total number of motifs of a given size in graph. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Motifs.html#igraph_motifs_randesu_no}{\code{motifs_randesu_no()}} diff --git a/man/count_reachable.Rd b/man/count_reachable.Rd index f8119699b19..620793ce607 100644 --- a/man/count_reachable.Rd +++ b/man/count_reachable.Rd @@ -11,18 +11,14 @@ count_reachable(graph, ..., mode = c("out", "in", "all", "total")) \item{...}{These dots are for future extensions and must be empty.} -\item{mode}{Character constant, defines how edge directions are considered -in directed graphs. +\item{mode}{Character constant, defines how edge directions are considered in directed graphs. \code{"out"} counts vertices reachable via outgoing edges, -\code{"in"} counts vertices from which the current vertex is reachable via -incoming edges, -\code{"all"} or \code{"total"} ignores edge directions. +\code{"in"} counts vertices from which the current vertex is reachable via incoming edges, \code{"all"} or \code{"total"} ignores edge directions. This parameter is ignored for undirected graphs.} } \value{ An integer vector of length \code{vcount(graph)}. -The i-th element is the number of vertices reachable from vertex i -(including vertex i itself). +The i-th element is the number of vertices reachable from vertex i (including vertex i itself). } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} @@ -30,11 +26,9 @@ The i-th element is the number of vertices reachable from vertex i \details{ Counts the number of vertices reachable from each vertex in the graph. -For each vertex in the graph, this function counts how many vertices -are reachable from it, including the vertex itself. +For each vertex in the graph, this function counts how many vertices are reachable from it, including the vertex itself. A vertex is reachable from another if there is a directed path between them. -For undirected graphs, two vertices are reachable from each other if they -are in the same connected component. +For undirected graphs, two vertices are reachable from each other if they are in the same connected component. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_count_reachable}{\code{count_reachable()}} diff --git a/man/count_subgraph_isomorphisms.Rd b/man/count_subgraph_isomorphisms.Rd index 283d03aeaa4..65889ff774d 100644 --- a/man/count_subgraph_isomorphisms.Rd +++ b/man/count_subgraph_isomorphisms.Rd @@ -3,37 +3,33 @@ \name{count_subgraph_isomorphisms} \alias{count_subgraph_isomorphisms} \alias{graph.count.subisomorphisms.vf2} -\title{Count the isomorphic mappings between a graph and the subgraphs of -another graph} +\title{Count the isomorphic mappings between a graph and the subgraphs of another graph} \usage{ count_subgraph_isomorphisms(pattern, target, method = c("lad", "vf2"), ...) } \arguments{ -\item{pattern}{The smaller graph, it might be directed or -undirected. Undirected graphs are treated as directed graphs with -mutual edges.} +\item{pattern}{The smaller graph, it might be directed or undirected. +Undirected graphs are treated as directed graphs with mutual edges.} -\item{target}{The bigger graph, it might be directed or -undirected. Undirected graphs are treated as directed graphs with -mutual edges.} +\item{target}{The bigger graph, it might be directed or undirected. +Undirected graphs are treated as directed graphs with mutual edges.} -\item{method}{The method to use. Possible values: -\sQuote{lad}, \sQuote{vf2}. See their details below.} +\item{method}{The method to use. +Possible values: \sQuote{lad}, \sQuote{vf2}. +See their details below.} \item{...}{Additional arguments, passed to the various methods.} } \value{ -Logical scalar, \code{TRUE} if the \code{pattern} is -isomorphic to a (possibly induced) subgraph of \code{target}. +Logical scalar, \code{TRUE} if the \code{pattern} is isomorphic to a (possibly induced) subgraph of \code{target}. } \description{ -Count the isomorphic mappings between a graph and the subgraphs of -another graph +Count the isomorphic mappings between a graph and the subgraphs of another graph } \section{\sQuote{lad} method}{ -This is the LAD algorithm by Solnon, see the reference below. It has -the following extra arguments: +This is the LAD algorithm by Solnon, see the reference below. +It has the following extra arguments: \describe{ \item{domains}{ Matching restrictions. @@ -53,9 +49,8 @@ The processor time limit for the computation, in seconds. It defaults to \code{I \section{\sQuote{vf2} method}{ -This method uses the VF2 algorithm by Cordella, Foggia et al., see -references below. It supports vertex and edge colors and have the -following extra arguments: +This method uses the VF2 algorithm by Cordella, Foggia et al., see references below. +It supports vertex and edge colors and have the following extra arguments: \describe{ \item{vertex.color1, vertex.color2}{ Optional integer vectors giving the colors of the vertices for colored graph isomorphism. diff --git a/man/count_triangles.Rd b/man/count_triangles.Rd index 99af82f07da..7010c512784 100644 --- a/man/count_triangles.Rd +++ b/man/count_triangles.Rd @@ -10,28 +10,25 @@ triangles(graph) count_triangles(graph, vids = NULL) } \arguments{ -\item{graph}{The input graph. It might be directed, but edge directions are -ignored.} +\item{graph}{The input graph. +It might be directed, but edge directions are ignored.} -\item{vids}{The vertices to query. This might be a vector of numeric IDs, -or a character vector of symbolic vertex names for named graphs. The -default \code{NULL} selects all vertices.} +\item{vids}{The vertices to query. +This might be a vector of numeric IDs, or a character vector of symbolic vertex names for named graphs. +The default \code{NULL} selects all vertices.} } \value{ -For \code{triangles()} a numeric vector of vertex IDs, the first three -vertices belong to the first triangle found, etc. +For \code{triangles()} a numeric vector of vertex IDs, the first three vertices belong to the first triangle found, etc. -For \code{count_triangles()} a numeric vector, the number of triangles for all -vertices queried. +For \code{count_triangles()} a numeric vector, the number of triangles for all vertices queried. } \description{ -Count how many triangles a vertex is part of, in a graph, or just list the -triangles of a graph. +Count how many triangles a vertex is part of, in a graph, or just list the triangles of a graph. } \details{ -\code{triangles()} lists all triangles of a graph. For efficiency, all -triangles are returned in a single vector. The first three vertices belong -to the first triangle, etc. +\code{triangles()} lists all triangles of a graph. +For efficiency, all triangles are returned in a single vector. +The first three vertices belong to the first triangle, etc. \code{count_triangles()} counts how many triangles a vertex is part of. } diff --git a/man/create.communities.Rd b/man/create.communities.Rd index d50e660e9f8..4f74c8aaf43 100644 --- a/man/create.communities.Rd +++ b/man/create.communities.Rd @@ -15,24 +15,19 @@ create.communities( \arguments{ \item{graph}{The graph of the community structure.} -\item{membership}{The membership vector of the community structure, a -numeric vector denoting the ID of the community for each vertex. It -might be \code{NULL} for hierarchical community structures.} +\item{membership}{The membership vector of the community structure, a numeric vector denoting the ID of the community for each vertex. +It might be \code{NULL} for hierarchical community structures.} -\item{algorithm}{Character string, the algorithm that generated -the community structure, it can be arbitrary.} +\item{algorithm}{Character string, the algorithm that generated the community structure, it can be arbitrary.} -\item{merges}{A merge matrix, for hierarchical community structures (or -\code{NULL} otherwise.} +\item{merges}{A merge matrix, for hierarchical community structures (or \code{NULL} otherwise.} -\item{modularity}{Modularity value of the community structure. If this -is \code{TRUE} and the membership vector is available, then it the -modularity values is calculated automatically.} +\item{modularity}{Modularity value of the community structure. +If this is \code{TRUE} and the membership vector is available, then it the modularity values is calculated automatically.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{create.communities()} was renamed to \code{\link[=make_clusters]{make_clusters()}} to create a more -consistent API. +\code{create.communities()} was renamed to \code{\link[=make_clusters]{make_clusters()}} to create a more consistent API. } \keyword{internal} diff --git a/man/curve_multiple.Rd b/man/curve_multiple.Rd index fb9831ed2f9..c295b75ab4a 100644 --- a/man/curve_multiple.Rd +++ b/man/curve_multiple.Rd @@ -11,21 +11,19 @@ curve_multiple(graph, ..., start = 0.5) \item{...}{These dots are for future extensions and must be empty.} -\item{start}{The curvature at the two extreme edges. All edges will have a -curvature between \code{-start} and \code{start}, spaced equally.} +\item{start}{The curvature at the two extreme edges. +All edges will have a curvature between \code{-start} and \code{start}, spaced equally.} } \value{ A numeric vector, its length is the number of edges in the graph. } \description{ -If graphs have multiple edges, then drawing them as straight lines does not -show them when plotting the graphs; they will be on top of each other. One -solution is to bend the edges, with diffenent curvature, so that all of them -are visible. +If graphs have multiple edges, then drawing them as straight lines does not show them when plotting the graphs; +they will be on top of each other. +One solution is to bend the edges, with diffenent curvature, so that all of them are visible. } \details{ -\code{curve_multiple()} calculates the optimal \code{edge.curved} vector for -plotting a graph with multiple edges, so that all edges are visible. +\code{curve_multiple()} calculates the optimal \code{edge.curved} vector for plotting a graph with multiple edges, so that all edges are visible. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_edgelist}{\code{get_edgelist()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} @@ -45,9 +43,7 @@ plot(g) } \seealso{ -\link{igraph.plotting} for all plotting parameters, -\code{\link[=plot.igraph]{plot.igraph()}}, \code{\link[=tkplot]{tkplot()}} and \code{\link[=rglplot]{rglplot()}} -for plotting functions. +\link{igraph.plotting} for all plotting parameters, \code{\link[=plot.igraph]{plot.igraph()}}, \code{\link[=tkplot]{tkplot()}} and \code{\link[=rglplot]{rglplot()}} for plotting functions. } \author{ Gabor Csardi \email{csardi.gabor@gmail.com} diff --git a/man/cutat.Rd b/man/cutat.Rd index e2ff41a32bd..1c4cbee7533 100644 --- a/man/cutat.Rd +++ b/man/cutat.Rd @@ -7,18 +7,17 @@ cutat(communities, no, steps) } \arguments{ -\item{no}{Integer scalar, the desired number of communities. If too low or -two high, then an error message is given. Exactly one of \code{no} and -\code{steps} must be supplied.} +\item{no}{Integer scalar, the desired number of communities. +If too low or two high, then an error message is given. +Exactly one of \code{no} and \code{steps} must be supplied.} -\item{steps}{The number of merge operations to perform to produce the -communities. Exactly one of \code{no} and \code{steps} must be supplied.} +\item{steps}{The number of merge operations to perform to produce the communities. +Exactly one of \code{no} and \code{steps} must be supplied.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{cutat()} was renamed to \code{\link[=cut_at]{cut_at()}} to create a more -consistent API. +\code{cutat()} was renamed to \code{\link[=cut_at]{cut_at()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Community.html#igraph_le_community_to_membership}{\code{le_community_to_membership()}} diff --git a/man/decompose.Rd b/man/decompose.Rd index 264666b6501..8362c53d880 100644 --- a/man/decompose.Rd +++ b/man/decompose.Rd @@ -17,19 +17,16 @@ decompose( \item{...}{These dots are for future extensions and must be empty.} -\item{mode}{Character constant giving the type of the components, wither -\code{weak} for weakly connected components or \code{strong} for strongly -connected components.} +\item{mode}{Character constant giving the type of the components, +wither \code{weak} for weakly connected components or \code{strong} for strongly connected components.} -\item{max.comps}{The maximum number of components to return. The first -\code{max.comps} components will be returned (which hold at least -\code{min.vertices} vertices, see the next parameter), the others will be -ignored. Supply \code{NA} here if you don't want to limit the number of -components.} +\item{max.comps}{The maximum number of components to return. +The first \code{max.comps} components will be returned (which hold at least \code{min.vertices} vertices, see the next parameter), +the others will be ignored. +Supply \code{NA} here if you don't want to limit the number of components.} -\item{min.vertices}{The minimum number of vertices a component should -contain in order to place it in the result list. E.g. supply 2 here to ignore -isolate vertices.} +\item{min.vertices}{The minimum number of vertices a component should contain in order to place it in the result list. +E.g. supply 2 here to ignore isolate vertices.} } \value{ A list of graph objects. diff --git a/man/decompose.graph.Rd b/man/decompose.graph.Rd index 2065be1e2c1..57704003b5e 100644 --- a/man/decompose.graph.Rd +++ b/man/decompose.graph.Rd @@ -14,25 +14,21 @@ decompose.graph( \arguments{ \item{graph}{The original graph.} -\item{mode}{Character constant giving the type of the components, wither -\code{weak} for weakly connected components or \code{strong} for strongly -connected components.} +\item{mode}{Character constant giving the type of the components, +wither \code{weak} for weakly connected components or \code{strong} for strongly connected components.} -\item{max.comps}{The maximum number of components to return. The first -\code{max.comps} components will be returned (which hold at least -\code{min.vertices} vertices, see the next parameter), the others will be -ignored. Supply \code{NA} here if you don't want to limit the number of -components.} +\item{max.comps}{The maximum number of components to return. +The first \code{max.comps} components will be returned (which hold at least \code{min.vertices} vertices, see the next parameter), +the others will be ignored. +Supply \code{NA} here if you don't want to limit the number of components.} -\item{min.vertices}{The minimum number of vertices a component should -contain in order to place it in the result list. E.g. supply 2 here to ignore -isolate vertices.} +\item{min.vertices}{The minimum number of vertices a component should contain in order to place it in the result list. +E.g. supply 2 here to ignore isolate vertices.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{decompose.graph()} was renamed to \code{\link[=decompose]{decompose()}} to create a more -consistent API. +\code{decompose.graph()} was renamed to \code{\link[=decompose]{decompose()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_decompose}{\code{decompose()}} diff --git a/man/degree.Rd b/man/degree.Rd index ec7c9277b44..ccd04812e04 100644 --- a/man/degree.Rd +++ b/man/degree.Rd @@ -36,38 +36,33 @@ The default \code{NULL} selects all vertices.} \item{...}{These dots are for future extensions and must be empty.} -\item{mode}{Character string, \dQuote{out} for out-degree, \dQuote{in} for -in-degree or \dQuote{total} for the sum of the two. For undirected graphs -this argument is ignored. \dQuote{all} is a synonym of \dQuote{total}.} +\item{mode}{Character string, \dQuote{out} for out-degree, \dQuote{in} for in-degree or \dQuote{total} for the sum of the two. +For undirected graphs this argument is ignored. +\dQuote{all} is a synonym of \dQuote{total}.} \item{loops}{Logical; whether the loop edges are also counted.} -\item{normalized}{Logical, whether to normalize the degree. If -\code{TRUE} then the result is divided by \eqn{n-1}, where \eqn{n} is the -number of vertices in the graph.} +\item{normalized}{Logical, whether to normalize the degree. +If \code{TRUE} then the result is divided by \eqn{n-1}, +where \eqn{n} is the number of vertices in the graph.} -\item{cumulative}{Logical; whether the cumulative degree distribution is to -be calculated.} +\item{cumulative}{Logical; whether the cumulative degree distribution is to be calculated.} } \value{ -For \code{degree()} a numeric vector of the same length as argument -\code{v}. +For \code{degree()} a numeric vector of the same length as argument \code{v}. -For \code{degree_distribution()} a numeric vector of the same length as the -maximum degree plus one. The first element is the relative frequency zero -degree vertices, the second vertices with degree one, etc. +For \code{degree_distribution()} a numeric vector of the same length as the maximum degree plus one. +The first element is the relative frequency zero degree vertices, the second vertices with degree one, etc. -For \code{max_degree()}, the largest degree in the graph. When no vertices are -selected, or when the input is the null graph, zero is returned as this -is the smallest possible degree. +For \code{max_degree()}, the largest degree in the graph. +When no vertices are selected, or when the input is the null graph, zero is returned as this is the smallest possible degree. For \code{mean_degree()}, the average degree in the graph as a single number. For graphs with no vertices, \code{NaN} is returned. \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} } \description{ -The degree of a vertex is its most basic structural property, the number of -its adjacent edges. +The degree of a vertex is its most basic structural property, the number of its adjacent edges. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_degree}{\code{degree()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_maxdegree}{\code{maxdegree()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_mean_degree}{\code{mean_degree()}} diff --git a/man/degree.distribution.Rd b/man/degree.distribution.Rd index 69d71e21734..eb29774d938 100644 --- a/man/degree.distribution.Rd +++ b/man/degree.distribution.Rd @@ -9,16 +9,14 @@ degree.distribution(graph, cumulative = FALSE, ...) \arguments{ \item{graph}{The graph to analyze.} -\item{cumulative}{Logical; whether the cumulative degree distribution is to -be calculated.} +\item{cumulative}{Logical; whether the cumulative degree distribution is to be calculated.} \item{...}{These dots are for future extensions and must be empty.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{degree.distribution()} was renamed to \code{\link[=degree_distribution]{degree_distribution()}} to create a more -consistent API. +\code{degree.distribution()} was renamed to \code{\link[=degree_distribution]{degree_distribution()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_degree}{\code{degree()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/degree.sequence.game.Rd b/man/degree.sequence.game.Rd index f4ddb22e73f..84740870d0d 100644 --- a/man/degree.sequence.game.Rd +++ b/man/degree.sequence.game.Rd @@ -11,21 +11,20 @@ degree.sequence.game( ) } \arguments{ -\item{out.deg}{Numeric vector, the sequence of degrees (for undirected -graphs) or out-degrees (for directed graphs). For undirected graphs its sum -should be even. For directed graphs its sum should be the same as the sum of -\code{in.deg}.} +\item{out.deg}{Numeric vector, the sequence of degrees (for undirected graphs) or out-degrees (for directed graphs). +For undirected graphs its sum should be even. +For directed graphs its sum should be the same as the sum of \code{in.deg}.} -\item{in.deg}{For directed graph, the in-degree sequence. By default this is -\code{NULL} and an undirected graph is created.} +\item{in.deg}{For directed graph, the in-degree sequence. +By default this is \code{NULL} and an undirected graph is created.} -\item{method}{Character, the method for generating the graph. See Details.} +\item{method}{Character, the method for generating the graph. +See Details.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{degree.sequence.game()} was renamed to \code{\link[=sample_degseq]{sample_degseq()}} to create a more -consistent API. +\code{degree.sequence.game()} was renamed to \code{\link[=sample_degseq]{sample_degseq()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_degree_sequence_game}{\code{degree_sequence_game()}} diff --git a/man/delete.edges.Rd b/man/delete.edges.Rd index 3c0a70138f7..d44fb9c96a7 100644 --- a/man/delete.edges.Rd +++ b/man/delete.edges.Rd @@ -9,16 +9,14 @@ delete.edges(graph, edges) \arguments{ \item{graph}{The input graph.} -\item{edges}{The edges to remove, specified as an edge sequence. Typically -this is either a numeric vector containing edge IDs, or a character vector -containing the IDs or names of the source and target vertices, separated by -\code{|}} +\item{edges}{The edges to remove, specified as an edge sequence. +Typically this is either a numeric vector containing edge IDs, +or a character vector containing the IDs or names of the source and target vertices, separated by \code{|}} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{delete.edges()} was renamed to \code{\link[=delete_edges]{delete_edges()}} to create a more -consistent API. +\code{delete.edges()} was renamed to \code{\link[=delete_edges]{delete_edges()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_delete_edges}{\code{delete_edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/delete.vertices.Rd b/man/delete.vertices.Rd index a956f6e4657..b8b09da06bc 100644 --- a/man/delete.vertices.Rd +++ b/man/delete.vertices.Rd @@ -14,8 +14,7 @@ delete.vertices(graph, v) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{delete.vertices()} was renamed to \code{\link[=delete_vertices]{delete_vertices()}} to create a more -consistent API. +\code{delete.vertices()} was renamed to \code{\link[=delete_vertices]{delete_vertices()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_delete_vertices}{\code{delete_vertices()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/delete_edges.Rd b/man/delete_edges.Rd index ca7508c1fe2..bae801ab511 100644 --- a/man/delete_edges.Rd +++ b/man/delete_edges.Rd @@ -9,10 +9,9 @@ delete_edges(graph, edges) \arguments{ \item{graph}{The input graph.} -\item{edges}{The edges to remove, specified as an edge sequence. Typically -this is either a numeric vector containing edge IDs, or a character vector -containing the IDs or names of the source and target vertices, separated by -\code{|}} +\item{edges}{The edges to remove, specified as an edge sequence. +Typically this is either a numeric vector containing edge IDs, +or a character vector containing the IDs or names of the source and target vertices, separated by \code{|}} } \value{ The graph, with the edges removed. diff --git a/man/dendPlot.Rd b/man/dendPlot.Rd index 0333797f582..9b09eac0496 100644 --- a/man/dendPlot.Rd +++ b/man/dendPlot.Rd @@ -7,19 +7,18 @@ dendPlot(x, mode = igraph_opt("dend.plot.type"), ...) } \arguments{ -\item{x}{An object containing the community structure of a graph. See -\code{\link[=communities]{communities()}} for details.} +\item{x}{An object containing the community structure of a graph. +See \code{\link[=communities]{communities()}} for details.} -\item{mode}{Which dendrogram plotting function to use. See details below. +\item{mode}{Which dendrogram plotting function to use. +See details below. The default \code{NULL} uses the \code{dend.plot.type} igraph option.} -\item{...}{Additional arguments to supply to the dendrogram plotting -function.} +\item{...}{Additional arguments to supply to the dendrogram plotting function.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{dendPlot()} was renamed to \code{\link[=plot_dendrogram]{plot_dendrogram()}} to create a more -consistent API. +\code{dendPlot()} was renamed to \code{\link[=plot_dendrogram]{plot_dendrogram()}} to create a more consistent API. } \keyword{internal} diff --git a/man/dfs.Rd b/man/dfs.Rd index 5364bfd8605..31d2c80f95c 100644 --- a/man/dfs.Rd +++ b/man/dfs.Rd @@ -28,35 +28,32 @@ dfs( \item{root}{The single root vertex to start the search from.} \item{mode}{For directed graphs specifies the type of edges to follow. -\sQuote{out} follows outgoing, \sQuote{in} incoming edges. \sQuote{all} -ignores edge directions completely. \sQuote{total} is a synonym for -\sQuote{all}. This argument is ignored for undirected graphs.} +\sQuote{out} follows outgoing, \sQuote{in} incoming edges. +\sQuote{all} ignores edge directions completely. +\sQuote{total} is a synonym for \sQuote{all}. +This argument is ignored for undirected graphs.} \item{...}{These dots are for future extensions and must be empty.} -\item{unreachable}{Logical, whether the search should visit the -vertices that are unreachable from the given root vertex (or vertices). If -\code{TRUE}, then additional searches are performed until all vertices are -visited.} +\item{unreachable}{Logical, whether the search should visit the vertices that are unreachable from the given root vertex (or vertices). +If \code{TRUE}, then additional searches are performed until all vertices are visited.} -\item{order}{Logical, whether to return the DFS ordering of the -vertices.} +\item{order}{Logical, whether to return the DFS ordering of the vertices.} -\item{order.out}{Logical, whether to return the ordering based on -leaving the subtree of the vertex.} +\item{order.out}{Logical, whether to return the ordering based on leaving the subtree of the vertex.} \item{parent}{Logical, whether to return the parent of the vertices.} -\item{dist}{Logical, whether to return the distance from the root of -the search tree.} +\item{dist}{Logical, whether to return the distance from the root of the search tree.} \item{in.callback}{Callback function. -This is called whenever a vertex is visited. See details below. +This is called whenever a vertex is visited. +See details below. Default: \code{NULL}.} \item{out.callback}{Callback function. -This is called whenever the subtree of a vertex is completed by the -algorithm. See details below. +This is called whenever the subtree of a vertex is completed by the algorithm. +See details below. Default: \code{NULL}.} \item{extra}{Additional argument to supply to the callback function.} @@ -64,8 +61,7 @@ Default: \code{NULL}.} \item{rho}{The environment in which the callback function is evaluated. The default \code{NULL} uses the caller's environment.} -\item{neimode}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} This argument is deprecated from igraph 1.3.0; use -\code{mode} instead.} +\item{neimode}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} This argument is deprecated from igraph 1.3.0; use \code{mode} instead.} \item{father}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}, use \code{parent} instead.} } @@ -96,13 +92,12 @@ Numeric vector, for each vertex its distance from the root of the search tree. } } -Note that \code{order}, \code{order.out}, \code{parent}, and \code{dist} -might be \code{NULL} if their corresponding argument is \code{FALSE}, i.e. -if their calculation is not requested. +Note that \code{order}, \code{order.out}, \code{parent}, and \code{dist} might be \code{NULL} if their corresponding argument is \code{FALSE}, +i.e. if their calculation is not requested. } \description{ -Depth-first search is an algorithm to traverse a graph. It starts from a -root vertex and tries to go quickly as far from as possible. +Depth-first search is an algorithm to traverse a graph. +It starts from a root vertex and tries to go quickly as far from as possible. } \details{ The callback functions must have the following arguments: @@ -119,7 +114,8 @@ A named numeric vector, with the following entries: The extra argument. } } The callback must return FALSE to continue the search or TRUE -to terminate it. See examples below on how to use the callback functions. +to terminate it. +See examples below on how to use the callback functions. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/diameter.Rd b/man/diameter.Rd index b8f8451cff1..4709c99305f 100644 --- a/man/diameter.Rd +++ b/man/diameter.Rd @@ -23,23 +23,19 @@ farthest_vertices( \item{...}{These dots are for future extensions and must be empty.} -\item{directed}{Logical, whether directed or undirected paths are to be -considered. This is ignored for undirected graphs.} +\item{directed}{Logical, whether directed or undirected paths are to be considered. +This is ignored for undirected graphs.} -\item{unconnected}{Logical, what to do if the graph is unconnected. If -FALSE, the function will return a number that is one larger the largest -possible diameter, which is always the number of vertices. If TRUE, the -diameters of the connected components will be calculated and the largest one -will be returned.} +\item{unconnected}{Logical, what to do if the graph is unconnected. +If FALSE, the function will return a number that is one larger the largest possible diameter, which is always the number of vertices. +If TRUE, the diameters of the connected components will be calculated and the largest one will be returned.} -\item{weights}{Optional positive weight vector for calculating weighted -distances. If the graph has a \code{weight} edge attribute, then this is -used by default.} +\item{weights}{Optional positive weight vector for calculating weighted distances. +If the graph has a \code{weight} edge attribute, then this is used by default.} } \value{ -A numeric constant for \code{diameter()}, a numeric vector for -\code{get_diameter()}. \code{farthest_vertices()} returns a list with two -entries: +A numeric constant for \code{diameter()}, a numeric vector for \code{get_diameter()}. +\code{farthest_vertices()} returns a list with two entries: \describe{ \item{\code{vertices}}{ The two vertices that are the farthest. @@ -55,12 +51,10 @@ The diameter of a graph is the length of the longest geodesic. \details{ The diameter is calculated by using a breadth-first search like method. -\code{get_diameter()} returns a path with the actual diameter. If there are -many shortest paths of the length of the diameter, then it returns the first -one found. +\code{get_diameter()} returns a path with the actual diameter. +If there are many shortest paths of the length of the diameter, then it returns the first one found. -\code{farthest_vertices()} returns two vertex IDs, the vertices which are -connected by the diameter path. +\code{farthest_vertices()} returns two vertex IDs, the vertices which are connected by the diameter path. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/difference.Rd b/man/difference.Rd index e805f8e8102..8c0e7b52c46 100644 --- a/man/difference.Rd +++ b/man/difference.Rd @@ -7,19 +7,16 @@ difference(...) } \arguments{ -\item{...}{Arguments, their number and interpretation depends on -the function that implements \code{difference()}.} +\item{...}{Arguments, their number and interpretation depends on the function that implements \code{difference()}.} } \value{ Depends on the function that implements this method. } \description{ -This is an S3 generic function. See \code{methods("difference")} -for the actual implementations for various S3 classes. Initially -it is implemented for igraph graphs (difference of edges in two graphs), -and igraph vertex and edge sequences. See -\code{\link[=difference.igraph]{difference.igraph()}}, and -\code{\link[=difference.igraph.vs]{difference.igraph.vs()}}. +This is an S3 generic function. +See \code{methods("difference")} for the actual implementations for various S3 classes. +Initially it is implemented for igraph graphs (difference of edges in two graphs), and igraph vertex and edge sequences. +See \code{\link[=difference.igraph]{difference.igraph()}}, and \code{\link[=difference.igraph.vs]{difference.igraph.vs()}}. } \seealso{ Other functions for manipulating graph structure: diff --git a/man/difference.igraph.Rd b/man/difference.igraph.Rd index 7bae49e61d5..23ede828d34 100644 --- a/man/difference.igraph.Rd +++ b/man/difference.igraph.Rd @@ -8,17 +8,16 @@ \method{difference}{igraph}(big, small, byname = "auto", ...) } \arguments{ -\item{big}{The left hand side argument of the minus operator. A directed or -undirected graph.} +\item{big}{The left hand side argument of the minus operator. +A directed or undirected graph.} -\item{small}{The right hand side argument of the minus operator. A directed -ot undirected graph.} +\item{small}{The right hand side argument of the minus operator. +A directed ot undirected graph.} -\item{byname}{A Logical, or the character scalar \code{auto}. Whether -to perform the operation based on symbolic vertex names. If it is -\code{auto}, that means \code{TRUE} if both graphs are named and -\code{FALSE} otherwise. A warning is generated if \code{auto} and one graph, -but not both graphs are named.} +\item{byname}{A Logical, or the character scalar \code{auto}. +Whether to perform the operation based on symbolic vertex names. +If it is \code{auto}, that means \code{TRUE} if both graphs are named and \code{FALSE} otherwise. +A warning is generated if \code{auto} and one graph, but not both graphs are named.} \item{...}{Ignored, included for S3 compatibility.} } @@ -29,19 +28,17 @@ A new graph object. The difference of two graphs are created. } \details{ -\code{difference()} creates the difference of two graphs. Only edges -present in the first graph but not in the second will be be included in the -new graph. The corresponding operator is \verb{\%m\%}. +\code{difference()} creates the difference of two graphs. +Only edges present in the first graph but not in the second will be be included in the new graph. +The corresponding operator is \verb{\%m\%}. -If the \code{byname} argument is \code{TRUE} (or \code{auto} and the graphs -are all named), then the operation is performed based on symbolic vertex -names. Otherwise numeric vertex IDs are used. +If the \code{byname} argument is \code{TRUE} (or \code{auto} and the graphs are all named), +then the operation is performed based on symbolic vertex names. +Otherwise numeric vertex IDs are used. -\code{difference()} keeps all attributes (graph, vertex and edge) of the -first graph. +\code{difference()} keeps all attributes (graph, vertex and edge) of the first graph. -Note that \code{big} and \code{small} must both be directed or both be -undirected, otherwise an error message is given. +Note that \code{big} and \code{small} must both be directed or both be undirected, otherwise an error message is given. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Operators.html#igraph_difference}{\code{difference()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Isomorphism.html#igraph_permute_vertices}{\code{permute_vertices()}} diff --git a/man/difference.igraph.es.Rd b/man/difference.igraph.es.Rd index 3323c0f297a..bbab43de8a2 100644 --- a/man/difference.igraph.es.Rd +++ b/man/difference.igraph.es.Rd @@ -14,16 +14,14 @@ \item{...}{Ignored, included for S3 signature compatibility.} } \value{ -An edge sequence that contains only edges that are part of -\code{big}, but not part of \code{small}. +An edge sequence that contains only edges that are part of \code{big}, but not part of \code{small}. } \description{ Difference of edge sequences } \details{ -They must belong to the same graph. Note that this function has -\sQuote{set} semantics and the multiplicity of edges is lost in the -result. +They must belong to the same graph. +Note that this function has \sQuote{set} semantics and the multiplicity of edges is lost in the result. } \examples{ g <- make_(ring(10), with_vertex_(name = LETTERS[1:10])) diff --git a/man/difference.igraph.vs.Rd b/man/difference.igraph.vs.Rd index 6747b1131c6..9372a0f8ab0 100644 --- a/man/difference.igraph.vs.Rd +++ b/man/difference.igraph.vs.Rd @@ -14,16 +14,14 @@ \item{...}{Ignored, included for S3 signature compatibility.} } \value{ -A vertex sequence that contains only vertices that are part of -\code{big}, but not part of \code{small}. +A vertex sequence that contains only vertices that are part of \code{big}, but not part of \code{small}. } \description{ Difference of vertex sequences } \details{ -They must belong to the same graph. Note that this function has -\sQuote{set} semantics and the multiplicity of vertices is lost in the -result. +They must belong to the same graph. +Note that this function has \sQuote{set} semantics and the multiplicity of vertices is lost in the result. } \examples{ g <- make_(ring(10), with_vertex_(name = LETTERS[1:10])) diff --git a/man/dim_select.Rd b/man/dim_select.Rd index fdffd8f1c0b..86175f0dbf7 100644 --- a/man/dim_select.Rd +++ b/man/dim_select.Rd @@ -13,25 +13,20 @@ dim_select(sv) A numeric scalar, the estimate of \eqn{d}. } \description{ -Select the number of significant singular values, by finding the -\sQuote{elbow} of the scree plot, in a principled way. +Select the number of significant singular values, by finding the \sQuote{elbow} of the scree plot, in a principled way. } \details{ -The input of the function is a numeric vector which contains the measure of -\sQuote{importance} for each dimension. +The input of the function is a numeric vector which contains the measure of \sQuote{importance} for each dimension. -For spectral embedding, these are the singular values of the adjacency -matrix. The singular values are assumed to be generated from a Gaussian -mixture distribution with two components that have different means and same -variance. The dimensionality \eqn{d} is chosen to maximize the likelihood -when the \eqn{d} largest singular values are assigned to one component of -the mixture and the rest of the singular values assigned to the other -component. +For spectral embedding, these are the singular values of the adjacency matrix. +The singular values are assumed to be generated from a Gaussian mixture distribution with two components that have different means and same variance. +The dimensionality \eqn{d} is chosen to maximize the likelihood +when the \eqn{d} largest singular values are assigned to one component of the mixture and the rest of the singular values assigned to the other component. -This function can also be used for the general separation problem, where we -assume that the left and the right of the vector are coming from two Normal -distributions, with different means, and we want to know their border. See -examples below. +This function can also be used for the general separation problem, +where we assume that the left and the right of the vector are coming from two Normal distributions, with different means, +and we want to know their border. +See examples below. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Embedding.html#igraph_dim_select}{\code{dim_select()}} diff --git a/man/disjoint_union.Rd b/man/disjoint_union.Rd index c0ae54327cf..03b5f2b3b3d 100644 --- a/man/disjoint_union.Rd +++ b/man/disjoint_union.Rd @@ -13,10 +13,9 @@ x \%du\% y \item{\dots}{Graph objects or lists of graph objects.} \item{graph.attr.comb}{Specification for combining shared graph attributes. -The default \code{NULL} uses the \code{graph.attr.comb} 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.} +The default \code{NULL} uses the \code{graph.attr.comb} 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.} \item{x, y}{Graph objects.} } @@ -24,30 +23,26 @@ names. See \link{igraph-attribute-combination} for the available combiners.} A new graph object. } \description{ -The union of two or more graphs are created. The graphs are assumed to have -disjoint vertex sets. +The union of two or more graphs are created. +The graphs are assumed to have disjoint vertex sets. } \details{ \code{disjoint_union()} creates a union of two or more disjoint graphs. -Thus first the vertices in the second, third, etc. graphs are relabeled to -have completely disjoint graphs. Then a simple union is created. This -function can also be used via the \verb{\%du\%} operator. +Thus first the vertices in the second, third, etc. graphs are relabeled to have completely disjoint graphs. +Then a simple union is created. +This function can also be used via the \verb{\%du\%} operator. -\code{disjoint_union()} handles graph, vertex and edge attributes. In -particular, it merges vertex and edge attributes using the \code{\link[vctrs:vec_c]{vctrs::vec_c()}} -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 -suffixes (\verb{_1}, \verb{_2}, ...). See \link{igraph-attribute-combination} for the -available combiners. +\code{disjoint_union()} handles graph, vertex and edge attributes. +In particular, it merges vertex and edge attributes using the \code{\link[vctrs:vec_c]{vctrs::vec_c()}} 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 suffixes (\verb{_1}, \verb{_2}, ...). +See \link{igraph-attribute-combination} for the available combiners. -Note that if both graphs have vertex names (i.e. a \code{name} vertex -attribute), then the concatenated vertex names might be non-unique in the -result. A warning is given if this happens. +Note that if both graphs have vertex names (i.e. a \code{name} vertex attribute), +then the concatenated vertex names might be non-unique in the result. +A warning is given if this happens. -An error is generated if some input graphs are directed and others are -undirected. +An error is generated if some input graphs are directed and others are undirected. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/distances.Rd b/man/distances.Rd index 2e84b17143a..18f22d7ee22 100644 --- a/man/distances.Rd +++ b/man/distances.Rd @@ -60,95 +60,77 @@ all_shortest_paths( \item{directed}{Whether to consider directed paths in directed graphs, this argument is ignored for undirected graphs.} -\item{weights}{Possibly a numeric vector giving edge weights. If this is -\code{NULL} and the graph has a \code{weight} edge attribute, then the -attribute is used. If this is \code{NA} then no weights are used (even if -the graph has a \code{weight} attribute). In a weighted graph, the length -of a path is the sum of the weights of its constituent edges.} +\item{weights}{Possibly a numeric vector giving edge weights. +If this is \code{NULL} and the graph has a \code{weight} edge attribute, then the attribute is used. +If this is \code{NA} then no weights are used (even if the graph has a \code{weight} attribute). +In a weighted graph, the length of a path is the sum of the weights of its constituent edges.} -\item{unconnected}{What to do if the graph is unconnected (not -strongly connected if directed paths are considered). If TRUE, only -the lengths of the existing paths are considered and averaged; if -FALSE, the length of the missing paths are considered as having infinite -length, making the mean distance infinite as well.} +\item{unconnected}{What to do if the graph is unconnected (not strongly connected if directed paths are considered). +If TRUE, only the lengths of the existing paths are considered and averaged; if FALSE, +the length of the missing paths are considered as having infinite length, making the mean distance infinite as well.} \item{details}{Whether to provide additional details in the result. -Functions accepting this argument (like \code{mean_distance()}) return -additional information like the number of disconnected vertex pairs in -the result when this parameter is set to \code{TRUE}.} +Functions accepting this argument (like \code{mean_distance()}) return additional information like the number of disconnected vertex pairs in the result +when this parameter is set to \code{TRUE}.} -\item{v}{Numeric vector, the vertices from which the shortest paths will be -calculated. The default \code{NULL} selects all vertices.} +\item{v}{Numeric vector, the vertices from which the shortest paths will be calculated. +The default \code{NULL} selects all vertices.} -\item{to}{Numeric vector, the vertices to which the shortest paths will be -calculated. The default \code{NULL} includes all vertices. Note that for -\code{distances()} every vertex must be included here at most once. (This -is not required for \code{shortest_paths()}.} +\item{to}{Numeric vector, the vertices to which the shortest paths will be calculated. +The default \code{NULL} includes all vertices. +Note that for \code{distances()} every vertex must be included here at most once. +(This is not required for \code{shortest_paths()}.} -\item{mode}{Character constant, gives whether the shortest paths to or from -the given vertices should be calculated for directed graphs. If \code{out} -then the shortest paths \emph{from} the vertex, if \verb{in} then \emph{to} -it will be considered. If \code{all}, the default, then the graph is treated -as undirected, i.e. edge directions are not taken into account. This -argument is ignored for undirected graphs.} +\item{mode}{Character constant, +gives whether the shortest paths to or from the given vertices should be calculated for directed graphs. +If \code{out} then the shortest paths \emph{from} the vertex, if \verb{in} then \emph{to} it will be considered. +If \code{all}, the default, then the graph is treated as undirected, i.e. edge directions are not taken into account. +This argument is ignored for undirected graphs.} -\item{algorithm}{Which algorithm to use for the calculation. By default -igraph tries to select the fastest suitable algorithm. If there are no -weights, then an unweighted breadth-first search is used, otherwise if all -weights are positive, then Dijkstra's algorithm is used. If there are -negative weights and we do the calculation for more than 100 sources, then -Johnson's algorithm is used. Otherwise the Bellman-Ford algorithm is used. -You can override igraph's choice by explicitly giving this parameter. Note -that the igraph C core might still override your choice in obvious cases, -i.e. if there are no edge weights, then the unweighted algorithm will be -used, regardless of this argument.} +\item{algorithm}{Which algorithm to use for the calculation. +By default igraph tries to select the fastest suitable algorithm. +If there are no weights, then an unweighted breadth-first search is used, otherwise if all weights are positive, +then Dijkstra's algorithm is used. +If there are negative weights and we do the calculation for more than 100 sources, then Johnson's algorithm is used. +Otherwise the Bellman-Ford algorithm is used. +You can override igraph's choice by explicitly giving this parameter. +Note that the igraph C core might still override your choice in obvious cases, i.e. if there are no edge weights, +then the unweighted algorithm will be used, regardless of this argument.} -\item{from}{Numeric constant, the vertex from or to the shortest paths will -be calculated. Note that right now this is not a vector of vertex IDs, but -only a single vertex.} +\item{from}{Numeric constant, the vertex from or to the shortest paths will be calculated. +Note that right now this is not a vector of vertex IDs, but only a single vertex.} \item{output}{Character scalar, defines how to report the shortest paths. -\dQuote{vpath} means that the vertices along the paths are reported, this -form was used prior to igraph version 0.6. \dQuote{epath} means that the -edges along the paths are reported. \dQuote{both} means that both forms are -returned, in a named list with components \dQuote{vpath} and \dQuote{epath}.} +\dQuote{vpath} means that the vertices along the paths are reported, +this form was used prior to igraph version 0.6. \dQuote{epath} means that the edges along the paths are reported. +\dQuote{both} means that both forms are returned, in a named list with components \dQuote{vpath} and \dQuote{epath}.} -\item{predecessors}{Logical, whether to return the predecessor vertex -for each vertex. The predecessor of vertex \code{i} in the tree is the -vertex from which vertex \code{i} was reached. The predecessor of the start -vertex (in the \code{from} argument) is itself by definition. If the -predecessor is zero, it means that the given vertex was not reached from the -source during the search. Note that the search terminates if all the -vertices in \code{to} are reached.} +\item{predecessors}{Logical, whether to return the predecessor vertex for each vertex. +The predecessor of vertex \code{i} in the tree is the vertex from which vertex \code{i} was reached. +The predecessor of the start vertex (in the \code{from} argument) is itself by definition. +If the predecessor is zero, it means that the given vertex was not reached from the source during the search. +Note that the search terminates if all the vertices in \code{to} are reached.} -\item{inbound.edges}{Logical, whether to return the inbound edge for -each vertex. The inbound edge of vertex \code{i} in the tree is the edge via -which vertex \code{i} was reached. The start vertex and vertices that were -not reached during the search will have zero in the corresponding entry of -the vector. Note that the search terminates if all the vertices in \code{to} -are reached.} +\item{inbound.edges}{Logical, whether to return the inbound edge for each vertex. +The inbound edge of vertex \code{i} in the tree is the edge via which vertex \code{i} was reached. +The start vertex and vertices that were not reached during the search will have zero in the corresponding entry of the vector. +Note that the search terminates if all the vertices in \code{to} are reached.} } \value{ -For \code{distances()} a numeric matrix with \code{length(to)} -columns and \code{length(v)} rows. The shortest path length from a vertex to -itself is always zero. For unreachable vertices \code{Inf} is included. +For \code{distances()} a numeric matrix with \code{length(to)} columns and \code{length(v)} rows. +The shortest path length from a vertex to itself is always zero. +For unreachable vertices \code{Inf} is included. For \code{shortest_paths()} a named list with four entries is returned: \item{vpath}{This itself is a list, of length \code{length(to)}; list -element \code{i} contains the vertex IDs on the path from vertex \code{from} -to vertex \code{to[i]} (or the other way for directed graphs depending on -the \code{mode} argument). The vector also contains \code{from} and \code{i} -as the first and last elements. If \code{from} is the same as \code{i} then -it is only included once. If there is no path between two vertices then a -numeric vector of length zero is returned as the list element. If this -output is not requested in the \code{output} argument, then it will be -\code{NULL}.} \item{epath}{This is a list similar to \code{vpath}, but the -vectors of the list contain the edge IDs along the shortest paths, instead -of the vertex IDs. This entry is set to \code{NULL} if it is not requested -in the \code{output} argument.} \item{predecessors}{Numeric vector, the -predecessor of each vertex in the \code{to} argument, or \code{NULL} if it -was not requested.} \item{inbound_edges}{Numeric vector, the inbound edge -for each vertex, or \code{NULL}, if it was not requested.} +element \code{i} contains the vertex IDs on the path from vertex \code{from} to vertex \code{to[i]} (or the other way for directed graphs depending on the \code{mode} argument). +The vector also contains \code{from} and \code{i} as the first and last elements. +If \code{from} is the same as \code{i} then it is only included once. +If there is no path between two vertices then a numeric vector of length zero is returned as the list element. +If this output is not requested in the \code{output} argument, then it will be \code{NULL}.} +\item{epath}{This is a list similar to \code{vpath}, but the vectors of the list contain the edge IDs along the shortest paths, instead of the vertex IDs. This entry is set to \code{NULL} if it is not requested in the \code{output} argument.} +\item{predecessors}{Numeric vector, the predecessor of each vertex in the \code{to} argument, or \code{NULL} if it was not requested.} +\item{inbound_edges}{Numeric vector, the inbound edge for each vertex, or \code{NULL}, if it was not requested.} For \code{all_shortest_paths()} a list is returned: \describe{ @@ -195,63 +177,47 @@ and \eqn{n(n-1)/2} for undirected graphs. } } \description{ -\code{distances()} calculates the length of all the shortest paths from -or to the vertices in the network. \code{shortest_paths()} calculates one -shortest path (the path itself, and not just its length) from or to the -given vertex. +\code{distances()} calculates the length of all the shortest paths from or to the vertices in the network. +\code{shortest_paths()} calculates one shortest path (the path itself, and not just its length) from or to the given vertex. } \details{ -The shortest path, or geodesic between two pair of vertices is a path with -the minimal number of vertices. The functions documented in this manual page -all calculate shortest paths between vertex pairs. +The shortest path, or geodesic between two pair of vertices is a path with the minimal number of vertices. +The functions documented in this manual page all calculate shortest paths between vertex pairs. -\code{distances()} calculates the lengths of pairwise shortest paths from -a set of vertices (\code{from}) to another set of vertices (\code{to}). It -uses different algorithms, depending on the \code{algorithm} argument and -the \code{weight} edge attribute of the graph. The implemented algorithms -are breadth-first search (\sQuote{\code{unweighted}}), this only works for -unweighted graphs; the Dijkstra algorithm (\sQuote{\code{dijkstra}}), this -works for graphs with non-negative edge weights; the Bellman-Ford algorithm -(\sQuote{\code{bellman-ford}}); Johnson's algorithm -(\sQuote{\code{johnson}}); and a faster version of the Floyd-Warshall algorithm -with expected quadratic running time (\sQuote{\code{floyd-warshall}}). The latter -three algorithms work with arbitrary -edge weights, but (naturally) only for graphs that don't have a negative -cycle. Note that a negative-weight edge in an undirected graph implies -such a cycle. Johnson's algorithm performs better than the Bellman-Ford -one when many source (and target) vertices are given, with all-pairs -shortest path length calculations being the typical use case. +\code{distances()} calculates the lengths of pairwise shortest paths from a set of vertices (\code{from}) to another set of vertices (\code{to}). +It uses different algorithms, depending on the \code{algorithm} argument and the \code{weight} edge attribute of the graph. +The implemented algorithms are breadth-first search (\sQuote{\code{unweighted}}), this only works for unweighted graphs; +the Dijkstra algorithm (\sQuote{\code{dijkstra}}), this works for graphs with non-negative edge weights; +the Bellman-Ford algorithm (\sQuote{\code{bellman-ford}}); Johnson's algorithm (\sQuote{\code{johnson}}); +and a faster version of the Floyd-Warshall algorithm with expected quadratic running time (\sQuote{\code{floyd-warshall}}). +The latter three algorithms work with arbitrary edge weights, but (naturally) only for graphs that don't have a negative cycle. +Note that a negative-weight edge in an undirected graph implies such a cycle. +Johnson's algorithm performs better than the Bellman-Ford one when many source (and target) vertices are given, +with all-pairs shortest path length calculations being the typical use case. -igraph can choose automatically between algorithms, and chooses the most -efficient one that is appropriate for the supplied weights (if any). For -automatic algorithm selection, supply \sQuote{\code{automatic}} as the -\code{algorithm} argument. (This is also the default.) +igraph can choose automatically between algorithms, +and chooses the most efficient one that is appropriate for the supplied weights (if any). +For automatic algorithm selection, supply \sQuote{\code{automatic}} as the \code{algorithm} argument. +(This is also the default.) -\code{shortest_paths()} calculates a single shortest path (i.e. the path -itself, not just its length) between the source vertex given in \code{from}, -to the target vertices given in \code{to}. \code{shortest_paths()} uses -breadth-first search for unweighted graphs and Dijkstra's algorithm for -weighted graphs. The latter only works if the edge weights are non-negative. +\code{shortest_paths()} calculates a single shortest path (i.e. the path itself, not just its length) between the source vertex given in \code{from}, +to the target vertices given in \code{to}. +\code{shortest_paths()} uses breadth-first search for unweighted graphs and Dijkstra's algorithm for weighted graphs. +The latter only works if the edge weights are non-negative. -\code{all_shortest_paths()} calculates \emph{all} shortest paths between -pairs of vertices, including several shortest paths of the same length. -More precisely, it computerd all shortest path starting at \code{from}, and -ending at any vertex given in \code{to}. It uses a breadth-first search for -unweighted graphs and Dijkstra's algorithm for weighted ones. The latter -only supports non-negative edge weights. Caution: in multigraphs, the -result size is exponentially large in the number of vertex pairs with -multiple edges between them. +\code{all_shortest_paths()} calculates \emph{all} shortest paths between pairs of vertices, including several shortest paths of the same length. +More precisely, it computerd all shortest path starting at \code{from}, and ending at any vertex given in \code{to}. +It uses a breadth-first search for unweighted graphs and Dijkstra's algorithm for weighted ones. +The latter only supports non-negative edge weights. +Caution: in multigraphs, the result size is exponentially large in the number of vertex pairs with multiple edges between them. -\code{mean_distance()} calculates the average path length in a graph, by -calculating the shortest paths between all pairs of vertices (both ways for -directed graphs). It uses a breadth-first search for unweighted graphs and -Dijkstra's algorithm for weighted ones. The latter only supports non-negative -edge weights. +\code{mean_distance()} calculates the average path length in a graph, +by calculating the shortest paths between all pairs of vertices (both ways for directed graphs). +It uses a breadth-first search for unweighted graphs and Dijkstra's algorithm for weighted ones. +The latter only supports non-negative edge weights. -\code{distance_table()} calculates a histogram, by calculating the shortest -path length between each pair of vertices. For directed graphs both -directions are considered, so every pair of vertices appears twice in the -histogram. +\code{distance_table()} calculates a histogram, by calculating the shortest path length between each pair of vertices. +For directed graphs both directions are considered, so every pair of vertices appears twice in the histogram. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_path_length_hist}{\code{path_length_hist()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_average_path_length_dijkstra}{\code{average_path_length_dijkstra()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_is_directed}{\code{is_directed()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_all_shortest_paths_dijkstra}{\code{get_all_shortest_paths_dijkstra()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_all_shortest_paths}{\code{get_all_shortest_paths()}} diff --git a/man/diverging_pal.Rd b/man/diverging_pal.Rd index e0693488832..751b2579dc1 100644 --- a/man/diverging_pal.Rd +++ b/man/diverging_pal.Rd @@ -7,8 +7,8 @@ diverging_pal(n) } \arguments{ -\item{n}{The number of colors in the palette. The maximum is eleven -currently.} +\item{n}{The number of colors in the palette. +The maximum is eleven currently.} } \value{ A character vector of RGB color codes. @@ -18,10 +18,8 @@ This is the \sQuote{PuOr} palette from \url{https://colorbrewer2.org/}. It has at most eleven colors. } \details{ -This is similar to \code{\link[=sequential_pal]{sequential_pal()}}, but it also puts -emphasis on the mid-range values, plus the the two extreme ends. -Use this palette, if you have such a quantity to mark with vertex -colors. +This is similar to \code{\link[=sequential_pal]{sequential_pal()}}, but it also puts emphasis on the mid-range values, plus the the two extreme ends. +Use this palette, if you have such a quantity to mark with vertex colors. } \examples{ \dontshow{if (rlang::is_installed(c("igraphdata", "scales"))) withAutoprint(\{ # examplesIf} diff --git a/man/diversity.Rd b/man/diversity.Rd index 0fe5d21dfd4..975d6a0560b 100644 --- a/man/diversity.Rd +++ b/man/diversity.Rd @@ -7,13 +7,14 @@ diversity(graph, ..., weights = NULL, vids = NULL) } \arguments{ -\item{graph}{The input graph. Edge directions are ignored.} +\item{graph}{The input graph. +Edge directions are ignored.} \item{...}{These dots are for future extensions and must be empty.} -\item{weights}{\code{NULL}, or the vector of edge weights to use for the -computation. If \code{NULL}, then the \sQuote{weight} attibute is used. Note -that this measure is not defined for unweighted graphs.} +\item{weights}{\code{NULL}, or the vector of edge weights to use for the computation. +If \code{NULL}, then the \sQuote{weight} attibute is used. +Note that this measure is not defined for unweighted graphs.} \item{vids}{The vertex IDs for which to calculate the measure. The default \code{NULL} selects all vertices.} @@ -25,16 +26,14 @@ A numeric vector, its length is the number of vertices. Calculates a measure of diversity for all vertices. } \details{ -The diversity of a vertex is defined as the (scaled) Shannon entropy of the -weights of its incident edges: +The diversity of a vertex is defined as the (scaled) Shannon entropy of the weights of its incident edges: \deqn{D(i)=\frac{H(i)}{\log k_i}}{D(i)=H(i)/log(k[i])} and \deqn{H(i)=-\sum_{j=1}^{k_i} p_{ij}\log p_{ij},}{H(i) = -sum(p[i,j] log(p[i,j]), j=1..k[i]),} where \deqn{p_{ij}=\frac{w_{ij}}{\sum_{l=1}^{k_i}}V_{il},}{p[i,j] = w[i,j] / sum(w[i,l], l=1..k[i]),} and \eqn{k_i}{k[i]} is the (total) degree of vertex -\eqn{i}, \eqn{w_{ij}}{w[i,j]} is the weight of the edge(s) between vertices -\eqn{i} and \eqn{j}. +\eqn{i}, \eqn{w_{ij}}{w[i,j]} is the weight of the edge(s) between vertices \eqn{i} and \eqn{j}. For vertices with degree less than two the function returns \code{NaN}. } diff --git a/man/dominator.tree.Rd b/man/dominator.tree.Rd index 8cc9511fee5..8bb2842304f 100644 --- a/man/dominator.tree.Rd +++ b/man/dominator.tree.Rd @@ -7,22 +7,19 @@ dominator.tree(graph, root, mode = c("out", "in", "all", "total")) } \arguments{ -\item{graph}{A directed graph. If it is not a flowgraph, and it contains -some vertices not reachable from the root vertex, then these vertices will -be collected and returned as part of the result.} +\item{graph}{A directed graph. +If it is not a flowgraph, and it contains some vertices not reachable from the root vertex, +then these vertices will be collected and returned as part of the result.} -\item{root}{The ID of the root (or source) vertex, this will be the root of -the tree.} +\item{root}{The ID of the root (or source) vertex, this will be the root of the tree.} -\item{mode}{Constant, must be \sQuote{\verb{in}} or \sQuote{\code{out}}. If -it is \sQuote{\verb{in}}, then all directions are considered as opposite to -the original one in the input graph.} +\item{mode}{Constant, must be \sQuote{\verb{in}} or \sQuote{\code{out}}. +If it is \sQuote{\verb{in}}, then all directions are considered as opposite to the original one in the input graph.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{dominator.tree()} was renamed to \code{\link[=dominator_tree]{dominator_tree()}} to create a more -consistent API. +\code{dominator.tree()} was renamed to \code{\link[=dominator_tree]{dominator_tree()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Flows.html#igraph_dominator_tree}{\code{dominator_tree()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/dominator_tree.Rd b/man/dominator_tree.Rd index b974e8c27aa..dfef6654e63 100644 --- a/man/dominator_tree.Rd +++ b/man/dominator_tree.Rd @@ -7,18 +7,16 @@ dominator_tree(graph, root, ..., mode = c("out", "in", "all", "total")) } \arguments{ -\item{graph}{A directed graph. If it is not a flowgraph, and it contains -some vertices not reachable from the root vertex, then these vertices will -be collected and returned as part of the result.} +\item{graph}{A directed graph. +If it is not a flowgraph, and it contains some vertices not reachable from the root vertex, +then these vertices will be collected and returned as part of the result.} -\item{root}{The ID of the root (or source) vertex, this will be the root of -the tree.} +\item{root}{The ID of the root (or source) vertex, this will be the root of the tree.} \item{...}{These dots are for future extensions and must be empty.} -\item{mode}{Constant, must be \sQuote{\verb{in}} or \sQuote{\code{out}}. If -it is \sQuote{\verb{in}}, then all directions are considered as opposite to -the original one in the input graph.} +\item{mode}{Constant, must be \sQuote{\verb{in}} or \sQuote{\code{out}}. +If it is \sQuote{\verb{in}}, then all directions are considered as opposite to the original one in the input graph.} } \value{ A list with components: @@ -42,20 +40,17 @@ A numeric vector containing the vertex IDs that are unreachable from the root. Dominator tree of a directed graph. } \details{ -A flowgraph is a directed graph with a distinguished start (or root) vertex -\eqn{r}, such that for any vertex \eqn{v}, there is a path from \eqn{r} to -\eqn{v}. A vertex \eqn{v} dominates another vertex \eqn{w} (not equal to -\eqn{v}), if every path from \eqn{r} to \eqn{w} contains \eqn{v}. Vertex -\eqn{v} is the immediate dominator or \eqn{w}, -\eqn{v=\textrm{idom}(w)}{v=idom(w)}, if \eqn{v} dominates \eqn{w} and every -other dominator of \eqn{w} dominates \eqn{v}. The edges -\eqn{{(\textrm{idom}(w), w)| w \ne r}}{{(idom(w),w)| w is not r}} form a -directed tree, rooted at \eqn{r}, called the dominator tree of the graph. -Vertex \eqn{v} dominates vertex \eqn{w} if and only if \eqn{v} is an -ancestor of \eqn{w} in the dominator tree. +A flowgraph is a directed graph with a distinguished start (or root) vertex \eqn{r}, such that for any vertex \eqn{v}, +there is a path from \eqn{r} to \eqn{v}. +A vertex \eqn{v} dominates another vertex \eqn{w} (not equal to \eqn{v}), if every path from \eqn{r} to \eqn{w} contains \eqn{v}. +Vertex \eqn{v} is the immediate dominator or \eqn{w}, \eqn{v=\textrm{idom}(w)}{v=idom(w)}, +if \eqn{v} dominates \eqn{w} and every other dominator of \eqn{w} dominates \eqn{v}. +The edges \eqn{{(\textrm{idom}(w), w)| w \ne r}}{{(idom(w),w)| w is not r}} form a directed tree, rooted at \eqn{r}, +called the dominator tree of the graph. +Vertex \eqn{v} dominates vertex \eqn{w} if and only if \eqn{v} is an ancestor of \eqn{w} in the dominator tree. -This function implements the Lengauer-Tarjan algorithm to construct the -dominator tree of a directed graph. For details see the reference below. +This function implements the Lengauer-Tarjan algorithm to construct the dominator tree of a directed graph. +For details see the reference below. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Flows.html#igraph_dominator_tree}{\code{dominator_tree()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/dot-apply_modifiers.Rd b/man/dot-apply_modifiers.Rd index cea645df25a..e0aa16bbc92 100644 --- a/man/dot-apply_modifiers.Rd +++ b/man/dot-apply_modifiers.Rd @@ -15,8 +15,7 @@ The modified graph } \description{ -This is a helper function for the common parts of \code{make_()} and -\code{sample_()}. +This is a helper function for the common parts of \code{make_()} and \code{sample_()}. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Operators.html#igraph_simplify}{\code{simplify()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/dot-data.Rd b/man/dot-data.Rd index 896d79fb40c..703249061d8 100644 --- a/man/dot-data.Rd +++ b/man/dot-data.Rd @@ -7,24 +7,20 @@ \alias{.env} \title{\code{.data} and \code{.env} pronouns} \description{ -The \code{.data} and \code{.env} pronouns make it explicit where to look up attribute -names when indexing \code{V(g)} or \code{E(g)}, i.e. the vertex or edge sequence of a -graph. These pronouns are inspired by \code{.data} and \code{.env} in \code{rlang} - thanks -to Michał Bojanowski for bringing these to our attention. +The \code{.data} and \code{.env} pronouns make it explicit where to look up attribute names when indexing \code{V(g)} or \code{E(g)}, +i.e. the vertex or edge sequence of a graph. +These pronouns are inspired by \code{.data} and \code{.env} in \code{rlang} - thanks to Michał Bojanowski for bringing these to our attention. The rules are simple: \itemize{ -\item \code{.data} retrieves attributes from the graph whose vertex or edge sequence -is being evaluated. +\item \code{.data} retrieves attributes from the graph whose vertex or edge sequence is being evaluated. \item \code{.env} retrieves variables from the calling environment. } -Note that \code{.data} and \code{.env} are injected dynamically into the environment -where the indexing expressions are evaluated; you cannot get access to these -objects outside the context of an indexing expression. To avoid warnings -printed by \verb{R CMD check} when code containing \code{.data} and \code{.env} is checked, -you can import \code{.data} and \code{.env} from \code{igraph} if needed. Alternatively, -you can declare them explicitly with \code{utils::globalVariables()} to silence -the warnings. +Note that \code{.data} and \code{.env} are injected dynamically into the environment where the indexing expressions are evaluated; +you cannot get access to these objects outside the context of an indexing expression. +To avoid warnings printed by \verb{R CMD check} when code containing \code{.data} and \code{.env} is checked, +you can import \code{.data} and \code{.env} from \code{igraph} if needed. +Alternatively, you can declare them explicitly with \code{utils::globalVariables()} to silence the warnings. } \concept{env-and-data} diff --git a/man/dot-extract_constructor_and_modifiers.Rd b/man/dot-extract_constructor_and_modifiers.Rd index 9084e594bbf..eb81c1c970c 100644 --- a/man/dot-extract_constructor_and_modifiers.Rd +++ b/man/dot-extract_constructor_and_modifiers.Rd @@ -2,20 +2,17 @@ % Please edit documentation in R/make.R \name{.extract_constructor_and_modifiers} \alias{.extract_constructor_and_modifiers} -\title{Takes an argument list and extracts the constructor specification and -constructor modifiers from it.} +\title{Takes an argument list and extracts the constructor specification and constructor modifiers from it.} \usage{ .extract_constructor_and_modifiers(..., .operation, .variant) } \arguments{ \item{...}{Parameters to extract from} -\item{.operation}{Human-readable description of the operation that this -helper is a part of} +\item{.operation}{Human-readable description of the operation that this helper is a part of} -\item{.variant}{Constructor variant; must be one of \sQuote{make}, -\sQuote{graph} or \sQuote{sample}. Used in cases when the same constructor -specification has deterministic and random variants.} +\item{.variant}{Constructor variant; must be one of \sQuote{make}, \sQuote{graph} or \sQuote{sample}. +Used in cases when the same constructor specification has deterministic and random variants.} } \value{ A named list with three items: @@ -32,7 +29,6 @@ the remaining, unparsed arguments. } } \description{ -This is a helper function for the common parts of \code{make_()} and -\code{sample_()}. +This is a helper function for the common parts of \code{make_()} and \code{sample_()}. } \keyword{internal} diff --git a/man/dyad.census.Rd b/man/dyad.census.Rd index a176ca42486..a33d39d3264 100644 --- a/man/dyad.census.Rd +++ b/man/dyad.census.Rd @@ -7,13 +7,13 @@ dyad.census(graph) } \arguments{ -\item{graph}{The input graph. A warning is given if it is not directed.} +\item{graph}{The input graph. +A warning is given if it is not directed.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{dyad.census()} was renamed to \code{\link[=dyad_census]{dyad_census()}} to create a more -consistent API. +\code{dyad.census()} was renamed to \code{\link[=dyad_census]{dyad_census()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Motifs.html#igraph_dyad_census}{\code{dyad_census()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_is_directed}{\code{is_directed()}} diff --git a/man/dyad_census.Rd b/man/dyad_census.Rd index 99785fcee28..47e2590a5bb 100644 --- a/man/dyad_census.Rd +++ b/man/dyad_census.Rd @@ -7,7 +7,8 @@ dyad_census(graph) } \arguments{ -\item{graph}{The input graph. A warning is given if it is not directed.} +\item{graph}{The input graph. +A warning is given if it is not directed.} } \value{ A named numeric vector with three elements: @@ -24,9 +25,9 @@ The number of pairs with no connection between them. } } \description{ -Classify dyads in a directed graphs. The relationship between each pair of -vertices is measured. It can be in three states: mutual, asymmetric or -non-existent. +Classify dyads in a directed graphs. +The relationship between each pair of vertices is measured. +It can be in three states: mutual, asymmetric or non-existent. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Motifs.html#igraph_dyad_census}{\code{dyad_census()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_is_directed}{\code{is_directed()}} @@ -46,8 +47,7 @@ Wasserman, S., and Faust, K. \emph{Social Network Analysis: Methods and Applications.} Cambridge: Cambridge University Press. 1994. } \seealso{ -\code{\link[=triad_census]{triad_census()}} for the same classification, but with -triples. +\code{\link[=triad_census]{triad_census()}} for the same classification, but with triples. Other graph motifs: \code{\link[=count_motifs]{count_motifs()}}, diff --git a/man/each_edge.Rd b/man/each_edge.Rd index 4b1a3bcc7d1..783694fc147 100644 --- a/man/each_edge.Rd +++ b/man/each_edge.Rd @@ -17,21 +17,18 @@ each_edge( \item{...}{These dots are for future extensions and must be empty.} -\item{loops}{Logical, whether loop edges are allowed in the rewired -graph.} +\item{loops}{Logical, whether loop edges are allowed in the rewired graph.} -\item{multiple}{Logical, whether multiple edges are allowed in the -generated graph.} +\item{multiple}{Logical, whether multiple edges are allowed in the generated graph.} -\item{mode}{Character string, specifies which endpoint of the edges to rewire -in directed graphs. \sQuote{all} rewires both endpoints, \sQuote{in} rewires -the start (tail) of each directed edge, \sQuote{out} rewires the end (head) -of each directed edge. Ignored for undirected graphs.} +\item{mode}{Character string, specifies which endpoint of the edges to rewire in directed graphs. +\sQuote{all} rewires both endpoints, \sQuote{in} rewires the start (tail) of each directed edge, +\sQuote{out} rewires the end (head) of each directed edge. +Ignored for undirected graphs.} } \description{ This function can be used together with \code{\link[=rewire]{rewire()}}. -This method rewires the endpoints of the edges with a constant probability -uniformly randomly to a new vertex in a graph. +This method rewires the endpoints of the edges with a constant probability uniformly randomly to a new vertex in a graph. } \details{ Note that this method might create graphs with multiple and/or loop edges. diff --git a/man/eccentricity.Rd b/man/eccentricity.Rd index aded3cc2cf3..f20123cb7ab 100644 --- a/man/eccentricity.Rd +++ b/man/eccentricity.Rd @@ -19,31 +19,26 @@ eccentricity( \item{...}{These dots are for future extensions and must be empty.} -\item{weights}{Possibly a numeric vector giving edge weights. If this is -\code{NULL} and the graph has a \code{weight} edge attribute, then the -attribute is used. If this is \code{NA} then no weights are used (even if -the graph has a \code{weight} attribute). In a weighted graph, the length -of a path is the sum of the weights of its constituent edges.} +\item{weights}{Possibly a numeric vector giving edge weights. +If this is \code{NULL} and the graph has a \code{weight} edge attribute, then the attribute is used. +If this is \code{NA} then no weights are used (even if the graph has a \code{weight} attribute). +In a weighted graph, the length of a path is the sum of the weights of its constituent edges.} -\item{mode}{Character constant, gives whether the shortest paths to or from -the given vertices should be calculated for directed graphs. If \code{out} -then the shortest paths \emph{from} the vertex, if \verb{in} then \emph{to} -it will be considered. If \code{all}, the default, then the graph is treated -as undirected, i.e. edge directions are not taken into account. This -argument is ignored for undirected graphs.} +\item{mode}{Character constant, +gives whether the shortest paths to or from the given vertices should be calculated for directed graphs. +If \code{out} then the shortest paths \emph{from} the vertex, if \verb{in} then \emph{to} it will be considered. +If \code{all}, the default, then the graph is treated as undirected, i.e. edge directions are not taken into account. +This argument is ignored for undirected graphs.} } \value{ -\code{eccentricity()} returns a numeric vector, containing the -eccentricity score of each given vertex. +\code{eccentricity()} returns a numeric vector, containing the eccentricity score of each given vertex. } \description{ -The eccentricity of a vertex is its shortest path distance from the farthest -other node in the graph. +The eccentricity of a vertex is its shortest path distance from the farthest other node in the graph. } \details{ -The eccentricity of a vertex is calculated by measuring the shortest -distance from (or to) the vertex, to (or from) all vertices in the graph, -and taking the maximum. +The eccentricity of a vertex is calculated by measuring the shortest distance from (or to) the vertex, +to (or from) all vertices in the graph, and taking the maximum. This implementation ignores vertex pairs that are in different components. Isolate vertices have eccentricity zero. diff --git a/man/edge.Rd b/man/edge.Rd index 41ea5e5f37c..61e70a7a739 100644 --- a/man/edge.Rd +++ b/man/edge.Rd @@ -13,25 +13,19 @@ edges(...) \item{...}{See details below.} } \value{ -A special object that can be used with together with -igraph graphs and the plus and minus operators. +A special object that can be used with together with igraph graphs and the plus and minus operators. } \description{ -This is a helper function that simplifies adding and deleting -edges to/from graphs. +This is a helper function that simplifies adding and deleting edges to/from graphs. } \details{ \code{edges()} is an alias for \code{edge()}. -When adding edges via \code{+}, all unnamed arguments of -\code{edge()} (or \code{edges()}) are concatenated, and then passed to -\code{\link[=add_edges]{add_edges()}}. They are interpreted as pairs of vertex IDs, -and an edge will added between each pair. Named arguments will be -used as edge attributes for the new edges. +When adding edges via \code{+}, all unnamed arguments of \code{edge()} (or \code{edges()}) are concatenated, and then passed to \code{\link[=add_edges]{add_edges()}}. +They are interpreted as pairs of vertex IDs, and an edge will added between each pair. +Named arguments will be used as edge attributes for the new edges. -When deleting edges via \code{-}, all arguments of \code{edge()} (or -\code{edges()}) are concatenated via \code{c()} and passed to -\code{\link[=delete_edges]{delete_edges()}}. +When deleting edges via \code{-}, all arguments of \code{edge()} (or \code{edges()}) are concatenated via \code{c()} and passed to \code{\link[=delete_edges]{delete_edges()}}. } \examples{ g <- make_ring(10) \%>\% diff --git a/man/edge.betweenness.Rd b/man/edge.betweenness.Rd index a98737cf183..598f97db794 100644 --- a/man/edge.betweenness.Rd +++ b/man/edge.betweenness.Rd @@ -18,22 +18,19 @@ edge.betweenness( \item{e}{The edges for which the edge betweenness will be calculated. The default \code{NULL} selects all edges.} -\item{directed}{Logical, whether directed paths should be considered while -determining the shortest paths.} +\item{directed}{Logical, whether directed paths should be considered while determining the shortest paths.} -\item{weights}{Optional positive weight vector for calculating weighted -betweenness. If the graph has a \code{weight} edge attribute, then this is -used by default. Weights are used to calculate weighted shortest paths, -so they are interpreted as distances.} +\item{weights}{Optional positive weight vector for calculating weighted betweenness. +If the graph has a \code{weight} edge attribute, then this is used by default. +Weights are used to calculate weighted shortest paths, so they are interpreted as distances.} -\item{cutoff}{The maximum shortest path length to consider when calculating -betweenness. If negative, then there is no such limit.} +\item{cutoff}{The maximum shortest path length to consider when calculating betweenness. +If negative, then there is no such limit.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{edge.betweenness()} was renamed to \code{\link[=edge_betweenness]{edge_betweenness()}} to create a more -consistent API. +\code{edge.betweenness()} was renamed to \code{\link[=edge_betweenness]{edge_betweenness()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_edge_betweenness_cutoff}{\code{edge_betweenness_cutoff()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/edge.betweenness.community.Rd b/man/edge.betweenness.community.Rd index 6115b9ee9ed..8c0b324729d 100644 --- a/man/edge.betweenness.community.Rd +++ b/man/edge.betweenness.community.Rd @@ -18,49 +18,41 @@ edge.betweenness.community( \arguments{ \item{graph}{The graph to analyze.} -\item{weights}{The weights of the edges. It must be a positive numeric vector, -\code{NULL} or \code{NA}. If it is \code{NULL} and the input graph has a -\sQuote{weight} edge attribute, then that attribute will be used. If -\code{NULL} and no such attribute is present, then the edges will have equal -weights. Set this to \code{NA} if the graph was a \sQuote{weight} edge -attribute, but you don't want to use it for community detection. Edge weights -are used to calculate weighted edge betweenness. This means that edges are -interpreted as distances, not as connection strengths.} - -\item{directed}{Logical, whether to calculate directed edge -betweenness for directed graphs. It is ignored for undirected graphs.} - -\item{edge.betweenness}{Logical, whether to return the edge -betweenness of the edges at the time of their removal.} - -\item{merges}{Logical, whether to return the merge matrix -representing the hierarchical community structure of the network. This -argument is called \code{merges}, even if the community structure algorithm -itself is divisive and not agglomerative: it builds the tree from top to -bottom. There is one line for each merge (i.e. split) in matrix, the first -line is the first merge (last split). The communities are identified by -integer number starting from one. Community IDs smaller than or equal to -\eqn{N}, the number of vertices in the graph, belong to singleton -communities, i.e. individual vertices. Before the first merge we have \eqn{N} -communities numbered from one to \eqn{N}. The first merge, the first line of -the matrix creates community \eqn{N+1}, the second merge creates community -\eqn{N+2}, etc.} - -\item{bridges}{Logical, whether to return a list the edge removals -which actually splitted a component of the graph.} - -\item{modularity}{Logical, whether to calculate the maximum -modularity score, considering all possibly community structures along the -edge-betweenness based edge removals.} - -\item{membership}{Logical, whether to calculate the membership -vector corresponding to the highest possible modularity score.} +\item{weights}{The weights of the edges. +It must be a positive numeric vector, \code{NULL} or \code{NA}. +If it is \code{NULL} and the input graph has a \sQuote{weight} edge attribute, then that attribute will be used. +If \code{NULL} and no such attribute is present, then the edges will have equal weights. +Set this to \code{NA} if the graph was a \sQuote{weight} edge attribute, but you don't want to use it for community detection. +Edge weights are used to calculate weighted edge betweenness. +This means that edges are interpreted as distances, not as connection strengths.} + +\item{directed}{Logical, whether to calculate directed edge betweenness for directed graphs. +It is ignored for undirected graphs.} + +\item{edge.betweenness}{Logical, whether to return the edge betweenness of the edges at the time of their removal.} + +\item{merges}{Logical, +whether to return the merge matrix representing the hierarchical community structure of the network. +This argument is called \code{merges}, even if the community structure algorithm itself is divisive and not agglomerative: +it builds the tree from top to bottom. +There is one line for each merge (i.e. split) in matrix, the first line is the first merge (last split). +The communities are identified by integer number starting from one. +Community IDs smaller than or equal to \eqn{N}, the number of vertices in the graph, belong to singleton communities, +i.e. individual vertices. +Before the first merge we have \eqn{N} communities numbered from one to \eqn{N}. +The first merge, the first line of the matrix creates community \eqn{N+1}, the second merge creates community \eqn{N+2}, etc.} + +\item{bridges}{Logical, whether to return a list the edge removals which actually splitted a component of the graph.} + +\item{modularity}{Logical, whether to calculate the maximum modularity score, +considering all possibly community structures along the edge-betweenness based edge removals.} + +\item{membership}{Logical, whether to calculate the membership vector corresponding to the highest possible modularity score.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{edge.betweenness.community()} was renamed to \code{\link[=cluster_edge_betweenness]{cluster_edge_betweenness()}} to create a more -consistent API. +\code{edge.betweenness.community()} was renamed to \code{\link[=cluster_edge_betweenness]{cluster_edge_betweenness()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/edge.connectivity.Rd b/man/edge.connectivity.Rd index 5074e4b76f2..c6bf7c081ed 100644 --- a/man/edge.connectivity.Rd +++ b/man/edge.connectivity.Rd @@ -9,25 +9,21 @@ edge.connectivity(graph, source = NULL, target = NULL, checks = TRUE) \arguments{ \item{graph}{The input graph.} -\item{source}{The ID of the source vertex, for \code{edge_connectivity()} it -can be \code{NULL}, see details below.} +\item{source}{The ID of the source vertex, for \code{edge_connectivity()} it can be \code{NULL}, see details below.} -\item{target}{The ID of the target vertex, for \code{edge_connectivity()} it -can be \code{NULL}, see details below.} +\item{target}{The ID of the target vertex, for \code{edge_connectivity()} it can be \code{NULL}, see details below.} -\item{checks}{Logical. Whether to check that the graph is connected -and also the degree of the vertices. If the graph is not (strongly) -connected then the connectivity is obviously zero. Otherwise if the minimum -degree is one then the edge connectivity is also one. It is a good idea to -perform these checks, as they can be done quickly compared to the -connectivity calculation itself. They were suggested by Peter McMahan, -thanks Peter.} +\item{checks}{Logical. +Whether to check that the graph is connected and also the degree of the vertices. +If the graph is not (strongly) connected then the connectivity is obviously zero. +Otherwise if the minimum degree is one then the edge connectivity is also one. +It is a good idea to perform these checks, as they can be done quickly compared to the connectivity calculation itself. +They were suggested by Peter McMahan, thanks Peter.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{edge.connectivity()} was renamed to \code{\link[=edge_connectivity]{edge_connectivity()}} to create a more -consistent API. +\code{edge.connectivity()} was renamed to \code{\link[=edge_connectivity]{edge_connectivity()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Flows.html#igraph_edge_connectivity}{\code{edge_connectivity()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Flows.html#igraph_st_edge_connectivity}{\code{st_edge_connectivity()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/edge.disjoint.paths.Rd b/man/edge.disjoint.paths.Rd index 4cb344b96be..3a54a146388 100644 --- a/man/edge.disjoint.paths.Rd +++ b/man/edge.disjoint.paths.Rd @@ -9,25 +9,21 @@ edge.disjoint.paths(graph, source = NULL, target = NULL, checks = TRUE) \arguments{ \item{graph}{The input graph.} -\item{source}{The ID of the source vertex, for \code{edge_connectivity()} it -can be \code{NULL}, see details below.} +\item{source}{The ID of the source vertex, for \code{edge_connectivity()} it can be \code{NULL}, see details below.} -\item{target}{The ID of the target vertex, for \code{edge_connectivity()} it -can be \code{NULL}, see details below.} +\item{target}{The ID of the target vertex, for \code{edge_connectivity()} it can be \code{NULL}, see details below.} -\item{checks}{Logical. Whether to check that the graph is connected -and also the degree of the vertices. If the graph is not (strongly) -connected then the connectivity is obviously zero. Otherwise if the minimum -degree is one then the edge connectivity is also one. It is a good idea to -perform these checks, as they can be done quickly compared to the -connectivity calculation itself. They were suggested by Peter McMahan, -thanks Peter.} +\item{checks}{Logical. +Whether to check that the graph is connected and also the degree of the vertices. +If the graph is not (strongly) connected then the connectivity is obviously zero. +Otherwise if the minimum degree is one then the edge connectivity is also one. +It is a good idea to perform these checks, as they can be done quickly compared to the connectivity calculation itself. +They were suggested by Peter McMahan, thanks Peter.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{edge.disjoint.paths()} was renamed to \code{\link[=edge_connectivity]{edge_connectivity()}} to create a more -consistent API. +\code{edge.disjoint.paths()} was renamed to \code{\link[=edge_connectivity]{edge_connectivity()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Flows.html#igraph_edge_connectivity}{\code{edge_connectivity()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Flows.html#igraph_st_edge_connectivity}{\code{st_edge_connectivity()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/edge_attr-set.Rd b/man/edge_attr-set.Rd index e25638f33e1..a713e9511e0 100644 --- a/man/edge_attr-set.Rd +++ b/man/edge_attr-set.Rd @@ -10,15 +10,13 @@ edge_attr(graph, name, index = NULL) <- value \arguments{ \item{graph}{The graph.} -\item{name}{The name of the edge attribute to set. If missing, -then \code{value} must be a named list, and its entries are -set as edge attributes.} +\item{name}{The name of the edge attribute to set. +If missing, then \code{value} must be a named list, and its entries are set as edge attributes.} -\item{index}{An optional edge sequence to set the attributes -of a subset of edges. The default \code{NULL} selects all edges.} +\item{index}{An optional edge sequence to set the attributes of a subset of edges. +The default \code{NULL} selects all edges.} -\item{value}{The new value of the attribute(s) for all -(or \code{index}) edges.} +\item{value}{The new value of the attribute(s) for all (or \code{index}) edges.} } \value{ The graph, with the edge attribute(s) added or set. diff --git a/man/edge_attr.Rd b/man/edge_attr.Rd index d1a412dc8db..d01cba4493e 100644 --- a/man/edge_attr.Rd +++ b/man/edge_attr.Rd @@ -10,15 +10,14 @@ edge_attr(graph, name, index = NULL) \arguments{ \item{graph}{The graph} -\item{name}{The name of the attribute to query. If missing, then -all edge attributes are returned in a list.} +\item{name}{The name of the attribute to query. +If missing, then all edge attributes are returned in a list.} -\item{index}{An optional edge sequence to query edge attributes -for a subset of edges. The default \code{NULL} selects all edges.} +\item{index}{An optional edge sequence to query edge attributes for a subset of edges. +The default \code{NULL} selects all edges.} } \value{ -The value of the edge attribute, or the list of all -edge attributes if \code{name} is missing. +The value of the edge attribute, or the list of all edge attributes if \code{name} is missing. } \description{ Query edge attributes of a graph diff --git a/man/edge_connectivity.Rd b/man/edge_connectivity.Rd index d29daa1cb41..5e7854d8169 100644 --- a/man/edge_connectivity.Rd +++ b/man/edge_connectivity.Rd @@ -15,72 +15,58 @@ adhesion(graph, ..., checks = TRUE) \arguments{ \item{graph}{The input graph.} -\item{source}{The ID of the source vertex, for \code{edge_connectivity()} it -can be \code{NULL}, see details below.} +\item{source}{The ID of the source vertex, for \code{edge_connectivity()} it can be \code{NULL}, see details below.} -\item{target}{The ID of the target vertex, for \code{edge_connectivity()} it -can be \code{NULL}, see details below.} +\item{target}{The ID of the target vertex, for \code{edge_connectivity()} it can be \code{NULL}, see details below.} \item{...}{These dots are for future extensions and must be empty.} -\item{checks}{Logical. Whether to check that the graph is connected -and also the degree of the vertices. If the graph is not (strongly) -connected then the connectivity is obviously zero. Otherwise if the minimum -degree is one then the edge connectivity is also one. It is a good idea to -perform these checks, as they can be done quickly compared to the -connectivity calculation itself. They were suggested by Peter McMahan, -thanks Peter.} +\item{checks}{Logical. +Whether to check that the graph is connected and also the degree of the vertices. +If the graph is not (strongly) connected then the connectivity is obviously zero. +Otherwise if the minimum degree is one then the edge connectivity is also one. +It is a good idea to perform these checks, as they can be done quickly compared to the connectivity calculation itself. +They were suggested by Peter McMahan, thanks Peter.} } \value{ A scalar real value. } \description{ -The edge connectivity of a graph or two vertices, this is recently also -called group adhesion. +The edge connectivity of a graph or two vertices, this is recently also called group adhesion. } \section{\code{edge_connectivity()} Edge connectivity}{ -The edge connectivity of a pair of vertices (\code{source} and -\code{target}) is the minimum number of edges needed to remove to eliminate -all (directed) paths from \code{source} to \code{target}. -\code{edge_connectivity()} calculates this quantity if both the \code{source} -and \code{target} arguments are given (and not \code{NULL}). +The edge connectivity of a pair of vertices (\code{source} and \code{target}) is the minimum number of edges needed to remove to eliminate all (directed) paths from \code{source} to \code{target}. +\code{edge_connectivity()} calculates this quantity if both the \code{source} and \code{target} arguments are given (and not \code{NULL}). -The edge connectivity of a graph is the minimum of the edge connectivity of -every (ordered) pair of vertices in the graph. \code{edge_connectivity()} -calculates this quantity if neither the \code{source} nor the \code{target} -arguments are given (i.e. they are both \code{NULL}). +The edge connectivity of a graph is the minimum of the edge connectivity of every (ordered) pair of vertices in the graph. +\code{edge_connectivity()} calculates this quantity if neither the \code{source} nor the \code{target} arguments are given (i.e. they are both \code{NULL}). } \section{\code{edge_disjoint_paths()} The maximum number of edge-disjoint paths between two vertices}{ -A set of paths between two vertices is called edge-disjoint if they do not -share any edges. The maximum number of edge-disjoint paths are calculated -by this function using maximum flow techniques. Directed paths are -considered in directed graphs. +A set of paths between two vertices is called edge-disjoint if they do not share any edges. +The maximum number of edge-disjoint paths are calculated by this function using maximum flow techniques. +Directed paths are considered in directed graphs. -A set of edge disjoint paths between two vertices is a set of paths between -them containing no common edges. The maximum number of edge disjoint paths -between two vertices is the same as their edge connectivity. +A set of edge disjoint paths between two vertices is a set of paths between them containing no common edges. +The maximum number of edge disjoint paths between two vertices is the same as their edge connectivity. -When there are no direct edges between the source and the target, the number -of vertex-disjoint paths is the same as the vertex connectivity of -the two vertices. When some edges are present, each one of them -contributes one extra path. +When there are no direct edges between the source and the target, +the number of vertex-disjoint paths is the same as the vertex connectivity of the two vertices. +When some edges are present, each one of them contributes one extra path. } \section{\code{adhesion()} Adhesion of a graph}{ -The adhesion of a graph is the minimum number of edges needed to remove to -obtain a graph which is not strongly connected. This is the same as the edge -connectivity of the graph. +The adhesion of a graph is the minimum number of edges needed to remove to obtain a graph which is not strongly connected. +This is the same as the edge connectivity of the graph. } \section{All three functions}{ -The three functions documented on this page calculate similar properties, -more precisely the most general is \code{edge_connectivity()}, the others are -included only for having more descriptive function names. +The three functions documented on this page calculate similar properties, more precisely the most general is \code{edge_connectivity()}, +the others are included only for having more descriptive function names. } \section{Related documentation in the C library}{ diff --git a/man/edge_density.Rd b/man/edge_density.Rd index f62bbcec7ea..e6f16e11fe5 100644 --- a/man/edge_density.Rd +++ b/man/edge_density.Rd @@ -12,23 +12,20 @@ edge_density(graph, ..., loops = FALSE) \item{...}{These dots are for future extensions and must be empty.} \item{loops}{Logical, whether loop edges may exist in the graph. -This affects the calculation of the largest possible number of edges in the -graph. If this parameter is set to FALSE yet the graph contains self-loops, -the result will not be meaningful.} +This affects the calculation of the largest possible number of edges in the graph. +If this parameter is set to FALSE yet the graph contains self-loops, the result will not be meaningful.} } \value{ -A real constant. This function returns \code{NaN} (=0.0/0.0) for an -empty graph with zero vertices. +A real constant. +This function returns \code{NaN} (=0.0/0.0) for an empty graph with zero vertices. } \description{ -The density of a graph is the ratio of the actual number of edges and the -largest possible number of edges in the graph, assuming that no multi-edges -are present. +The density of a graph is the ratio of the actual number of edges and the largest possible number of edges in the graph, +assuming that no multi-edges are present. } \details{ -The concept of density is ill-defined for multigraphs. Note that this function -does not check whether the graph has multi-edges and will return meaningless -results for such graphs. +The concept of density is ill-defined for multigraphs. +Note that this function does not check whether the graph has multi-edges and will return meaningless results for such graphs. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_density}{\code{density()}} @@ -52,8 +49,7 @@ Wasserman, S., and Faust, K. (1994). Social Network Analysis: Methods and Applications. Cambridge: Cambridge University Press. } \seealso{ -\code{\link[=vcount]{vcount()}}, \code{\link[=ecount]{ecount()}}, \code{\link[=simplify]{simplify()}} -to get rid of the multiple and/or loop edges. +\code{\link[=vcount]{vcount()}}, \code{\link[=ecount]{ecount()}}, \code{\link[=simplify]{simplify()}} to get rid of the multiple and/or loop edges. Other structural.properties: \code{\link[=bfs]{bfs()}}, diff --git a/man/ego.Rd b/man/ego.Rd index 67ddfceda02..5233fb1b31e 100644 --- a/man/ego.Rd +++ b/man/ego.Rd @@ -70,18 +70,17 @@ make_neighborhood_graph( \arguments{ \item{graph}{The input graph.} -\item{order}{Integer giving the order of the neighborhood. Negative values -indicate an infinite order.} +\item{order}{Integer giving the order of the neighborhood. +Negative values indicate an infinite order.} \item{...}{These dots are for future extensions and must be empty.} -\item{mode}{Character constant, it specifies how to use the direction of -the edges if a directed graph is analyzed. For \sQuote{out} only the -outgoing edges are followed, so all vertices reachable from the source -vertex in at most \code{order} steps are counted. For \sQuote{"in"} all -vertices from which the source vertex is reachable in at most \code{order} -steps are counted. \sQuote{"all"} ignores the direction of the edges. This -argument is ignored for undirected graphs.} +\item{mode}{Character constant, it specifies how to use the direction of the edges if a directed graph is analyzed. +For \sQuote{out} only the outgoing edges are followed, +so all vertices reachable from the source vertex in at most \code{order} steps are counted. +For \sQuote{"in"} all vertices from which the source vertex is reachable in at most \code{order} steps are counted. +\sQuote{"all"} ignores the direction of the edges. +This argument is ignored for undirected graphs.} \item{nodes}{The vertices for which the calculation is performed. The default \code{NULL} selects all vertices.} @@ -99,31 +98,25 @@ see details for performance characteristics.} } } \description{ -These functions find the vertices not farther than a given limit from -another fixed vertex, these are called the neighborhood of the vertex. -Note that \code{ego()} and \code{neighborhood()}, -\code{ego_size()} and \code{neighborhood_size()}, -\code{make_ego_graph()} and \verb{make_neighborhood()_graph()}, +These functions find the vertices not farther than a given limit from another fixed vertex, +these are called the neighborhood of the vertex. +Note that \code{ego()} and \code{neighborhood()}, \code{ego_size()} and \code{neighborhood_size()}, \code{make_ego_graph()} and \verb{make_neighborhood()_graph()}, are synonyms (aliases). } \details{ -The neighborhood of a given order \code{r} of a vertex \code{v} includes all -vertices which are closer to \code{v} than the order. I.e. order 0 is always -\code{v} itself, order 1 is \code{v} plus its immediate neighbors, order 2 -is order 1 plus the immediate neighbors of the vertices in order 1, etc. +The neighborhood of a given order \code{r} of a vertex \code{v} includes all vertices which are closer to \code{v} than the order. +I.e. order 0 is always \code{v} itself, order 1 is \code{v} plus its immediate neighbors, +order 2 is order 1 plus the immediate neighbors of the vertices in order 1, etc. \code{ego_size()}/\code{neighborhood_size()} (synonyms) returns the size of the neighborhoods of the given order, for each given vertex. -\code{ego()}/\code{neighborhood()} (synonyms) returns the vertices belonging to the neighborhoods of the given -order, for each given vertex. +\code{ego()}/\code{neighborhood()} (synonyms) returns the vertices belonging to the neighborhoods of the given order, for each given vertex. -\code{make_ego_graph()}/\verb{make_neighborhood()_graph()} (synonyms) is creates (sub)graphs from all neighborhoods of -the given vertices with the given order parameter. This function preserves -the vertex, edge and graph attributes. +\code{make_ego_graph()}/\verb{make_neighborhood()_graph()} (synonyms) is creates (sub)graphs from all neighborhoods of the given vertices with the given order parameter. +This function preserves the vertex, edge and graph attributes. -\code{connect()} creates a new graph by connecting each vertex to -all other vertices in its neighborhood. +\code{connect()} creates a new graph by connecting each vertex to all other vertices in its neighborhood. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Operators.html#igraph_connect_neighborhood}{\code{connect_neighborhood()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/eigen_centrality.Rd b/man/eigen_centrality.Rd index 287bfa656fa..9447d8b82c3 100644 --- a/man/eigen_centrality.Rd +++ b/man/eigen_centrality.Rd @@ -15,26 +15,23 @@ eigen_centrality( \arguments{ \item{graph}{Graph to be analyzed.} -\item{directed}{Logical, whether to consider direction of the edges -in directed graphs. It is ignored for undirected graphs.} +\item{directed}{Logical, whether to consider direction of the edges in directed graphs. +It is ignored for undirected graphs.} -\item{scale}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Normalization will always take -place.} +\item{scale}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Normalization will always take place.} -\item{weights}{A numerical vector or \code{NULL}. This argument can be used -to give edge weights for calculating the weighted eigenvector centrality of -vertices. If this is \code{NULL} and the graph has a \code{weight} edge -attribute then that is used. If \code{weights} is a numerical vector then it is -used, even if the graph has a \code{weight} edge attribute. If this is -\code{NA}, then no edge weights are used (even if the graph has a -\code{weight} edge attribute). Note that if there are negative edge weights -and the direction of the edges is considered, then the eigenvector might be -complex. In this case only the real part is reported. -This function interprets weights as connection strength. Higher -weights spread the centrality better.} +\item{weights}{A numerical vector or \code{NULL}. +This argument can be used to give edge weights for calculating the weighted eigenvector centrality of vertices. +If this is \code{NULL} and the graph has a \code{weight} edge attribute then that is used. +If \code{weights} is a numerical vector then it is used, even if the graph has a \code{weight} edge attribute. +If this is \code{NA}, then no edge weights are used (even if the graph has a \code{weight} edge attribute). +Note that if there are negative edge weights and the direction of the edges is considered, then the eigenvector might be complex. +In this case only the real part is reported. +This function interprets weights as connection strength. +Higher weights spread the centrality better.} -\item{options}{A named list, to override some ARPACK options. See -\code{\link[=arpack]{arpack()}} for details.} +\item{options}{A named list, to override some ARPACK options. +See \code{\link[=arpack]{arpack()}} for details.} } \value{ A named list with components: @@ -51,50 +48,40 @@ A named list, information about the underlying ARPACK computation. See \code{\li } } \description{ -\code{eigen_centrality()} takes a graph (\code{graph}) and returns the -eigenvector centralities of the vertices \code{v} within it. +\code{eigen_centrality()} takes a graph (\code{graph}) and returns the eigenvector centralities of the vertices \code{v} within it. } \details{ -Eigenvector centrality scores correspond to the values of the principal -eigenvector of the graph's adjacency matrix; these scores may, in turn, be -interpreted as arising from a reciprocal process in which the centrality of -each actor is proportional to the sum of the centralities of those actors to -whom he or she is connected. In general, vertices with high eigenvector -centralities are those which are connected to many other vertices which are, -in turn, connected to many others (and so on). The perceptive may realize -that this implies that the largest values will be obtained by individuals in -large cliques (or high-density substructures). This is also intelligible -from an algebraic point of view, with the first eigenvector being closely -related to the best rank-1 approximation of the adjacency matrix (a -relationship which is easy to see in the special case of a diagonalizable -symmetric real matrix via the \eqn{SLS^-1}{$S \Lambda S^{-1}$} -decomposition). +Eigenvector centrality scores correspond to the values of the principal eigenvector of the graph's adjacency matrix; these scores may, +in turn, +be interpreted as arising from a reciprocal process +in which the centrality of each actor is proportional to the sum of the centralities of those actors to whom he or she is connected. +In general, +vertices with high eigenvector centralities are those which are connected to many other vertices which are, in turn, +connected to many others (and so on). +The perceptive may realize that this implies +that the largest values will be obtained by individuals in large cliques (or high-density substructures). +This is also intelligible from an algebraic point of view, +with the first eigenvector being closely related to the best rank-1 approximation of the adjacency matrix (a relationship which is easy to see in the special case of a diagonalizable symmetric real matrix via the \eqn{SLS^-1}{$S \Lambda S^{-1}$} decomposition). -The adjacency matrix used in the eigenvector centrality calculation assumes -that loop edges are counted \emph{twice} in undirected graphs; this is because -each loop edge has \emph{two} endpoints that are both connected to the same vertex, +The adjacency matrix used in the eigenvector centrality calculation assumes that loop edges are counted \emph{twice} in undirected graphs; +this is because each loop edge has \emph{two} endpoints that are both connected to the same vertex, and you could traverse the loop edge via either endpoint. -In the directed case, the left eigenvector of the adjacency matrix is -calculated. In other words, the centrality of a vertex is proportional to -the sum of centralities of vertices pointing to it. +In the directed case, the left eigenvector of the adjacency matrix is calculated. +In other words, the centrality of a vertex is proportional to the sum of centralities of vertices pointing to it. Eigenvector centrality is meaningful only for (strongly) connected graphs. -Undirected graphs that are not connected should be decomposed into connected -components, and the eigenvector centrality calculated for each separately. -This function does not verify that the graph is connected. If it is not, in -the undirected case the scores of all but one component will be zeros. +Undirected graphs that are not connected should be decomposed into connected components, +and the eigenvector centrality calculated for each separately. +This function does not verify that the graph is connected. +If it is not, in the undirected case the scores of all but one component will be zeros. -Also note that the adjacency matrix of a directed acyclic graph or the -adjacency matrix of an empty graph does not possess positive eigenvalues, -therefore the eigenvector centrality is not defined for these graphs. -igraph will return an eigenvalue of zero in such cases. The eigenvector -centralities will all be equal for an empty graph and will all be zeros for -a directed acyclic graph. Such pathological cases can be detected by checking -whether the eigenvalue is very close to zero. +Also note that the adjacency matrix of a directed acyclic graph or the adjacency matrix of an empty graph does not possess positive eigenvalues, +therefore the eigenvector centrality is not defined for these graphs. igraph will return an eigenvalue of zero in such cases. +The eigenvector centralities will all be equal for an empty graph and will all be zeros for a directed acyclic graph. +Such pathological cases can be detected by checking whether the eigenvalue is very close to zero. -From igraph version 0.5 this function uses ARPACK for the underlying -computation, see \code{\link[=arpack]{arpack()}} for more about ARPACK in igraph. +From igraph version 0.5 this function uses ARPACK for the underlying computation, see \code{\link[=arpack]{arpack()}} for more about ARPACK in igraph. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_eigenvector_centrality}{\code{eigenvector_centrality()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/embed_adjacency_matrix.Rd b/man/embed_adjacency_matrix.Rd index b5071c1785f..c10b7859448 100644 --- a/man/embed_adjacency_matrix.Rd +++ b/man/embed_adjacency_matrix.Rd @@ -18,36 +18,31 @@ embed_adjacency_matrix( \arguments{ \item{graph}{The input graph, directed or undirected.} -\item{no}{An integer scalar. This value is the embedding dimension of the -spectral embedding. Should be smaller than the number of vertices. The -largest \code{no}-dimensional non-zero singular values are used for the -spectral embedding.} +\item{no}{An integer scalar. +This value is the embedding dimension of the spectral embedding. +Should be smaller than the number of vertices. +The largest \code{no}-dimensional non-zero singular values are used for the spectral embedding.} \item{...}{These dots are for future extensions and must be empty.} -\item{weights}{Optional positive weight vector for calculating a weighted -embedding. If the graph has a \code{weight} edge attribute, then this is -used by default. In a weighted embedding, the edge weights are used instead -of the binary adjacencny matrix.} +\item{weights}{Optional positive weight vector for calculating a weighted embedding. +If the graph has a \code{weight} edge attribute, then this is used by default. +In a weighted embedding, the edge weights are used instead of the binary adjacencny matrix.} -\item{which}{Which eigenvalues (or singular values, for directed graphs) to -use. \sQuote{lm} means the ones with the largest magnitude, \sQuote{la} is -the ones (algebraic) largest, and \sQuote{sa} is the (algebraic) smallest -eigenvalues. The default is \sQuote{lm}. Note that for directed graphs -\sQuote{la} and \sQuote{lm} are the equivalent, because the singular values -are used for the ordering.} +\item{which}{Which eigenvalues (or singular values, for directed graphs) to use. +\sQuote{lm} means the ones with the largest magnitude, \sQuote{la} is the ones (algebraic) largest, +and \sQuote{sa} is the (algebraic) smallest eigenvalues. +The default is \sQuote{lm}. +Note that for directed graphs \sQuote{la} and \sQuote{lm} are the equivalent, because the singular values are used for the ordering.} -\item{scaled}{Logical, if \code{FALSE}, then \eqn{U} and \eqn{V} are -returned instead of \eqn{X} and \eqn{Y}.} +\item{scaled}{Logical, if \code{FALSE}, then \eqn{U} and \eqn{V} are returned instead of \eqn{X} and \eqn{Y}.} -\item{cvec}{A numeric vector, its length is the number vertices in the -graph. This vector is added to the diagonal of the adjacency matrix. The -default \code{NULL} uses -\code{strength(graph, weights = weights) / (vcount(graph) - 1)}.} +\item{cvec}{A numeric vector, its length is the number vertices in the graph. +This vector is added to the diagonal of the adjacency matrix. +The default \code{NULL} uses \code{strength(graph, weights = weights) / (vcount(graph) - 1)}.} -\item{options}{A named list containing the parameters for the SVD -computation algorithm in ARPACK. The default \code{NULL} uses the values given -by \code{\link[=arpack_defaults]{arpack_defaults()}}.} +\item{options}{A named list containing the parameters for the SVD computation algorithm in ARPACK. +The default \code{NULL} uses the values given by \code{\link[=arpack_defaults]{arpack_defaults()}}.} } \value{ A list containing with entries: @@ -66,8 +61,8 @@ The eigenvalues (for undirected graphs) or the singular values (for directed graphs) calculated by the algorithm. } \item{options}{ -A named list, information about the underlying ARPACK -computation. See \code{\link[=arpack]{arpack()}} for the details. +A named list, information about the underlying ARPACK computation. +See \code{\link[=arpack]{arpack()}} for the details. } } } @@ -75,21 +70,16 @@ computation. See \code{\link[=arpack]{arpack()}} for the details. Spectral decomposition of the adjacency matrices of graphs. } \details{ -This function computes a \code{no}-dimensional Euclidean representation of -the graph based on its adjacency matrix, \eqn{A}. This representation is -computed via the singular value decomposition of the adjacency matrix, -\eqn{A=UDV^T}.In the case, where the graph is a random dot product graph -generated using latent position vectors in \eqn{R^{no}} for each vertex, the -embedding will provide an estimate of these latent vectors. +This function computes a \code{no}-dimensional Euclidean representation of the graph based on its adjacency matrix, \eqn{A}. +This representation is computed via the singular value decomposition of the adjacency matrix, \eqn{A=UDV^T}.In the case, +where the graph is a random dot product graph generated using latent position vectors in \eqn{R^{no}} for each vertex, +the embedding will provide an estimate of these latent vectors. -For undirected graphs the latent positions are calculated as -\eqn{X=U^{no}D^{1/2}}{U[no] sqrt(D[no])}, where \eqn{U^{no}}{U[no]} equals -to the first \code{no} columns of \eqn{U}, and \eqn{D^{1/2}}{sqrt(D[no])} is -a diagonal matrix containing the top \code{no} singular values on the -diagonal. +For undirected graphs the latent positions are calculated as \eqn{X=U^{no}D^{1/2}}{U[no] sqrt(D[no])}, +where \eqn{U^{no}}{U[no]} equals to the first \code{no} columns of \eqn{U}, +and \eqn{D^{1/2}}{sqrt(D[no])} is a diagonal matrix containing the top \code{no} singular values on the diagonal. -For directed graphs the embedding is defined as the pair -\eqn{X=U^{no}D^{1/2}}{U[no] sqrt(D[no])} and \eqn{Y=V^{no}D^{1/2}}{V[no] +For directed graphs the embedding is defined as the pair \eqn{X=U^{no}D^{1/2}}{U[no] sqrt(D[no])} and \eqn{Y=V^{no}D^{1/2}}{V[no] sqrt(D[no])}. (For undirected graphs \eqn{U=V}, so it is enough to keep one of them.) } diff --git a/man/embed_laplacian_matrix.Rd b/man/embed_laplacian_matrix.Rd index ae89843dbdc..a6fcb195d77 100644 --- a/man/embed_laplacian_matrix.Rd +++ b/man/embed_laplacian_matrix.Rd @@ -18,51 +18,42 @@ embed_laplacian_matrix( \arguments{ \item{graph}{The input graph, directed or undirected.} -\item{no}{An integer scalar. This value is the embedding dimension of the -spectral embedding. Should be smaller than the number of vertices. The -largest \code{no}-dimensional non-zero singular values are used for the -spectral embedding.} +\item{no}{An integer scalar. +This value is the embedding dimension of the spectral embedding. +Should be smaller than the number of vertices. +The largest \code{no}-dimensional non-zero singular values are used for the spectral embedding.} \item{...}{These dots are for future extensions and must be empty.} -\item{weights}{Optional positive weight vector for calculating a weighted -embedding. If the graph has a \code{weight} edge attribute, then this is -used by default. For weighted embedding, edge weights are used instead -of the binary adjacency matrix, and vertex strength (see -\code{\link[=strength]{strength()}}) is used instead of the degrees.} +\item{weights}{Optional positive weight vector for calculating a weighted embedding. +If the graph has a \code{weight} edge attribute, then this is used by default. +For weighted embedding, edge weights are used instead of the binary adjacency matrix, +and vertex strength (see \code{\link[=strength]{strength()}}) is used instead of the degrees.} -\item{which}{Which eigenvalues (or singular values, for directed graphs) to -use. \sQuote{lm} means the ones with the largest magnitude, \sQuote{la} is -the ones (algebraic) largest, and \sQuote{sa} is the (algebraic) smallest -eigenvalues. The default is \sQuote{lm}. Note that for directed graphs -\sQuote{la} and \sQuote{lm} are the equivalent, because the singular values -are used for the ordering.} +\item{which}{Which eigenvalues (or singular values, for directed graphs) to use. +\sQuote{lm} means the ones with the largest magnitude, \sQuote{la} is the ones (algebraic) largest, +and \sQuote{sa} is the (algebraic) smallest eigenvalues. +The default is \sQuote{lm}. +Note that for directed graphs \sQuote{la} and \sQuote{lm} are the equivalent, because the singular values are used for the ordering.} -\item{type}{The type of the Laplacian to use. Various definitions exist for -the Laplacian of a graph, and one can choose between them with this -argument. +\item{type}{The type of the Laplacian to use. +Various definitions exist for the Laplacian of a graph, and one can choose between them with this argument. -Possible values: \code{D-A} means \eqn{D-A} where \eqn{D} is the degree -matrix and \eqn{A} is the adjacency matrix; \code{DAD} means -\eqn{D^{1/2}}{D^1/2} times \eqn{A} times \eqn{D^{1/2}{D^1/2}}, -\eqn{D^{1/2}}{D^1/2} is the inverse of the square root of the degree matrix; -\code{I-DAD} means \eqn{I-D^{1/2}}{I-D^1/2}, where \eqn{I} is the identity -matrix. \code{OAP} is \eqn{O^{1/2}AP^{1/2}}{O^1/2 A P^1/2}, where -\eqn{O^{1/2}}{O^1/2} is the inverse of the square root of the out-degree -matrix and \eqn{P^{1/2}}{P^1/2} is the same for the in-degree matrix. +Possible values: \code{D-A} means \eqn{D-A} where \eqn{D} is the degree matrix and \eqn{A} is the adjacency matrix; +\code{DAD} means \eqn{D^{1/2}}{D^1/2} times \eqn{A} times \eqn{D^{1/2}{D^1/2}}, +\eqn{D^{1/2}}{D^1/2} is the inverse of the square root of the degree matrix; \code{I-DAD} means \eqn{I-D^{1/2}}{I-D^1/2}, +where \eqn{I} is the identity matrix. +\code{OAP} is \eqn{O^{1/2}AP^{1/2}}{O^1/2 A P^1/2}, +where \eqn{O^{1/2}}{O^1/2} is the inverse of the square root of the out-degree matrix and \eqn{P^{1/2}}{P^1/2} is the same for the in-degree matrix. -\code{OAP} is not defined for undirected graphs, and is the only defined type -for directed graphs. +\code{OAP} is not defined for undirected graphs, and is the only defined type for directed graphs. -The default (i.e. type \code{default}) is to use \code{D-A} for undirected -graphs and \code{OAP} for directed graphs.} +The default (i.e. type \code{default}) is to use \code{D-A} for undirected graphs and \code{OAP} for directed graphs.} -\item{scaled}{Logical, if \code{FALSE}, then \eqn{U} and \eqn{V} are -returned instead of \eqn{X} and \eqn{Y}.} +\item{scaled}{Logical, if \code{FALSE}, then \eqn{U} and \eqn{V} are returned instead of \eqn{X} and \eqn{Y}.} -\item{options}{A named list containing the parameters for the SVD -computation algorithm in ARPACK. The default \code{NULL} uses the values given -by \code{\link[=arpack_defaults]{arpack_defaults()}}.} +\item{options}{A named list containing the parameters for the SVD computation algorithm in ARPACK. +The default \code{NULL} uses the values given by \code{\link[=arpack_defaults]{arpack_defaults()}}.} } \value{ A list containing with entries: @@ -81,8 +72,8 @@ The eigenvalues (for undirected graphs) or the singular values (for directed graphs) calculated by the algorithm. } \item{options}{ -A named list, information about the underlying ARPACK -computation. See \code{\link[=arpack]{arpack()}} for the details. +A named list, information about the underlying ARPACK computation. +See \code{\link[=arpack]{arpack()}} for the details. } } } @@ -90,9 +81,8 @@ computation. See \code{\link[=arpack]{arpack()}} for the details. Spectral decomposition of Laplacian matrices of graphs. } \details{ -This function computes a \code{no}-dimensional Euclidean representation of -the graph based on its Laplacian matrix, \eqn{L}. This representation is -computed via the singular value decomposition of the Laplacian matrix. +This function computes a \code{no}-dimensional Euclidean representation of the graph based on its Laplacian matrix, \eqn{L}. +This representation is computed via the singular value decomposition of the Laplacian matrix. They are essentially doing the same as \code{\link[=embed_adjacency_matrix]{embed_adjacency_matrix()}}, but work on the Laplacian matrix, instead of the adjacency matrix. diff --git a/man/ends.Rd b/man/ends.Rd index be8c4381989..8c437963e4f 100644 --- a/man/ends.Rd +++ b/man/ends.Rd @@ -14,8 +14,8 @@ ends(graph, es, ..., names = TRUE) \item{...}{These dots are for future extensions and must be empty.} -\item{names}{Whether to return vertex names or -numeric vertex IDs. By default vertex names are used.} +\item{names}{Whether to return vertex names or numeric vertex IDs. +By default vertex names are used.} } \value{ A two column matrix of vertex names or vertex IDs. diff --git a/man/erdos.renyi.game.Rd b/man/erdos.renyi.game.Rd index 9a4fe5859c4..5beab295c3c 100644 --- a/man/erdos.renyi.game.Rd +++ b/man/erdos.renyi.game.Rd @@ -16,15 +16,12 @@ erdos.renyi.game( \arguments{ \item{n}{The number of vertices in the graph.} -\item{p.or.m}{Either the probability for drawing an edge between two -arbitrary vertices (\eqn{G(n,p)} graph), or the number of edges in -the graph (for \eqn{G(n,m)} graphs).} +\item{p.or.m}{Either the probability for drawing an edge between two arbitrary vertices (\eqn{G(n,p)} graph), +or the number of edges in the graph (for \eqn{G(n,m)} graphs).} -\item{type}{The type of the random graph to create, either \code{gnp()} -(\eqn{G(n,p)} graph) or \code{gnm()} (\eqn{G(n,m)} graph).} +\item{type}{The type of the random graph to create, either \code{gnp()} (\eqn{G(n,p)} graph) or \code{gnm()} (\eqn{G(n,m)} graph).} -\item{directed}{Logical, whether the graph will be directed, defaults to -\code{FALSE}.} +\item{directed}{Logical, whether the graph will be directed, defaults to \code{FALSE}.} \item{loops}{Logical, whether to add loop edges, defaults to \code{FALSE}.} } @@ -34,9 +31,9 @@ A graph object. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -Since igraph version 0.8.0, both \code{erdos.renyi.game()} and -\code{random.graph.game()} are deprecated, and \code{\link[=sample_gnp]{sample_gnp()}} and -\code{\link[=sample_gnm]{sample_gnm()}} should be used instead. See these for more details. +Since igraph version 0.8.0, both \code{erdos.renyi.game()} and \code{random.graph.game()} are deprecated, +and \code{\link[=sample_gnp]{sample_gnp()}} and \code{\link[=sample_gnm]{sample_gnm()}} should be used instead. +See these for more details. \code{random.graph.game()} is an (also deprecated) alias to this function. } diff --git a/man/establishment.game.Rd b/man/establishment.game.Rd index c27ce60c400..a06081fd737 100644 --- a/man/establishment.game.Rd +++ b/man/establishment.game.Rd @@ -20,11 +20,12 @@ establishment.game( \item{k}{The number of trials per time step, see details below.} -\item{type.dist}{The distribution of the vertex types. This is assumed to be -stationary in time. The default \code{NULL} gives a uniform distribution.} +\item{type.dist}{The distribution of the vertex types. +This is assumed to be stationary in time. +The default \code{NULL} gives a uniform distribution.} -\item{pref.matrix}{A matrix giving the preferences of the given vertex -types. These should be probabilities, i.e. numbers between zero and one. +\item{pref.matrix}{A matrix giving the preferences of the given vertex types. +These should be probabilities, i.e. numbers between zero and one. The default \code{NULL} sets all preferences to one.} \item{directed}{Logical, whether to generate directed graphs.} @@ -32,8 +33,7 @@ The default \code{NULL} sets all preferences to one.} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{establishment.game()} was renamed to \code{\link[=sample_traits]{sample_traits()}} to create a more -consistent API. +\code{establishment.game()} was renamed to \code{\link[=sample_traits]{sample_traits()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_establishment_game}{\code{establishment_game()}} diff --git a/man/estimate_betweenness.Rd b/man/estimate_betweenness.Rd index b56c96035f9..10a91010a77 100644 --- a/man/estimate_betweenness.Rd +++ b/man/estimate_betweenness.Rd @@ -15,19 +15,16 @@ estimate_betweenness( \arguments{ \item{graph}{The graph to analyze.} -\item{vids}{The vertices for which the vertex betweenness estimation will be -calculated.} +\item{vids}{The vertices for which the vertex betweenness estimation will be calculated.} -\item{directed}{Logical, whether directed paths should be considered while -determining the shortest paths.} +\item{directed}{Logical, whether directed paths should be considered while determining the shortest paths.} -\item{cutoff}{The maximum shortest path length to consider when calculating -betweenness. If negative, then there is no such limit.} +\item{cutoff}{The maximum shortest path length to consider when calculating betweenness. +If negative, then there is no such limit.} -\item{weights}{Optional positive weight vector for calculating weighted -betweenness. If the graph has a \code{weight} edge attribute, then this is -used by default. Weights are used to calculate weighted shortest paths, -so they are interpreted as distances.} +\item{weights}{Optional positive weight vector for calculating weighted betweenness. +If the graph has a \code{weight} edge attribute, then this is used by default. +Weights are used to calculate weighted shortest paths, so they are interpreted as distances.} } \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/estimate_closeness.Rd b/man/estimate_closeness.Rd index 2b7d031524d..986f2df6ad6 100644 --- a/man/estimate_closeness.Rd +++ b/man/estimate_closeness.Rd @@ -19,24 +19,19 @@ estimate_closeness( \item{vids}{The vertices for which closeness will be calculated. The default \code{NULL} selects all vertices.} -\item{mode}{Character string, defined the types of the paths used for -measuring the distance in directed graphs. \dQuote{in} measures the paths -\emph{to} a vertex, \dQuote{out} measures paths \emph{from} a vertex, -\emph{all} uses undirected paths. This argument is ignored for undirected -graphs.} +\item{mode}{Character string, defined the types of the paths used for measuring the distance in directed graphs. +\dQuote{in} measures the paths \emph{to} a vertex, \dQuote{out} measures paths \emph{from} a vertex, \emph{all} uses undirected paths. +This argument is ignored for undirected graphs.} -\item{cutoff}{The maximum path length to consider when calculating the -closeness. If zero or negative then there is no such limit.} +\item{cutoff}{The maximum path length to consider when calculating the closeness. +If zero or negative then there is no such limit.} -\item{weights}{Optional positive weight vector for calculating weighted -closeness. If the graph has a \code{weight} edge attribute, then this is -used by default. Weights are used for calculating weighted shortest -paths, so they are interpreted as distances.} +\item{weights}{Optional positive weight vector for calculating weighted closeness. +If the graph has a \code{weight} edge attribute, then this is used by default. +Weights are used for calculating weighted shortest paths, so they are interpreted as distances.} -\item{normalized}{Logical, whether to calculate the normalized -closeness, i.e. the inverse average distance to all reachable vertices. -The non-normalized closeness is the inverse of the sum of distances to -all reachable vertices.} +\item{normalized}{Logical, whether to calculate the normalized closeness, i.e. the inverse average distance to all reachable vertices. +The non-normalized closeness is the inverse of the sum of distances to all reachable vertices.} } \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/estimate_edge_betweenness.Rd b/man/estimate_edge_betweenness.Rd index acd055427c0..2fddaec4867 100644 --- a/man/estimate_edge_betweenness.Rd +++ b/man/estimate_edge_betweenness.Rd @@ -18,16 +18,14 @@ estimate_edge_betweenness( \item{e}{The edges for which the edge betweenness will be calculated. The default \code{NULL} selects all edges.} -\item{directed}{Logical, whether directed paths should be considered while -determining the shortest paths.} +\item{directed}{Logical, whether directed paths should be considered while determining the shortest paths.} -\item{cutoff}{The maximum shortest path length to consider when calculating -betweenness. If negative, then there is no such limit.} +\item{cutoff}{The maximum shortest path length to consider when calculating betweenness. +If negative, then there is no such limit.} -\item{weights}{Optional positive weight vector for calculating weighted -betweenness. If the graph has a \code{weight} edge attribute, then this is -used by default. Weights are used to calculate weighted shortest paths, -so they are interpreted as distances.} +\item{weights}{Optional positive weight vector for calculating weighted betweenness. +If the graph has a \code{weight} edge attribute, then this is used by default. +Weights are used to calculate weighted shortest paths, so they are interpreted as distances.} } \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/evcent.Rd b/man/evcent.Rd index a618c521979..7fc0d769b10 100644 --- a/man/evcent.Rd +++ b/man/evcent.Rd @@ -15,32 +15,28 @@ evcent( \arguments{ \item{graph}{Graph to be analyzed.} -\item{directed}{Logical, whether to consider direction of the edges -in directed graphs. It is ignored for undirected graphs.} +\item{directed}{Logical, whether to consider direction of the edges in directed graphs. +It is ignored for undirected graphs.} -\item{scale}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Normalization will always take -place.} +\item{scale}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Normalization will always take place.} -\item{weights}{A numerical vector or \code{NULL}. This argument can be used -to give edge weights for calculating the weighted eigenvector centrality of -vertices. If this is \code{NULL} and the graph has a \code{weight} edge -attribute then that is used. If \code{weights} is a numerical vector then it is -used, even if the graph has a \code{weight} edge attribute. If this is -\code{NA}, then no edge weights are used (even if the graph has a -\code{weight} edge attribute). Note that if there are negative edge weights -and the direction of the edges is considered, then the eigenvector might be -complex. In this case only the real part is reported. -This function interprets weights as connection strength. Higher -weights spread the centrality better.} +\item{weights}{A numerical vector or \code{NULL}. +This argument can be used to give edge weights for calculating the weighted eigenvector centrality of vertices. +If this is \code{NULL} and the graph has a \code{weight} edge attribute then that is used. +If \code{weights} is a numerical vector then it is used, even if the graph has a \code{weight} edge attribute. +If this is \code{NA}, then no edge weights are used (even if the graph has a \code{weight} edge attribute). +Note that if there are negative edge weights and the direction of the edges is considered, then the eigenvector might be complex. +In this case only the real part is reported. +This function interprets weights as connection strength. +Higher weights spread the centrality better.} -\item{options}{A named list, to override some ARPACK options. See -\code{\link[=arpack]{arpack()}} for details.} +\item{options}{A named list, to override some ARPACK options. +See \code{\link[=arpack]{arpack()}} for details.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{evcent()} was renamed to \code{\link[=eigen_centrality]{eigen_centrality()}} to create a more -consistent API. +\code{evcent()} was renamed to \code{\link[=eigen_centrality]{eigen_centrality()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_eigenvector_centrality}{\code{eigenvector_centrality()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/exportPajek.Rd b/man/exportPajek.Rd index d88573b6188..a7344a67ec6 100644 --- a/man/exportPajek.Rd +++ b/man/exportPajek.Rd @@ -7,35 +7,32 @@ exportPajek(blocks, graph, file, project.file = TRUE) } \arguments{ -\item{graph}{For \code{cohesive_blocks()} a graph object of class -\code{igraph}. It must be undirected and simple. (See -\code{\link[=is_simple]{is_simple()}}.) +\item{graph}{For \code{cohesive_blocks()} a graph object of class \code{igraph}. +It must be undirected and simple. +(See \code{\link[=is_simple]{is_simple()}}.) -For \code{graphs_from_cohesive_blocks()} and \code{export_pajek()} the same graph must be -supplied whose cohesive block structure is given in the \code{blocks()} -argument.} +For \code{graphs_from_cohesive_blocks()} and \code{export_pajek()} the same graph must be supplied whose cohesive block structure is given in the \code{blocks()} argument.} \item{file}{Defines the file (or connection) the Pajek file is written to. -If the \code{project.file} argument is \code{TRUE}, then it can be a -filename (with extension), a file object, or in general any king of -connection object. The file/connection will be opened if it wasn't already. +If the \code{project.file} argument is \code{TRUE}, then it can be a filename (with extension), a file object, +or in general any king of connection object. +The file/connection will be opened if it wasn't already. -If the \code{project.file} argument is \code{FALSE}, then several files are -created and \code{file} must be a character scalar containing the base name -of the files, without extension. (But it can contain the path to the files.) +If the \code{project.file} argument is \code{FALSE}, +then several files are created and \code{file} must be a character scalar containing the base name of the files, without extension. +(But it can contain the path to the files.) See also details below.} -\item{project.file}{Logical, whether to create a single Pajek project -file containing all the data, or to create separated files for each item. +\item{project.file}{Logical, whether to create a single Pajek project file containing all the data, +or to create separated files for each item. See details below.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{exportPajek()} was renamed to \code{\link[=export_pajek]{export_pajek()}} to create a more -consistent API. +\code{exportPajek()} was renamed to \code{\link[=export_pajek]{export_pajek()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Foreign.html#igraph_write_graph_edgelist}{\code{write_graph_edgelist()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Foreign.html#igraph_write_graph_pajek}{\code{write_graph_pajek()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Foreign.html#igraph_write_graph_graphml}{\code{write_graph_graphml()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Foreign.html#igraph_write_graph_gml}{\code{write_graph_gml()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Foreign.html#igraph_write_graph_dot}{\code{write_graph_dot()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Foreign.html#igraph_write_graph_leda}{\code{write_graph_leda()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/farthest.nodes.Rd b/man/farthest.nodes.Rd index a9ce78a850c..59f752f3d7a 100644 --- a/man/farthest.nodes.Rd +++ b/man/farthest.nodes.Rd @@ -9,24 +9,20 @@ farthest.nodes(graph, directed = TRUE, unconnected = TRUE, weights = NULL) \arguments{ \item{graph}{The graph to analyze.} -\item{directed}{Logical, whether directed or undirected paths are to be -considered. This is ignored for undirected graphs.} +\item{directed}{Logical, whether directed or undirected paths are to be considered. +This is ignored for undirected graphs.} -\item{unconnected}{Logical, what to do if the graph is unconnected. If -FALSE, the function will return a number that is one larger the largest -possible diameter, which is always the number of vertices. If TRUE, the -diameters of the connected components will be calculated and the largest one -will be returned.} +\item{unconnected}{Logical, what to do if the graph is unconnected. +If FALSE, the function will return a number that is one larger the largest possible diameter, which is always the number of vertices. +If TRUE, the diameters of the connected components will be calculated and the largest one will be returned.} -\item{weights}{Optional positive weight vector for calculating weighted -distances. If the graph has a \code{weight} edge attribute, then this is -used by default.} +\item{weights}{Optional positive weight vector for calculating weighted distances. +If the graph has a \code{weight} edge attribute, then this is used by default.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{farthest.nodes()} was renamed to \code{\link[=farthest_vertices]{farthest_vertices()}} to create a more -consistent API. +\code{farthest.nodes()} was renamed to \code{\link[=farthest_vertices]{farthest_vertices()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/fastgreedy.community.Rd b/man/fastgreedy.community.Rd index ff1251fb379..5461eb1e1cf 100644 --- a/man/fastgreedy.community.Rd +++ b/man/fastgreedy.community.Rd @@ -13,31 +13,27 @@ fastgreedy.community( ) } \arguments{ -\item{graph}{The input graph. It must be undirected and must not have -multi-edges.} +\item{graph}{The input graph. +It must be undirected and must not have multi-edges.} \item{merges}{Logical, whether to return the merge matrix.} -\item{modularity}{Logical, whether to return a vector containing the -modularity after each merge.} +\item{modularity}{Logical, whether to return a vector containing the modularity after each merge.} -\item{membership}{Logical, whether to calculate the membership vector -corresponding to the maximum modularity score, considering all possible -community structures along the merges.} +\item{membership}{Logical, whether to calculate the membership vector corresponding to the maximum modularity score, +considering all possible community structures along the merges.} -\item{weights}{The weights of the edges. It must be a positive numeric vector, -\code{NULL} or \code{NA}. If it is \code{NULL} and the input graph has a -\sQuote{weight} edge attribute, then that attribute will be used. If -\code{NULL} and no such attribute is present, then the edges will have equal -weights. Set this to \code{NA} if the graph was a \sQuote{weight} edge -attribute, but you don't want to use it for community detection. A larger -edge weight means a stronger connection for this function.} +\item{weights}{The weights of the edges. +It must be a positive numeric vector, \code{NULL} or \code{NA}. +If it is \code{NULL} and the input graph has a \sQuote{weight} edge attribute, then that attribute will be used. +If \code{NULL} and no such attribute is present, then the edges will have equal weights. +Set this to \code{NA} if the graph was a \sQuote{weight} edge attribute, but you don't want to use it for community detection. +A larger edge weight means a stronger connection for this function.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{fastgreedy.community()} was renamed to \code{\link[=cluster_fast_greedy]{cluster_fast_greedy()}} to create a more -consistent API. +\code{fastgreedy.community()} was renamed to \code{\link[=cluster_fast_greedy]{cluster_fast_greedy()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/feedback_arc_set.Rd b/man/feedback_arc_set.Rd index 4e243de7630..a552d649419 100644 --- a/man/feedback_arc_set.Rd +++ b/man/feedback_arc_set.Rd @@ -16,34 +16,27 @@ feedback_arc_set( \item{...}{These dots are for future extensions and must be empty.} -\item{weights}{Potential edge weights. If the graph has an edge -attribute called \sQuote{\code{weight}}, and this argument is -\code{NULL}, then the edge attribute is used automatically. The goal of -the feedback arc set problem is to find a feedback arc set with the smallest -total weight.} +\item{weights}{Potential edge weights. +If the graph has an edge attribute called \sQuote{\code{weight}}, and this argument is \code{NULL}, +then the edge attribute is used automatically. +The goal of the feedback arc set problem is to find a feedback arc set with the smallest total weight.} -\item{algo}{Specifies the algorithm to use. \dQuote{\code{exact_ip}} solves -the feedback arc set problem with an exact integer programming algorithm that -guarantees that the total weight of the removed edges is as small as possible. -\dQuote{\code{approx_eades}} uses a fast (linear-time) approximation -algorithm from Eades, Lin and Smyth. \dQuote{\code{exact}} is an alias to -\dQuote{\code{exact_ip}} while \dQuote{\code{approx}} is an alias to -\dQuote{\code{approx_eades}}.} +\item{algo}{Specifies the algorithm to use. +\dQuote{\code{exact_ip}} solves the feedback arc set problem with an exact integer programming algorithm that guarantees that the total weight of the removed edges is as small as possible. +\dQuote{\code{approx_eades}} uses a fast (linear-time) approximation algorithm from Eades, Lin and Smyth. +\dQuote{\code{exact}} is an alias to \dQuote{\code{exact_ip}} while \dQuote{\code{approx}} is an alias to \dQuote{\code{approx_eades}}.} } \value{ -An edge sequence (by default, but see the \code{return.vs.es} option -of \code{\link[=igraph_options]{igraph_options()}}) containing the feedback arc set. +An edge sequence (by default, but see the \code{return.vs.es} option of \code{\link[=igraph_options]{igraph_options()}}) containing the feedback arc set. } \description{ -A feedback arc set of a graph is a subset of edges whose removal breaks all -cycles in the graph. +A feedback arc set of a graph is a subset of edges whose removal breaks all cycles in the graph. } \details{ -Feedback arc sets are typically used in directed graphs. The removal of a -feedback arc set of a directed graph ensures that the remaining graph is a -directed acyclic graph (DAG). For undirected graphs, the removal of a feedback -arc set ensures that the remaining graph is a forest (i.e. every connected -component is a tree). +Feedback arc sets are typically used in directed graphs. +The removal of a feedback arc set of a directed graph ensures that the remaining graph is a directed acyclic graph (DAG). +For undirected graphs, +the removal of a feedback arc set ensures that the remaining graph is a forest (i.e. every connected component is a tree). } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_feedback_arc_set}{\code{feedback_arc_set()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/feedback_vertex_set.Rd b/man/feedback_vertex_set.Rd index 89dd657e20d..290d47cfbf4 100644 --- a/man/feedback_vertex_set.Rd +++ b/man/feedback_vertex_set.Rd @@ -11,26 +11,23 @@ feedback_vertex_set(graph, ..., weights = NULL, algo = c("exact_ip")) \item{...}{These dots are for future extensions and must be empty.} -\item{weights}{Potential vertex weights. If the graph has a vertex -attribute called \sQuote{\code{weight}}, and this argument is -\code{NULL}, then the vertex attribute is used automatically. The goal of -the feedback vertex set problem is to find a feedback vertex set with -the smallest total weight.} +\item{weights}{Potential vertex weights. +If the graph has a vertex attribute called \sQuote{\code{weight}}, and this argument is \code{NULL}, +then the vertex attribute is used automatically. +The goal of the feedback vertex set problem is to find a feedback vertex set with the smallest total weight.} -\item{algo}{Specifies the algorithm to use. Currently, \dQuote{\code{exact_ip}}, -which solves the feedback vertex set problem with an exact integer -programming approach, is the only option.} +\item{algo}{Specifies the algorithm to use. +Currently, \dQuote{\code{exact_ip}}, which solves the feedback vertex set problem with an exact integer programming approach, +is the only option.} } \value{ -A vertex sequence (by default, but see the \code{return.vs.es} option -of \code{\link[=igraph_options]{igraph_options()}}) containing the feedback vertex set. +A vertex sequence (by default, but see the \code{return.vs.es} option of \code{\link[=igraph_options]{igraph_options()}}) containing the feedback vertex set. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} -A feedback vertex set of a graph is a subset of vertices whose removal breaks -all cycles in the graph. Finding a \emph{minimum} feedback vertex set is an -NP-complete problem, both on directed and undirected graphs. +A feedback vertex set of a graph is a subset of vertices whose removal breaks all cycles in the graph. +Finding a \emph{minimum} feedback vertex set is an NP-complete problem, both on directed and undirected graphs. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_feedback_vertex_set}{\code{feedback_vertex_set()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/find_cycle.Rd b/man/find_cycle.Rd index f35f567bc46..b025dce7174 100644 --- a/man/find_cycle.Rd +++ b/man/find_cycle.Rd @@ -12,23 +12,20 @@ find_cycle(graph, ..., mode = c("out", "in", "all", "total")) \item{...}{These dots are for future extensions and must be empty.} \item{mode}{Character constant specifying how to handle directed graphs. -\code{out} follows edge directions, \verb{in} follows edges in the reverse direction, -and \code{all} ignores edge directions. Ignored in undirected graphs.} +\code{out} follows edge directions, \verb{in} follows edges in the reverse direction, and \code{all} ignores edge directions. +Ignored in undirected graphs.} } \value{ -A list of integer vectors, each integer vector is a path from -the source vertex to one of the target vertices. A path is given by its -vertex IDs. +A list of integer vectors, each integer vector is a path from the source vertex to one of the target vertices. +A path is given by its vertex IDs. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} -This function returns a cycle of the graph, in terms of both its vertices -and edges. If the graph is acyclic, it returns empty vertex and edge -sequences. +This function returns a cycle of the graph, in terms of both its vertices and edges. +If the graph is acyclic, it returns empty vertex and edge sequences. -Use \code{\link[=is_acyclic]{is_acyclic()}} to determine if a graph has cycles, without returning -a specific cycle. +Use \code{\link[=is_acyclic]{is_acyclic()}} to determine if a graph has cycles, without returning a specific cycle. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Cycles.html#igraph_find_cycle}{\code{find_cycle()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}} diff --git a/man/fit_hrg.Rd b/man/fit_hrg.Rd index 413132e4abd..e500d88a8bc 100644 --- a/man/fit_hrg.Rd +++ b/man/fit_hrg.Rd @@ -7,24 +7,22 @@ fit_hrg(graph, hrg = NULL, ..., start = FALSE, steps = 0) } \arguments{ -\item{graph}{The graph to fit the model to. Edge directions are ignored in -directed graphs.} +\item{graph}{The graph to fit the model to. +Edge directions are ignored in directed graphs.} -\item{hrg}{A hierarchical random graph model, in the form of an -\code{igraphHRG} object. \code{fit_hrg()} allows this to be \code{NULL}, in -which case a random starting point is used for the fitting.} +\item{hrg}{A hierarchical random graph model, in the form of an \code{igraphHRG} object. +\code{fit_hrg()} allows this to be \code{NULL}, in which case a random starting point is used for the fitting.} \item{...}{These dots are for future extensions and must be empty.} -\item{start}{Logical, whether to start the fitting/sampling from the -supplied \code{igraphHRG} object, or from a random starting point.} +\item{start}{Logical, whether to start the fitting/sampling from the supplied \code{igraphHRG} object, or from a random starting point.} -\item{steps}{The number of MCMC steps to make. If this is zero, then the -MCMC procedure is performed until convergence.} +\item{steps}{The number of MCMC steps to make. +If this is zero, then the MCMC procedure is performed until convergence.} } \value{ -\code{fit_hrg()} returns an \code{igraphHRG} object. This is a list -with the following members: +\code{fit_hrg()} returns an \code{igraphHRG} object. +This is a list with the following members: \describe{ \item{left}{ Vector that contains the left children of the internal tree vertices. @@ -52,12 +50,11 @@ The number of vertices in the subtree below the given internal vertex, including } } \description{ -\code{fit_hrg()} fits a HRG to a given graph. It takes the specified -\code{steps} number of MCMC steps to perform the fitting, or a convergence -criteria if the specified number of steps is zero. \code{fit_hrg()} can start -from a given HRG, if this is given in the \code{hrg()} argument and the -\code{start} argument is \code{TRUE}. It can be converted to the \code{hclust} class using -\code{as.hclust()} provided in this package. +\code{fit_hrg()} fits a HRG to a given graph. +It takes the specified \code{steps} number of MCMC steps to perform the fitting, +or a convergence criteria if the specified number of steps is zero. +\code{fit_hrg()} can start from a given HRG, if this is given in the \code{hrg()} argument and the \code{start} argument is \code{TRUE}. +It can be converted to the \code{hclust} class using \code{as.hclust()} provided in this package. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-HRG.html#igraph_hrg_fit}{\code{hrg_fit()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/fit_power_law.Rd b/man/fit_power_law.Rd index c35bb42001c..50ad9bde343 100644 --- a/man/fit_power_law.Rd +++ b/man/fit_power_law.Rd @@ -16,29 +16,29 @@ fit_power_law( ) } \arguments{ -\item{x}{The data to fit, a numeric vector. For implementation -\sQuote{\code{R.mle}} the data must be integer values. For the -\sQuote{\code{plfit}} implementation non-integer values might be present and -then a continuous power-law distribution is fitted.} - -\item{xmin}{Numeric scalar, or \code{NULL}. The lower bound for fitting the -power-law. If \code{NULL}, the smallest value in \code{x} will be used for -the \sQuote{\code{R.mle}} implementation, and its value will be -automatically determined for the \sQuote{\code{plfit}} implementation. This -argument makes it possible to fit only the tail of the distribution.} - -\item{start}{Numeric scalar. The initial value of the exponent for the -minimizing function, for the \sQuote{\code{R.mle}} implementation. Usually -it is safe to leave this untouched.} - -\item{force.continuous}{Logical. Whether to force a continuous -distribution for the \sQuote{\code{plfit}} implementation, even if the -sample vector contains integer values only (by chance). If this argument is -false, igraph will assume a continuous distribution if at least one sample -is non-integer and assume a discrete distribution otherwise.} - -\item{implementation}{Character scalar. Which implementation to use. See -details below.} +\item{x}{The data to fit, a numeric vector. +For implementation \sQuote{\code{R.mle}} the data must be integer values. +For the \sQuote{\code{plfit}} implementation non-integer values might be present and then a continuous power-law distribution is fitted.} + +\item{xmin}{Numeric scalar, or \code{NULL}. +The lower bound for fitting the power-law. +If \code{NULL}, the smallest value in \code{x} will be used for the \sQuote{\code{R.mle}} implementation, +and its value will be automatically determined for the \sQuote{\code{plfit}} implementation. +This argument makes it possible to fit only the tail of the distribution.} + +\item{start}{Numeric scalar. +The initial value of the exponent for the minimizing function, for the \sQuote{\code{R.mle}} implementation. +Usually it is safe to leave this untouched.} + +\item{force.continuous}{Logical. +Whether to force a continuous distribution for the \sQuote{\code{plfit}} implementation, +even if the sample vector contains integer values only (by chance). +If this argument is false, +igraph will assume a continuous distribution if at least one sample is non-integer and assume a discrete distribution otherwise.} + +\item{implementation}{Character scalar. +Which implementation to use. +See details below.} \item{p.value}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} @@ -46,25 +46,22 @@ Set to \code{TRUE} to compute the p-value with \code{implementation = "plfit"}.} \item{p.precision}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} -The desired precision of the p-value calculation. The -precision ultimately depends on the number of resampling attempts. The -number of resampling trials is determined by 0.25 divided by the square -of the required precision. For instance, a required precision of 0.01 -means that 2500 samples will be drawn.} +The desired precision of the p-value calculation. +The precision ultimately depends on the number of resampling attempts. +The number of resampling trials is determined by 0.25 divided by the square of the required precision. +For instance, a required precision of 0.01 means that 2500 samples will be drawn.} -\item{\dots}{Additional arguments, passed to the maximum likelihood -optimizing function, \code{\link[stats4:mle]{stats4::mle()}}, if the \sQuote{\code{R.mle}} -implementation is chosen. It is ignored by the \sQuote{\code{plfit}} -implementation.} +\item{\dots}{Additional arguments, passed to the maximum likelihood optimizing function, \code{\link[stats4:mle]{stats4::mle()}}, +if the \sQuote{\code{R.mle}} implementation is chosen. +It is ignored by the \sQuote{\code{plfit}} implementation.} } \value{ -Depends on the \code{implementation} argument. If it is -\sQuote{\code{R.mle}}, then an object with class \sQuote{\code{mle}}. It can -be used to calculate confidence intervals and log-likelihood. See -\code{\link[stats4:mle-class]{stats4::mle-class()}} for details. +Depends on the \code{implementation} argument. +If it is \sQuote{\code{R.mle}}, then an object with class \sQuote{\code{mle}}. +It can be used to calculate confidence intervals and log-likelihood. +See \code{\link[stats4:mle-class]{stats4::mle-class()}} for details. -If \code{implementation} is \sQuote{\code{plfit}}, then the result is a -named list with entries: +If \code{implementation} is \sQuote{\code{plfit}}, then the result is a named list with entries: \describe{ \item{continuous}{ Logical, whether the @@ -74,9 +71,8 @@ fitted power-law distribution was continuous or discrete. Numeric scalar, the exponent of the fitted power-law distribution. } \item{xmin}{ -Numeric scalar, the minimum value from which the -power-law distribution was fitted. In other words, only the values larger -than \code{xmin} were used from the input vector. +Numeric scalar, the minimum value from which the power-law distribution was fitted. +In other words, only the values larger than \code{xmin} were used from the input vector. } \item{logLik}{ Numeric scalar, the log-likelihood of the fitted parameters. @@ -87,10 +83,10 @@ that compares the fitted distribution with the input vector. Smaller scores denote better fit. } \item{KS.p}{ -Only for \code{p.value = TRUE}. Numeric scalar, the p-value of the Kolmogorov-Smirnov -test. Small p-values (less than 0.05) indicate that the test rejected the -hypothesis that the original data could have been drawn from the fitted -power-law distribution. +Only for \code{p.value = TRUE}. +Numeric scalar, the p-value of the Kolmogorov-Smirnov test. +Small p-values (less than 0.05) indicate that the test rejected the hypothesis +that the original data could have been drawn from the fitted power-law distribution. } } } @@ -98,31 +94,26 @@ power-law distribution. \code{fit_power_law()} fits a power-law distribution to a data set. } \details{ -This function fits a power-law distribution to a vector containing samples -from a distribution (that is assumed to follow a power-law of course). In a -power-law distribution, it is generally assumed that \eqn{P(X=x)} is -proportional to \eqn{x^{-\alpha}}{x^-alpha}, where \eqn{x} is a positive -number and \eqn{\alpha}{alpha} is greater than 1. In many real-world cases, -the power-law behaviour kicks in only above a threshold value -\eqn{x_\text{min}}{xmin}. The goal of this function is to determine -\eqn{\alpha}{alpha} if \eqn{x_\text{min}}{xmin} is given, or to determine -\eqn{x_\text{min}}{xmin} and the corresponding value of \eqn{\alpha}{alpha}. - -\code{fit_power_law()} provides two maximum likelihood implementations. If -the \code{implementation} argument is \sQuote{\code{R.mle}}, then the BFGS -optimization (see \code{\link[stats4:mle]{stats4::mle()}}) algorithm is applied. The additional -arguments are passed to the mle function, so it is possible to change the -optimization method and/or its parameters. This implementation can -\emph{not} to fit the \eqn{x_\text{min}}{xmin} argument, so use the -\sQuote{\code{plfit}} implementation if you want to do that. - -The \sQuote{\code{plfit}} implementation also uses the maximum likelihood -principle to determine \eqn{\alpha}{alpha} for a given \eqn{x_\text{min}}{xmin}; -When \eqn{x_\text{min}}{xmin} is not given in advance, the algorithm will attempt -to find its optimal value for which the \eqn{p}-value of a Kolmogorov-Smirnov -test between the fitted distribution and the original sample is the largest. -The function uses the method of Clauset, Shalizi and Newman to calculate the -parameters of the fitted distribution. See references below for the details. +This function fits a power-law distribution to a vector containing samples from a distribution (that is assumed to follow a power-law of course). +In a power-law distribution, it is generally assumed that \eqn{P(X=x)} is proportional to \eqn{x^{-\alpha}}{x^-alpha}, +where \eqn{x} is a positive number and \eqn{\alpha}{alpha} is greater than 1. In many real-world cases, +the power-law behaviour kicks in only above a threshold value \eqn{x_\text{min}}{xmin}. +The goal of this function is to determine \eqn{\alpha}{alpha} if \eqn{x_\text{min}}{xmin} is given, +or to determine \eqn{x_\text{min}}{xmin} and the corresponding value of \eqn{\alpha}{alpha}. + +\code{fit_power_law()} provides two maximum likelihood implementations. +If the \code{implementation} argument is \sQuote{\code{R.mle}}, +then the BFGS optimization (see \code{\link[stats4:mle]{stats4::mle()}}) algorithm is applied. +The additional arguments are passed to the mle function, +so it is possible to change the optimization method and/or its parameters. +This implementation can \emph{not} to fit the \eqn{x_\text{min}}{xmin} argument, +so use the \sQuote{\code{plfit}} implementation if you want to do that. + +The \sQuote{\code{plfit}} implementation also uses the maximum likelihood principle to determine \eqn{\alpha}{alpha} for a given \eqn{x_\text{min}}{xmin}; +When \eqn{x_\text{min}}{xmin} is not given in advance, +the algorithm will attempt to find its optimal value for which the \eqn{p}-value of a Kolmogorov-Smirnov test between the fitted distribution and the original sample is the largest. +The function uses the method of Clauset, Shalizi and Newman to calculate the parameters of the fitted distribution. +See references below for the details. \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} diff --git a/man/forest.fire.game.Rd b/man/forest.fire.game.Rd index 28aa158ba63..108cf736b07 100644 --- a/man/forest.fire.game.Rd +++ b/man/forest.fire.game.Rd @@ -11,8 +11,8 @@ forest.fire.game(nodes, fw.prob, bw.factor = 1, ambs = 1, directed = TRUE) \item{fw.prob}{The forward burning probability, see details below.} -\item{bw.factor}{The backward burning ratio. The backward burning -probability is calculated as \code{bw.factor*fw.prob}.} +\item{bw.factor}{The backward burning ratio. +The backward burning probability is calculated as \code{bw.factor*fw.prob}.} \item{ambs}{The number of ambassador vertices.} @@ -21,8 +21,7 @@ probability is calculated as \code{bw.factor*fw.prob}.} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{forest.fire.game()} was renamed to \code{\link[=sample_forestfire]{sample_forestfire()}} to create a more -consistent API. +\code{forest.fire.game()} was renamed to \code{\link[=sample_forestfire]{sample_forestfire()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_forest_fire_game}{\code{forest_fire_game()}} diff --git a/man/from_incidence_matrix.Rd b/man/from_incidence_matrix.Rd index 8ed4c95a284..eb344d4029f 100644 --- a/man/from_incidence_matrix.Rd +++ b/man/from_incidence_matrix.Rd @@ -12,13 +12,10 @@ from_incidence_matrix(...) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph_from_incidence_matrix()} was renamed to \code{\link[=graph_from_biadjacency_matrix]{graph_from_biadjacency_matrix()}} to create a more -consistent API. +\code{graph_from_incidence_matrix()} was renamed to \code{\link[=graph_from_biadjacency_matrix]{graph_from_biadjacency_matrix()}} to create a more consistent API. } \details{ -Some authors refer to the bipartite adjacency matrix as the -"bipartite incidence matrix". igraph 1.6.0 and later does not use -this naming to avoid confusion with the edge-vertex incidence matrix. +Some authors refer to the bipartite adjacency matrix as the "bipartite incidence matrix". igraph 1.6.0 and later does not use this naming to avoid confusion with the edge-vertex incidence matrix. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Bipartite.html#igraph_biadjacency}{\code{biadjacency()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_create}{\code{create()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_empty}{\code{empty()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_famous}{\code{famous()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Operators.html#igraph_simplify}{\code{simplify()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_simple}{\code{is_simple()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/get.adjacency.Rd b/man/get.adjacency.Rd index feb56556148..7915723d8a2 100644 --- a/man/get.adjacency.Rd +++ b/man/get.adjacency.Rd @@ -17,32 +17,28 @@ get.adjacency( \item{graph}{The graph to convert.} \item{type}{Gives how to create the adjacency matrix for undirected graphs. -It is ignored for directed graphs. Possible values: \code{upper}: the upper -right triangle of the matrix is used, \code{lower}: the lower left triangle -of the matrix is used. \code{both}: the whole matrix is used, a symmetric -matrix is returned.} +It is ignored for directed graphs. +Possible values: \code{upper}: the upper right triangle of the matrix is used, \code{lower}: the lower left triangle of the matrix is used. +\code{both}: the whole matrix is used, a symmetric matrix is returned.} -\item{attr}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{weights} instead. A -character edge attribute name is forwarded to \code{weights} unchanged; \code{NULL} -becomes \code{weights = NA}, since \code{attr = NULL} asked for a traditional -unweighted matrix while \code{weights = NULL} picks the \code{weight} attribute up.} +\item{attr}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{weights} instead. +A character edge attribute name is forwarded to \code{weights} unchanged; \code{NULL} becomes \code{weights = NA}, +since \code{attr = NULL} asked for a traditional unweighted matrix while \code{weights = NULL} picks the \code{weight} attribute up.} \item{edges}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Logical, whether to return the edge IDs in the matrix. For non-existant edges zero is returned.} -\item{names}{Logical, whether to assign row and column names -to the matrix. These are only assigned if the \code{name} vertex attribute -is present in the graph.} +\item{names}{Logical, whether to assign row and column names to the matrix. +These are only assigned if the \code{name} vertex attribute is present in the graph.} -\item{sparse}{Logical, whether to create a sparse matrix. The -\sQuote{\code{Matrix}} package must be installed for creating sparse -matrices. The default \code{NULL} uses the \code{sparsematrices} igraph option.} +\item{sparse}{Logical, whether to create a sparse matrix. +The \sQuote{\code{Matrix}} package must be installed for creating sparse matrices. +The default \code{NULL} uses the \code{sparsematrices} igraph option.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{get.adjacency()} was renamed to \code{\link[=as_adjacency_matrix]{as_adjacency_matrix()}} to create a more -consistent API. +\code{get.adjacency()} was renamed to \code{\link[=as_adjacency_matrix]{as_adjacency_matrix()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_adjacency}{\code{get_adjacency()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_adjacency_sparse}{\code{get_adjacency_sparse()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/get.adjedgelist.Rd b/man/get.adjedgelist.Rd index c09b64002a1..1f3d81a6dd5 100644 --- a/man/get.adjedgelist.Rd +++ b/man/get.adjedgelist.Rd @@ -13,20 +13,18 @@ get.adjedgelist( \arguments{ \item{graph}{The input graph.} -\item{mode}{Character scalar, it gives what kind of adjacent edges/vertices -to include in the lists. \sQuote{\code{out}} is for outgoing edges/vertices, -\sQuote{\verb{in}} is for incoming edges/vertices, \sQuote{\code{all}} is -for both. This argument is ignored for undirected graphs.} +\item{mode}{Character scalar, it gives what kind of adjacent edges/vertices to include in the lists. +\sQuote{\code{out}} is for outgoing edges/vertices, \sQuote{\verb{in}} is for incoming edges/vertices, \sQuote{\code{all}} is for both. +This argument is ignored for undirected graphs.} -\item{loops}{Character scalar, one of \code{"ignore"} (to omit loops), \code{"twice"} -(to include loop edges twice) and \code{"once"} (to include them once). \code{"twice"} -is not allowed for directed graphs and will be replaced with \code{"once"}.} +\item{loops}{Character scalar, one of \code{"ignore"} (to omit loops), +\code{"twice"} (to include loop edges twice) and \code{"once"} (to include them once). +\code{"twice"} is not allowed for directed graphs and will be replaced with \code{"once"}.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{get.adjedgelist()} was renamed to \code{\link[=as_adj_edge_list]{as_adj_edge_list()}} to create a more -consistent API. +\code{get.adjedgelist()} was renamed to \code{\link[=as_adj_edge_list]{as_adj_edge_list()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_is_directed}{\code{is_directed()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/get.adjlist.Rd b/man/get.adjlist.Rd index 841feb1311f..e2cc514f521 100644 --- a/man/get.adjlist.Rd +++ b/man/get.adjlist.Rd @@ -14,23 +14,20 @@ get.adjlist( \arguments{ \item{graph}{The input graph.} -\item{mode}{Character scalar, it gives what kind of adjacent edges/vertices -to include in the lists. \sQuote{\code{out}} is for outgoing edges/vertices, -\sQuote{\verb{in}} is for incoming edges/vertices, \sQuote{\code{all}} is -for both. This argument is ignored for undirected graphs.} +\item{mode}{Character scalar, it gives what kind of adjacent edges/vertices to include in the lists. +\sQuote{\code{out}} is for outgoing edges/vertices, \sQuote{\verb{in}} is for incoming edges/vertices, \sQuote{\code{all}} is for both. +This argument is ignored for undirected graphs.} -\item{loops}{Character scalar, one of \code{"ignore"} (to omit loops), \code{"twice"} -(to include loop edges twice) and \code{"once"} (to include them once). \code{"twice"} -is not allowed for directed graphs and will be replaced with \code{"once"}.} +\item{loops}{Character scalar, one of \code{"ignore"} (to omit loops), +\code{"twice"} (to include loop edges twice) and \code{"once"} (to include them once). +\code{"twice"} is not allowed for directed graphs and will be replaced with \code{"once"}.} -\item{multiple}{Logical, set to \code{FALSE} to use only one representative -of each set of parallel edges.} +\item{multiple}{Logical, set to \code{FALSE} to use only one representative of each set of parallel edges.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{get.adjlist()} was renamed to \code{\link[=as_adj_list]{as_adj_list()}} to create a more -consistent API. +\code{get.adjlist()} was renamed to \code{\link[=as_adj_list]{as_adj_list()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_is_directed}{\code{is_directed()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/get.all.shortest.paths.Rd b/man/get.all.shortest.paths.Rd index ac517470fcc..2a83d4160b6 100644 --- a/man/get.all.shortest.paths.Rd +++ b/man/get.all.shortest.paths.Rd @@ -15,33 +15,29 @@ get.all.shortest.paths( \arguments{ \item{graph}{The graph to work on.} -\item{from}{Numeric constant, the vertex from or to the shortest paths will -be calculated. Note that right now this is not a vector of vertex IDs, but -only a single vertex.} +\item{from}{Numeric constant, the vertex from or to the shortest paths will be calculated. +Note that right now this is not a vector of vertex IDs, but only a single vertex.} -\item{to}{Numeric vector, the vertices to which the shortest paths will be -calculated. The default \code{NULL} includes all vertices. Note that for -\code{distances()} every vertex must be included here at most once. (This -is not required for \code{shortest_paths()}.} +\item{to}{Numeric vector, the vertices to which the shortest paths will be calculated. +The default \code{NULL} includes all vertices. +Note that for \code{distances()} every vertex must be included here at most once. +(This is not required for \code{shortest_paths()}.} -\item{mode}{Character constant, gives whether the shortest paths to or from -the given vertices should be calculated for directed graphs. If \code{out} -then the shortest paths \emph{from} the vertex, if \verb{in} then \emph{to} -it will be considered. If \code{all}, the default, then the graph is treated -as undirected, i.e. edge directions are not taken into account. This -argument is ignored for undirected graphs.} +\item{mode}{Character constant, +gives whether the shortest paths to or from the given vertices should be calculated for directed graphs. +If \code{out} then the shortest paths \emph{from} the vertex, if \verb{in} then \emph{to} it will be considered. +If \code{all}, the default, then the graph is treated as undirected, i.e. edge directions are not taken into account. +This argument is ignored for undirected graphs.} -\item{weights}{Possibly a numeric vector giving edge weights. If this is -\code{NULL} and the graph has a \code{weight} edge attribute, then the -attribute is used. If this is \code{NA} then no weights are used (even if -the graph has a \code{weight} attribute). In a weighted graph, the length -of a path is the sum of the weights of its constituent edges.} +\item{weights}{Possibly a numeric vector giving edge weights. +If this is \code{NULL} and the graph has a \code{weight} edge attribute, then the attribute is used. +If this is \code{NA} then no weights are used (even if the graph has a \code{weight} attribute). +In a weighted graph, the length of a path is the sum of the weights of its constituent edges.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{get.all.shortest.paths()} was renamed to \code{\link[=all_shortest_paths]{all_shortest_paths()}} to create a more -consistent API. +\code{get.all.shortest.paths()} was renamed to \code{\link[=all_shortest_paths]{all_shortest_paths()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_all_shortest_paths_dijkstra}{\code{get_all_shortest_paths_dijkstra()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_all_shortest_paths}{\code{get_all_shortest_paths()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/get.data.frame.Rd b/man/get.data.frame.Rd index 39ab6b425b1..b8ef45f46d4 100644 --- a/man/get.data.frame.Rd +++ b/man/get.data.frame.Rd @@ -9,14 +9,13 @@ get.data.frame(x, what = c("edges", "vertices", "both")) \arguments{ \item{x}{An igraph object.} -\item{what}{Character constant, whether to return info about vertices, -edges, or both. The default is \sQuote{edges}.} +\item{what}{Character constant, whether to return info about vertices, edges, or both. +The default is \sQuote{edges}.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{get.data.frame()} was renamed to \code{\link[=as_data_frame]{as_data_frame()}} to create a more -consistent API. +\code{get.data.frame()} was renamed to \code{\link[=as_data_frame]{as_data_frame()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_edgelist}{\code{get_edgelist()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/get.diameter.Rd b/man/get.diameter.Rd index 06560f3b4d6..5b990fedfb3 100644 --- a/man/get.diameter.Rd +++ b/man/get.diameter.Rd @@ -9,24 +9,20 @@ get.diameter(graph, directed = TRUE, unconnected = TRUE, weights = NULL) \arguments{ \item{graph}{The graph to analyze.} -\item{directed}{Logical, whether directed or undirected paths are to be -considered. This is ignored for undirected graphs.} +\item{directed}{Logical, whether directed or undirected paths are to be considered. +This is ignored for undirected graphs.} -\item{unconnected}{Logical, what to do if the graph is unconnected. If -FALSE, the function will return a number that is one larger the largest -possible diameter, which is always the number of vertices. If TRUE, the -diameters of the connected components will be calculated and the largest one -will be returned.} +\item{unconnected}{Logical, what to do if the graph is unconnected. +If FALSE, the function will return a number that is one larger the largest possible diameter, which is always the number of vertices. +If TRUE, the diameters of the connected components will be calculated and the largest one will be returned.} -\item{weights}{Optional positive weight vector for calculating weighted -distances. If the graph has a \code{weight} edge attribute, then this is -used by default.} +\item{weights}{Optional positive weight vector for calculating weighted distances. +If the graph has a \code{weight} edge attribute, then this is used by default.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{get.diameter()} was renamed to \code{\link[=get_diameter]{get_diameter()}} to create a more -consistent API. +\code{get.diameter()} was renamed to \code{\link[=get_diameter]{get_diameter()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/get.edge.attribute.Rd b/man/get.edge.attribute.Rd index 5fc746f8998..d1db8167234 100644 --- a/man/get.edge.attribute.Rd +++ b/man/get.edge.attribute.Rd @@ -9,17 +9,16 @@ get.edge.attribute(graph, name, index = E(graph)) \arguments{ \item{graph}{The graph} -\item{name}{The name of the attribute to query. If missing, then -all edge attributes are returned in a list.} +\item{name}{The name of the attribute to query. +If missing, then all edge attributes are returned in a list.} -\item{index}{An optional edge sequence to query edge attributes -for a subset of edges. The default \code{NULL} selects all edges.} +\item{index}{An optional edge sequence to query edge attributes for a subset of edges. +The default \code{NULL} selects all edges.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{get.edge.attribute()} was renamed to \code{\link[=edge_attr]{edge_attr()}} to create a more -consistent API. +\code{get.edge.attribute()} was renamed to \code{\link[=edge_attr]{edge_attr()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/get.edge.ids.Rd b/man/get.edge.ids.Rd index a78552ec802..7a7f74a76e9 100644 --- a/man/get.edge.ids.Rd +++ b/man/get.edge.ids.Rd @@ -9,25 +9,22 @@ get.edge.ids(graph, vp, directed = TRUE, error = FALSE, multi = deprecated()) \arguments{ \item{graph}{The input graph.} -\item{vp}{The incident vertices, given as a two-column data frame, two-column matrix, -or vector of vertex IDs or symbolic vertex names. -For a vector, the values are interpreted pairwise, i.e. the first and second are used for -the first edge, the third and fourth for the second, etc.} +\item{vp}{The incident vertices, given as a two-column data frame, two-column matrix, or vector of vertex IDs or symbolic vertex names. +For a vector, the values are interpreted pairwise, i.e. the first and second are used for the first edge, +the third and fourth for the second, etc.} -\item{directed}{Logical, whether to consider edge directions in -directed graphs. This argument is ignored for undirected graphs.} +\item{directed}{Logical, whether to consider edge directions in directed graphs. +This argument is ignored for undirected graphs.} -\item{error}{Logical, whether to report an error if an edge is not -found in the graph. If \code{FALSE}, then no error is reported, and zero is -returned for the non-existant edge(s).} +\item{error}{Logical, whether to report an error if an edge is not found in the graph. +If \code{FALSE}, then no error is reported, and zero is returned for the non-existant edge(s).} \item{multi}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{get.edge.ids()} was renamed to \code{\link[=get_edge_ids]{get_edge_ids()}} to create a more -consistent API. +\code{get.edge.ids()} was renamed to \code{\link[=get_edge_ids]{get_edge_ids()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}} diff --git a/man/get.edgelist.Rd b/man/get.edgelist.Rd index 8cd885d99c2..1d082de40c6 100644 --- a/man/get.edgelist.Rd +++ b/man/get.edgelist.Rd @@ -9,15 +9,13 @@ get.edgelist(graph, names = TRUE) \arguments{ \item{graph}{The graph to convert.} -\item{names}{Whether to return a character matrix containing vertex -names (i.e. the \code{name} vertex attribute) if they exist or numeric -vertex IDs.} +\item{names}{Whether to return a character matrix containing vertex names (i.e. the \code{name} vertex attribute) +if they exist or numeric vertex IDs.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{get.edgelist()} was renamed to \code{\link[=as_edgelist]{as_edgelist()}} to create a more -consistent API. +\code{get.edgelist()} was renamed to \code{\link[=as_edgelist]{as_edgelist()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_edgelist}{\code{get_edgelist()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/get.graph.attribute.Rd b/man/get.graph.attribute.Rd index b63e6badcc3..8c7c431e4c0 100644 --- a/man/get.graph.attribute.Rd +++ b/man/get.graph.attribute.Rd @@ -9,13 +9,12 @@ get.graph.attribute(graph, name) \arguments{ \item{graph}{Input graph.} -\item{name}{The name of attribute to query. If missing, then all -attributes are returned in a list.} +\item{name}{The name of attribute to query. +If missing, then all attributes are returned in a list.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{get.graph.attribute()} was renamed to \code{\link[=graph_attr]{graph_attr()}} to create a more -consistent API. +\code{get.graph.attribute()} was renamed to \code{\link[=graph_attr]{graph_attr()}} to create a more consistent API. } \keyword{internal} diff --git a/man/get.incidence.Rd b/man/get.incidence.Rd index 3f230fda43f..985d4081b2b 100644 --- a/man/get.incidence.Rd +++ b/man/get.incidence.Rd @@ -7,31 +7,26 @@ get.incidence(graph, types = NULL, attr = NULL, names = TRUE, sparse = FALSE) } \arguments{ -\item{graph}{The input graph. The direction of the edges is ignored in -directed graphs.} +\item{graph}{The input graph. +The direction of the edges is ignored in directed graphs.} -\item{types}{An optional vertex type vector to use instead of the -\code{type} vertex attribute. You must supply this argument if the graph has -no \code{type} vertex attribute.} +\item{types}{An optional vertex type vector to use instead of the \code{type} vertex attribute. +You must supply this argument if the graph has no \code{type} vertex attribute.} -\item{attr}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{weights} instead. A -character edge attribute name is forwarded to \code{weights} unchanged; \code{NULL} -becomes \code{weights = NA}, since \code{attr = NULL} asked for a traditional -unweighted matrix while \code{weights = NULL} picks the \code{weight} attribute up.} +\item{attr}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{weights} instead. +A character edge attribute name is forwarded to \code{weights} unchanged; \code{NULL} becomes \code{weights = NA}, +since \code{attr = NULL} asked for a traditional unweighted matrix while \code{weights = NULL} picks the \code{weight} attribute up.} -\item{names}{Logical, if \code{TRUE} and the vertices in the graph -are named (i.e. the graph has a vertex attribute called \code{name}), then -vertex names will be added to the result as row and column names. Otherwise -the IDs of the vertices are used as row and column names.} +\item{names}{Logical, if \code{TRUE} and the vertices in the graph are named (i.e. the graph has a vertex attribute called \code{name}), +then vertex names will be added to the result as row and column names. +Otherwise the IDs of the vertices are used as row and column names.} -\item{sparse}{Logical, if it is \code{TRUE} then a sparse matrix is -created, you will need the \code{Matrix} package for this.} +\item{sparse}{Logical, if it is \code{TRUE} then a sparse matrix is created, you will need the \code{Matrix} package for this.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{get.incidence()} was renamed to \code{\link[=as_biadjacency_matrix]{as_biadjacency_matrix()}} to create a more -consistent API. +\code{get.incidence()} was renamed to \code{\link[=as_biadjacency_matrix]{as_biadjacency_matrix()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Bipartite.html#igraph_get_biadjacency}{\code{get_biadjacency()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_edgelist}{\code{get_edgelist()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/get.shortest.paths.Rd b/man/get.shortest.paths.Rd index d71de3f3a71..98264feb219 100644 --- a/man/get.shortest.paths.Rd +++ b/man/get.shortest.paths.Rd @@ -19,65 +19,55 @@ get.shortest.paths( \arguments{ \item{graph}{The graph to work on.} -\item{from}{Numeric constant, the vertex from or to the shortest paths will -be calculated. Note that right now this is not a vector of vertex IDs, but -only a single vertex.} +\item{from}{Numeric constant, the vertex from or to the shortest paths will be calculated. +Note that right now this is not a vector of vertex IDs, but only a single vertex.} -\item{to}{Numeric vector, the vertices to which the shortest paths will be -calculated. The default \code{NULL} includes all vertices. Note that for -\code{distances()} every vertex must be included here at most once. (This -is not required for \code{shortest_paths()}.} +\item{to}{Numeric vector, the vertices to which the shortest paths will be calculated. +The default \code{NULL} includes all vertices. +Note that for \code{distances()} every vertex must be included here at most once. +(This is not required for \code{shortest_paths()}.} -\item{mode}{Character constant, gives whether the shortest paths to or from -the given vertices should be calculated for directed graphs. If \code{out} -then the shortest paths \emph{from} the vertex, if \verb{in} then \emph{to} -it will be considered. If \code{all}, the default, then the graph is treated -as undirected, i.e. edge directions are not taken into account. This -argument is ignored for undirected graphs.} +\item{mode}{Character constant, +gives whether the shortest paths to or from the given vertices should be calculated for directed graphs. +If \code{out} then the shortest paths \emph{from} the vertex, if \verb{in} then \emph{to} it will be considered. +If \code{all}, the default, then the graph is treated as undirected, i.e. edge directions are not taken into account. +This argument is ignored for undirected graphs.} -\item{weights}{Possibly a numeric vector giving edge weights. If this is -\code{NULL} and the graph has a \code{weight} edge attribute, then the -attribute is used. If this is \code{NA} then no weights are used (even if -the graph has a \code{weight} attribute). In a weighted graph, the length -of a path is the sum of the weights of its constituent edges.} +\item{weights}{Possibly a numeric vector giving edge weights. +If this is \code{NULL} and the graph has a \code{weight} edge attribute, then the attribute is used. +If this is \code{NA} then no weights are used (even if the graph has a \code{weight} attribute). +In a weighted graph, the length of a path is the sum of the weights of its constituent edges.} \item{output}{Character scalar, defines how to report the shortest paths. -\dQuote{vpath} means that the vertices along the paths are reported, this -form was used prior to igraph version 0.6. \dQuote{epath} means that the -edges along the paths are reported. \dQuote{both} means that both forms are -returned, in a named list with components \dQuote{vpath} and \dQuote{epath}.} +\dQuote{vpath} means that the vertices along the paths are reported, +this form was used prior to igraph version 0.6. \dQuote{epath} means that the edges along the paths are reported. +\dQuote{both} means that both forms are returned, in a named list with components \dQuote{vpath} and \dQuote{epath}.} -\item{predecessors}{Logical, whether to return the predecessor vertex -for each vertex. The predecessor of vertex \code{i} in the tree is the -vertex from which vertex \code{i} was reached. The predecessor of the start -vertex (in the \code{from} argument) is itself by definition. If the -predecessor is zero, it means that the given vertex was not reached from the -source during the search. Note that the search terminates if all the -vertices in \code{to} are reached.} +\item{predecessors}{Logical, whether to return the predecessor vertex for each vertex. +The predecessor of vertex \code{i} in the tree is the vertex from which vertex \code{i} was reached. +The predecessor of the start vertex (in the \code{from} argument) is itself by definition. +If the predecessor is zero, it means that the given vertex was not reached from the source during the search. +Note that the search terminates if all the vertices in \code{to} are reached.} -\item{inbound.edges}{Logical, whether to return the inbound edge for -each vertex. The inbound edge of vertex \code{i} in the tree is the edge via -which vertex \code{i} was reached. The start vertex and vertices that were -not reached during the search will have zero in the corresponding entry of -the vector. Note that the search terminates if all the vertices in \code{to} -are reached.} +\item{inbound.edges}{Logical, whether to return the inbound edge for each vertex. +The inbound edge of vertex \code{i} in the tree is the edge via which vertex \code{i} was reached. +The start vertex and vertices that were not reached during the search will have zero in the corresponding entry of the vector. +Note that the search terminates if all the vertices in \code{to} are reached.} -\item{algorithm}{Which algorithm to use for the calculation. By default -igraph tries to select the fastest suitable algorithm. If there are no -weights, then an unweighted breadth-first search is used, otherwise if all -weights are positive, then Dijkstra's algorithm is used. If there are -negative weights and we do the calculation for more than 100 sources, then -Johnson's algorithm is used. Otherwise the Bellman-Ford algorithm is used. -You can override igraph's choice by explicitly giving this parameter. Note -that the igraph C core might still override your choice in obvious cases, -i.e. if there are no edge weights, then the unweighted algorithm will be -used, regardless of this argument.} +\item{algorithm}{Which algorithm to use for the calculation. +By default igraph tries to select the fastest suitable algorithm. +If there are no weights, then an unweighted breadth-first search is used, otherwise if all weights are positive, +then Dijkstra's algorithm is used. +If there are negative weights and we do the calculation for more than 100 sources, then Johnson's algorithm is used. +Otherwise the Bellman-Ford algorithm is used. +You can override igraph's choice by explicitly giving this parameter. +Note that the igraph C core might still override your choice in obvious cases, i.e. if there are no edge weights, +then the unweighted algorithm will be used, regardless of this argument.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{get.shortest.paths()} was renamed to \code{\link[=shortest_paths]{shortest_paths()}} to create a more -consistent API. +\code{get.shortest.paths()} was renamed to \code{\link[=shortest_paths]{shortest_paths()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}} diff --git a/man/get.stochastic.Rd b/man/get.stochastic.Rd index d5b47e68846..431963df8bc 100644 --- a/man/get.stochastic.Rd +++ b/man/get.stochastic.Rd @@ -11,20 +11,19 @@ get.stochastic( ) } \arguments{ -\item{graph}{The input graph. Must be of class \code{igraph}.} +\item{graph}{The input graph. +Must be of class \code{igraph}.} -\item{column.wise}{If \code{FALSE}, then the rows of the stochastic matrix -sum up to one; otherwise it is the columns.} +\item{column.wise}{If \code{FALSE}, then the rows of the stochastic matrix sum up to one; otherwise it is the columns.} -\item{sparse}{Logical, whether to return a sparse matrix. The -\code{Matrix} package is needed for sparse matrices. The default \code{NULL} uses -the \code{sparsematrices} igraph option.} +\item{sparse}{Logical, whether to return a sparse matrix. +The \code{Matrix} package is needed for sparse matrices. +The default \code{NULL} uses the \code{sparsematrices} igraph option.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{get.stochastic()} was renamed to \code{\link[=stochastic_matrix]{stochastic_matrix()}} to create a more -consistent API. +\code{get.stochastic()} was renamed to \code{\link[=stochastic_matrix]{stochastic_matrix()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_stochastic}{\code{get_stochastic()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_stochastic_sparse}{\code{get_stochastic_sparse()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/get.vertex.attribute.Rd b/man/get.vertex.attribute.Rd index b13e8f4446c..7c283097aaa 100644 --- a/man/get.vertex.attribute.Rd +++ b/man/get.vertex.attribute.Rd @@ -9,17 +9,16 @@ get.vertex.attribute(graph, name, index = V(graph)) \arguments{ \item{graph}{The graph.} -\item{name}{Name of the attribute to query. If missing, then -all vertex attributes are returned in a list.} +\item{name}{Name of the attribute to query. +If missing, then all vertex attributes are returned in a list.} -\item{index}{An optional vertex sequence to query the attribute only -for these vertices. The default \code{NULL} selects all vertices.} +\item{index}{An optional vertex sequence to query the attribute only for these vertices. +The default \code{NULL} selects all vertices.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{get.vertex.attribute()} was renamed to \code{\link[=vertex_attr]{vertex_attr()}} to create a more -consistent API. +\code{get.vertex.attribute()} was renamed to \code{\link[=vertex_attr]{vertex_attr()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/getIgraphOpt.Rd b/man/getIgraphOpt.Rd index 1c319890d4b..88dbc3c9bad 100644 --- a/man/getIgraphOpt.Rd +++ b/man/getIgraphOpt.Rd @@ -9,14 +9,12 @@ getIgraphOpt(x, default = NULL) \arguments{ \item{x}{A character string holding an option name.} -\item{default}{If the specified option is not set in the options list, this -value is returned. This facilitates retrieving an option and checking -whether it is set and setting it separately if not.} +\item{default}{If the specified option is not set in the options list, this value is returned. +This facilitates retrieving an option and checking whether it is set and setting it separately if not.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{getIgraphOpt()} was renamed to \code{\link[=igraph_opt]{igraph_opt()}} to create a more -consistent API. +\code{getIgraphOpt()} was renamed to \code{\link[=igraph_opt]{igraph_opt()}} to create a more consistent API. } \keyword{internal} diff --git a/man/get_edge_ids.Rd b/man/get_edge_ids.Rd index f7f389cd20c..03e8e004868 100644 --- a/man/get_edge_ids.Rd +++ b/man/get_edge_ids.Rd @@ -9,37 +9,32 @@ get_edge_ids(graph, vp, ..., directed = TRUE, error = FALSE) \arguments{ \item{graph}{The input graph.} -\item{vp}{The incident vertices, given as a two-column data frame, two-column matrix, -or vector of vertex IDs or symbolic vertex names. -For a vector, the values are interpreted pairwise, i.e. the first and second are used for -the first edge, the third and fourth for the second, etc.} +\item{vp}{The incident vertices, given as a two-column data frame, two-column matrix, or vector of vertex IDs or symbolic vertex names. +For a vector, the values are interpreted pairwise, i.e. the first and second are used for the first edge, +the third and fourth for the second, etc.} \item{...}{These dots are for future extensions and must be empty.} -\item{directed}{Logical, whether to consider edge directions in -directed graphs. This argument is ignored for undirected graphs.} +\item{directed}{Logical, whether to consider edge directions in directed graphs. +This argument is ignored for undirected graphs.} -\item{error}{Logical, whether to report an error if an edge is not -found in the graph. If \code{FALSE}, then no error is reported, and zero is -returned for the non-existant edge(s).} +\item{error}{Logical, whether to report an error if an edge is not found in the graph. +If \code{FALSE}, then no error is reported, and zero is returned for the non-existant edge(s).} } \value{ A numeric vector of edge IDs, one for each pair of input vertices. -If there is no edge in the input graph for a given pair of vertices, then -zero is reported. (If the \code{error} argument is \code{FALSE}.) +If there is no edge in the input graph for a given pair of vertices, then zero is reported. +(If the \code{error} argument is \code{FALSE}.) } \description{ -Find the edges in an igraph graph that have the specified end points. This -function handles multi-graph (graphs with multiple edges) and can consider -or ignore the edge directions in directed graphs. +Find the edges in an igraph graph that have the specified end points. +This function handles multi-graph (graphs with multiple edges) and can consider or ignore the edge directions in directed graphs. } \details{ -igraph vertex IDs are natural numbers, starting from one, up to the number -of vertices in the graph. Similarly, edges are also numbered from one, up to -the number of edges. +igraph vertex IDs are natural numbers, starting from one, up to the number of vertices in the graph. +Similarly, edges are also numbered from one, up to the number of edges. -This function allows finding the edges of the graph, via their incident -vertices. +This function allows finding the edges of the graph, via their incident vertices. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}} diff --git a/man/girth.Rd b/man/girth.Rd index 52a047daef1..cd4bd53a7c4 100644 --- a/man/girth.Rd +++ b/man/girth.Rd @@ -7,8 +7,8 @@ girth(graph, ..., circle = TRUE) } \arguments{ -\item{graph}{The input graph. It may be directed, but the algorithm searches -for undirected circles anyway.} +\item{graph}{The input graph. +It may be directed, but the algorithm searches for undirected circles anyway.} \item{...}{These dots are for future extensions and must be empty.} @@ -29,14 +29,13 @@ Numeric vector with the vertex IDs in the shortest circle. The girth of a graph is the length of the shortest circle in it. } \details{ -The current implementation works for undirected graphs only, directed graphs -are treated as undirected graphs. Loop edges and multiple edges are ignored. +The current implementation works for undirected graphs only, directed graphs are treated as undirected graphs. +Loop edges and multiple edges are ignored. If the graph is a forest (i.e. acyclic), then \code{Inf} is returned. -This implementation is based on Alon Itai and Michael Rodeh: Finding a -minimum circuit in a graph \emph{Proceedings of the ninth annual ACM -symposium on Theory of computing}, 1-10, 1977. The first implementation of -this function was done by Keith Briggs, thanks Keith. +This implementation is based on Alon Itai and Michael Rodeh: +Finding a minimum circuit in a graph \emph{Proceedings of the ninth annual ACM symposium on Theory of computing}, +1-10, 1977. The first implementation of this function was done by Keith Briggs, thanks Keith. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/global_efficiency.Rd b/man/global_efficiency.Rd index 2a390554fa2..fbb064d7a10 100644 --- a/man/global_efficiency.Rd +++ b/man/global_efficiency.Rd @@ -30,37 +30,33 @@ average_local_efficiency( \item{...}{These dots are for future extensions and must be empty.} -\item{weights}{The edge weights. All edge weights must be non-negative; -additionally, no edge weight may be NaN. If it is \code{NULL} (the default) -and the graph has a \code{weight} edge attribute, then it is used automatically.} +\item{weights}{The edge weights. +All edge weights must be non-negative; additionally, no edge weight may be NaN. +If it is \code{NULL} (the default) and the graph has a \code{weight} edge attribute, then it is used automatically.} -\item{directed}{Logical, whether to consider directed paths. Ignored -for undirected graphs.} +\item{directed}{Logical, whether to consider directed paths. +Ignored for undirected graphs.} \item{vids}{The vertex IDs of the vertices for which the calculation will be done. -Applies to the local efficiency calculation only. The default \code{NULL} -selects all vertices.} +Applies to the local efficiency calculation only. +The default \code{NULL} selects all vertices.} -\item{mode}{Specifies how to define the local neighborhood of a vertex in -directed graphs. \dQuote{out} considers out-neighbors only, \dQuote{in} -considers in-neighbors only, \dQuote{all} considers both.} +\item{mode}{Specifies how to define the local neighborhood of a vertex in directed graphs. +\dQuote{out} considers out-neighbors only, \dQuote{in} considers in-neighbors only, \dQuote{all} considers both.} } \value{ -For \code{global_efficiency()}, the global efficiency of the graph as a -single number. For \code{average_local_efficiency()}, the average local -efficiency of the graph as a single number. For \code{local_efficiency()}, the -local efficiency of each vertex in a vector. +For \code{global_efficiency()}, the global efficiency of the graph as a single number. +For \code{average_local_efficiency()}, the average local efficiency of the graph as a single number. +For \code{local_efficiency()}, the local efficiency of each vertex in a vector. } \description{ -These functions calculate the global or average local efficiency of a network, -or the local efficiency of every vertex in the network. See below for -definitions. +These functions calculate the global or average local efficiency of a network, or the local efficiency of every vertex in the network. +See below for definitions. } \section{Global efficiency}{ -The global efficiency of a network is defined as the average of inverse -distances between all pairs of vertices. +The global efficiency of a network is defined as the average of inverse distances between all pairs of vertices. More precisely: @@ -69,29 +65,26 @@ E_g = 1/(n*(n-1)) sum_{i!=j} 1/d_ij} where \eqn{n}{n} is the number of vertices. -The inverse distance between pairs that are not reachable from each other is -considered to be zero. For graphs with fewer than 2 vertices, NaN is returned. +The inverse distance between pairs that are not reachable from each other is considered to be zero. +For graphs with fewer than 2 vertices, NaN is returned. } \section{Local efficiency}{ -The local efficiency of a network around a vertex is defined as follows: We -remove the vertex and compute the distances (shortest path lengths) between -its neighbours through the rest of the network. The local efficiency around -the removed vertex is the average of the inverse of these distances. +The local efficiency of a network around a vertex is defined as follows: +We remove the vertex and compute the distances (shortest path lengths) between its neighbours through the rest of the network. +The local efficiency around the removed vertex is the average of the inverse of these distances. -The inverse distance between two vertices which are not reachable from each -other is considered to be zero. The local efficiency around a vertex with -fewer than two neighbours is taken to be zero by convention. +The inverse distance between two vertices which are not reachable from each other is considered to be zero. +The local efficiency around a vertex with fewer than two neighbours is taken to be zero by convention. } \section{Average local efficiency}{ -The average local efficiency of a network is simply the arithmetic mean of -the local efficiencies of all the vertices; see the definition for local -efficiency above. +The average local efficiency of a network is simply the arithmetic mean of the local efficiencies of all the vertices; +see the definition for local efficiency above. } \section{Related documentation in the C library}{ diff --git a/man/graph.Rd b/man/graph.Rd index 086f400d012..c74c5199289 100644 --- a/man/graph.Rd +++ b/man/graph.Rd @@ -15,36 +15,29 @@ graph( ) } \arguments{ -\item{edges}{A vector defining the edges, the first edge points -from the first element to the second, the second edge from the third -to the fourth, etc. For a numeric vector, these are interpreted -as internal vertex IDs. For character vectors, they are interpreted -as vertex names. +\item{edges}{A vector defining the edges, the first edge points from the first element to the second, +the second edge from the third to the fourth, etc. For a numeric vector, these are interpreted as internal vertex IDs. +For character vectors, they are interpreted as vertex names. -Alternatively, this can be a character scalar, the name of a -notable graph. See Notable graphs below. The name is case -insensitive. +Alternatively, this can be a character scalar, the name of a notable graph. +See Notable graphs below. +The name is case insensitive. -Starting from igraph 0.8.0, you can also include literals here, -via igraph's formula notation (see \code{\link[=graph_from_literal]{graph_from_literal()}}). -In this case, the first term of the formula has to start with -a \sQuote{\code{~}} character, just like regular formulae in R. +Starting from igraph 0.8.0, you can also include literals here, via igraph's formula notation (see \code{\link[=graph_from_literal]{graph_from_literal()}}). +In this case, the first term of the formula has to start with a \sQuote{\code{~}} character, just like regular formulae in R. See examples below.} -\item{...}{For \code{make_graph()}: extra arguments for the case when the -graph is given via a literal, see \code{\link[=graph_from_literal]{graph_from_literal()}}. -For \code{directed_graph()} and \code{undirected_graph()}: -Passed to \code{make_directed_graph()} or \code{make_undirected_graph()}.} +\item{...}{For \code{make_graph()}: extra arguments for the case when the graph is given via a literal, see \code{\link[=graph_from_literal]{graph_from_literal()}}. +For \code{directed_graph()} and \code{undirected_graph()}: Passed to \code{make_directed_graph()} or \code{make_undirected_graph()}.} -\item{n}{The number of vertices in the graph. This argument is -ignored (with a warning) if \code{edges} are symbolic vertex names. It -is also ignored if there is a bigger vertex ID in \code{edges}. This -means that for this function it is safe to supply zero here if the -vertex with the largest ID is not an isolate. The default \code{NULL} uses -the largest vertex ID in \code{edges}.} +\item{n}{The number of vertices in the graph. +This argument is ignored (with a warning) if \code{edges} are symbolic vertex names. +It is also ignored if there is a bigger vertex ID in \code{edges}. +This means that for this function it is safe to supply zero here if the vertex with the largest ID is not an isolate. +The default \code{NULL} uses the largest vertex ID in \code{edges}.} -\item{isolates}{Character vector, names of isolate vertices, -for symbolic edge lists. It is ignored for numeric edge lists.} +\item{isolates}{Character vector, names of isolate vertices, for symbolic edge lists. +It is ignored for numeric edge lists.} \item{directed}{Whether to create a directed graph.} @@ -56,8 +49,7 @@ Do not give both of them.} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph()} was renamed to \code{\link[=make_graph]{make_graph()}} to create a more -consistent API. +\code{graph()} was renamed to \code{\link[=make_graph]{make_graph()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_create}{\code{create()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_famous}{\code{famous()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_empty}{\code{empty()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Operators.html#igraph_simplify}{\code{simplify()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_simple}{\code{is_simple()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/graph.adhesion.Rd b/man/graph.adhesion.Rd index 56d7cfb3214..afd2db5d861 100644 --- a/man/graph.adhesion.Rd +++ b/man/graph.adhesion.Rd @@ -9,19 +9,17 @@ graph.adhesion(graph, checks = TRUE) \arguments{ \item{graph}{The input graph.} -\item{checks}{Logical. Whether to check that the graph is connected -and also the degree of the vertices. If the graph is not (strongly) -connected then the connectivity is obviously zero. Otherwise if the minimum -degree is one then the edge connectivity is also one. It is a good idea to -perform these checks, as they can be done quickly compared to the -connectivity calculation itself. They were suggested by Peter McMahan, -thanks Peter.} +\item{checks}{Logical. +Whether to check that the graph is connected and also the degree of the vertices. +If the graph is not (strongly) connected then the connectivity is obviously zero. +Otherwise if the minimum degree is one then the edge connectivity is also one. +It is a good idea to perform these checks, as they can be done quickly compared to the connectivity calculation itself. +They were suggested by Peter McMahan, thanks Peter.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.adhesion()} was renamed to \code{\link[=adhesion]{adhesion()}} to create a more -consistent API. +\code{graph.adhesion()} was renamed to \code{\link[=adhesion]{adhesion()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Flows.html#igraph_adhesion}{\code{adhesion()}} diff --git a/man/graph.adjacency.Rd b/man/graph.adjacency.Rd index 31f01e715c9..ebb3e924b06 100644 --- a/man/graph.adjacency.Rd +++ b/man/graph.adjacency.Rd @@ -14,45 +14,37 @@ graph.adjacency( ) } \arguments{ -\item{adjmatrix}{A square adjacency matrix. From igraph version 0.5.1 this -can be a sparse matrix created with the \code{Matrix} package.} +\item{adjmatrix}{A square adjacency matrix. +From igraph version 0.5.1 this can be a sparse matrix created with the \code{Matrix} package.} -\item{mode}{Character scalar, specifies how igraph should interpret the -supplied matrix. See also the \code{weighted} argument, the interpretation -depends on that too. Possible values are: \code{directed}, -\code{undirected}, \code{upper}, \code{lower}, \code{max}, \code{min}, -\code{plus}. See details below.} +\item{mode}{Character scalar, specifies how igraph should interpret the supplied matrix. +See also the \code{weighted} argument, the interpretation depends on that too. +Possible values are: \code{directed}, \code{undirected}, \code{upper}, \code{lower}, \code{max}, \code{min}, \code{plus}. +See details below.} -\item{weighted}{This argument specifies whether to create a weighted graph -from an adjacency matrix. If it is \code{NULL} then an unweighted graph is -created and the elements of the adjacency matrix gives the number of edges -between the vertices. If it is a character constant then for every non-zero -matrix entry an edge is created and the value of the entry is added as an -edge attribute named by the \code{weighted} argument. If it is \code{TRUE} -then a weighted graph is created and the name of the edge attribute will be -\code{weight}. See also details below.} +\item{weighted}{This argument specifies whether to create a weighted graph from an adjacency matrix. +If it is \code{NULL} then an unweighted graph is created and the elements of the adjacency matrix gives the number of edges between the vertices. +If it is a character constant then for every non-zero matrix entry an edge is created and the value of the entry is added as an edge attribute named by the \code{weighted} argument. +If it is \code{TRUE} then a weighted graph is created and the name of the edge attribute will be \code{weight}. +See also details below.} -\item{diag}{Logical, whether to include the diagonal of the matrix in -the calculation. If this is \code{FALSE} then the diagonal is zerod out -first.} +\item{diag}{Logical, whether to include the diagonal of the matrix in the calculation. +If this is \code{FALSE} then the diagonal is zerod out first.} -\item{add.colnames}{Character scalar, whether to add the column names as -vertex attributes. If it is \code{NULL} (the default) then, if -present, column names are added as vertex attribute \sQuote{name}. If -\code{NA} or \code{FALSE} then they will not be added. If a character constant, -then it gives the name of the vertex attribute to add.} +\item{add.colnames}{Character scalar, whether to add the column names as vertex attributes. +If it is \code{NULL} (the default) then, if present, column names are added as vertex attribute \sQuote{name}. +If \code{NA} or \code{FALSE} then they will not be added. +If a character constant, then it gives the name of the vertex attribute to add.} -\item{add.rownames}{Character scalar, whether to add the row names as vertex -attributes. Possible values the same as the previous argument. By default -row names are not added. If \sQuote{\code{add.rownames}} and -\sQuote{\code{add.colnames}} specify the same vertex attribute, then the -former is ignored.} +\item{add.rownames}{Character scalar, whether to add the row names as vertex attributes. +Possible values the same as the previous argument. +By default row names are not added. +If \sQuote{\code{add.rownames}} and \sQuote{\code{add.colnames}} specify the same vertex attribute, then the former is ignored.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.adjacency()} was renamed to \code{\link[=graph_from_adjacency_matrix]{graph_from_adjacency_matrix()}} to create a more -consistent API. +\code{graph.adjacency()} was renamed to \code{\link[=graph_from_adjacency_matrix]{graph_from_adjacency_matrix()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_adjacency}{\code{adjacency()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_weighted_adjacency}{\code{weighted_adjacency()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_create}{\code{create()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_empty}{\code{empty()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_famous}{\code{famous()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Operators.html#igraph_simplify}{\code{simplify()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_simple}{\code{is_simple()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/graph.adjlist.Rd b/man/graph.adjlist.Rd index 601a9a6e650..69bb7d36078 100644 --- a/man/graph.adjlist.Rd +++ b/man/graph.adjlist.Rd @@ -7,28 +7,23 @@ graph.adjlist(adjlist, mode = c("out", "in", "all", "total"), duplicate = TRUE) } \arguments{ -\item{adjlist}{The adjacency list. It should be consistent, i.e. the maximum -throughout all vectors in the list must be less than the number of vectors -(=the number of vertices in the graph).} +\item{adjlist}{The adjacency list. +It should be consistent, +i.e. the maximum throughout all vectors in the list must be less than the number of vectors (=the number of vertices in the graph).} -\item{mode}{Character scalar, it specifies whether the graph to create is -undirected (\sQuote{all} or \sQuote{total}) or directed; and in the latter -case, whether it contains the outgoing (\sQuote{out}) or the incoming -(\sQuote{in}) neighbors of the vertices.} +\item{mode}{Character scalar, it specifies whether the graph to create is undirected (\sQuote{all} or \sQuote{total}) or directed; +and in the latter case, whether it contains the outgoing (\sQuote{out}) or the incoming (\sQuote{in}) neighbors of the vertices.} -\item{duplicate}{Logical. For undirected graphs it gives whether -edges are included in the list twice. E.g. if it is \code{TRUE} then for an -undirected \code{{A,B}} edge \code{graph_from_adj_list()} expects \code{A} -included in the neighbors of \code{B} and \code{B} to be included in the -neighbors of \code{A}. +\item{duplicate}{Logical. +For undirected graphs it gives whether edges are included in the list twice. +E.g. if it is \code{TRUE} then for an undirected \code{{A,B}} edge \code{graph_from_adj_list()} expects \code{A} included in the neighbors of \code{B} and \code{B} to be included in the neighbors of \code{A}. This argument is ignored if \code{mode} is \code{out} or \verb{in}.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.adjlist()} was renamed to \code{\link[=graph_from_adj_list]{graph_from_adj_list()}} to create a more -consistent API. +\code{graph.adjlist()} was renamed to \code{\link[=graph_from_adj_list]{graph_from_adj_list()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_adjlist}{\code{adjlist()}} diff --git a/man/graph.atlas.Rd b/man/graph.atlas.Rd index b65b20b417f..de51e65ab5b 100644 --- a/man/graph.atlas.Rd +++ b/man/graph.atlas.Rd @@ -12,8 +12,7 @@ graph.atlas(n) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.atlas()} was renamed to \code{\link[=graph_from_atlas]{graph_from_atlas()}} to create a more -consistent API. +\code{graph.atlas()} was renamed to \code{\link[=graph_from_atlas]{graph_from_atlas()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_atlas}{\code{atlas()}} diff --git a/man/graph.automorphisms.Rd b/man/graph.automorphisms.Rd index bf5a5676697..c988fd6d2b7 100644 --- a/man/graph.automorphisms.Rd +++ b/man/graph.automorphisms.Rd @@ -13,16 +13,14 @@ graph.automorphisms( \arguments{ \item{graph}{The input graph, it is treated as undirected.} -\item{colors}{The colors of the individual vertices of the graph; only -vertices having the same color are allowed to match each other in an -automorphism. When omitted, igraph uses the \code{color} attribute of the -vertices, or, if there is no such vertex attribute, it simply assumes that -all vertices have the same color. Pass NULL explicitly if the graph has a -\code{color} vertex attribute but you do not want to use it.} +\item{colors}{The colors of the individual vertices of the graph; +only vertices having the same color are allowed to match each other in an automorphism. +When omitted, igraph uses the \code{color} attribute of the vertices, or, if there is no such vertex attribute, +it simply assumes that all vertices have the same color. +Pass NULL explicitly if the graph has a \code{color} vertex attribute but you do not want to use it.} -\item{sh}{The splitting heuristics for the BLISS algorithm. Possible values -are: -\sQuote{\code{f}}: +\item{sh}{The splitting heuristics for the BLISS algorithm. +Possible values are: \sQuote{\code{f}}: first non-singleton cell, \sQuote{\code{fl}}: first largest non-singleton cell, @@ -40,8 +38,7 @@ first smallest maximally non-trivially connected non-singleton cell.} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.automorphisms()} was renamed to \code{\link[=count_automorphisms]{count_automorphisms()}} to create a more -consistent API. +\code{graph.automorphisms()} was renamed to \code{\link[=count_automorphisms]{count_automorphisms()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Isomorphism.html#igraph_count_automorphisms}{\code{count_automorphisms()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/graph.bfs.Rd b/man/graph.bfs.Rd index 56642407ca8..9479a54da96 100644 --- a/man/graph.bfs.Rd +++ b/man/graph.bfs.Rd @@ -25,25 +25,23 @@ graph.bfs( \arguments{ \item{graph}{The input graph.} -\item{root}{Numeric vector, usually of length one. The root vertex, or root -vertices to start the search from. When several roots are given, they are -considered in the order they appear. If a root vertex was already reached -while searching from an earlier root, no separate search is started from -it, so it keeps the distance it was first found at rather than \code{0}.} +\item{root}{Numeric vector, usually of length one. +The root vertex, or root vertices to start the search from. +When several roots are given, they are considered in the order they appear. +If a root vertex was already reached while searching from an earlier root, no separate search is started from it, +so it keeps the distance it was first found at rather than \code{0}.} \item{mode}{For directed graphs specifies the type of edges to follow. -\sQuote{out} follows outgoing, \sQuote{in} incoming edges. \sQuote{all} -ignores edge directions completely. \sQuote{total} is a synonym for -\sQuote{all}. This argument is ignored for undirected graphs.} +\sQuote{out} follows outgoing, \sQuote{in} incoming edges. +\sQuote{all} ignores edge directions completely. +\sQuote{total} is a synonym for \sQuote{all}. +This argument is ignored for undirected graphs.} -\item{unreachable}{Logical, whether the search should visit the -vertices that are unreachable from the given root vertex (or vertices). If -\code{TRUE}, then additional searches are performed until all vertices are -visited.} +\item{unreachable}{Logical, whether the search should visit the vertices that are unreachable from the given root vertex (or vertices). +If \code{TRUE}, then additional searches are performed until all vertices are visited.} -\item{restricted}{\code{NULL} (=no restriction), or a vector of vertices -(IDs or symbolic names). In the latter case, the search is restricted to the -given vertices.} +\item{restricted}{\code{NULL} (=no restriction), or a vector of vertices (IDs or symbolic names). +In the latter case, the search is restricted to the given vertices.} \item{order}{Logical, whether to return the ordering of the vertices.} @@ -51,18 +49,16 @@ given vertices.} \item{father}{Logical, whether to return the father of the vertices.} -\item{pred}{Logical, whether to return the predecessors of the -vertices.} +\item{pred}{Logical, whether to return the predecessors of the vertices.} -\item{succ}{Logical, whether to return the successors of the -vertices.} +\item{succ}{Logical, whether to return the successors of the vertices.} -\item{dist}{Logical, whether to return the distance from the root of -the search tree.} +\item{dist}{Logical, whether to return the distance from the root of the search tree.} -\item{callback}{Callback function. This is called whenever a vertex is visited. -The callback function should return \code{FALSE} to continue the search -or \code{TRUE} to stop it. See details below. +\item{callback}{Callback function. +This is called whenever a vertex is visited. +The callback function should return \code{FALSE} to continue the search or \code{TRUE} to stop it. +See details below. Default: \code{NULL}.} \item{extra}{Additional argument to supply to the callback function.} @@ -70,14 +66,12 @@ Default: \code{NULL}.} \item{rho}{The environment in which the callback function is evaluated. The default \code{NULL} uses the caller's environment.} -\item{neimode}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} This argument is deprecated -from igraph 1.3.0; use \code{mode} instead.} +\item{neimode}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} This argument is deprecated from igraph 1.3.0; use \code{mode} instead.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.bfs()} was renamed to \code{\link[=bfs]{bfs()}} to create a more -consistent API. +\code{graph.bfs()} was renamed to \code{\link[=bfs]{bfs()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/graph.bipartite.Rd b/man/graph.bipartite.Rd index 3e95f20c385..57e46f913bb 100644 --- a/man/graph.bipartite.Rd +++ b/man/graph.bipartite.Rd @@ -7,25 +7,22 @@ graph.bipartite(types, edges, directed = FALSE) } \arguments{ -\item{types}{A vector giving the vertex types. It will be coerced into -boolean. The length of the vector gives the number of vertices in the graph. -When the vector is a named vector, the names will be attached to the graph -as the \code{name} vertex attribute.} +\item{types}{A vector giving the vertex types. +It will be coerced into boolean. +The length of the vector gives the number of vertices in the graph. +When the vector is a named vector, the names will be attached to the graph as the \code{name} vertex attribute.} -\item{edges}{A vector giving the edges of the graph, the same way as for the -regular \code{\link[=make_graph]{make_graph()}} function. It is checked that the edges indeed -connect vertices of different kind, according to the supplied \code{types} -vector. The vector may be a string vector if \code{types} is a named vector.} +\item{edges}{A vector giving the edges of the graph, the same way as for the regular \code{\link[=make_graph]{make_graph()}} function. +It is checked that the edges indeed connect vertices of different kind, according to the supplied \code{types} vector. +The vector may be a string vector if \code{types} is a named vector.} -\item{directed}{Logical, whether to create a directed graph. Note -that by default undirected graphs are created, as this is more common for -bipartite graphs.} +\item{directed}{Logical, whether to create a directed graph. +Note that by default undirected graphs are created, as this is more common for bipartite graphs.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.bipartite()} was renamed to \code{\link[=make_bipartite_graph]{make_bipartite_graph()}} to create a more -consistent API. +\code{graph.bipartite()} was renamed to \code{\link[=make_bipartite_graph]{make_bipartite_graph()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Bipartite.html#igraph_create_bipartite}{\code{create_bipartite()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/graph.cohesion.Rd b/man/graph.cohesion.Rd index 15a340b47d0..8376f60bd34 100644 --- a/man/graph.cohesion.Rd +++ b/man/graph.cohesion.Rd @@ -14,7 +14,6 @@ graph.cohesion(x, ...) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.cohesion()} was renamed to \code{\link[=cohesion]{cohesion()}} to create a more -consistent API. +\code{graph.cohesion()} was renamed to \code{\link[=cohesion]{cohesion()}} to create a more consistent API. } \keyword{internal} diff --git a/man/graph.complementer.Rd b/man/graph.complementer.Rd index d11ae057ab4..65910d6971b 100644 --- a/man/graph.complementer.Rd +++ b/man/graph.complementer.Rd @@ -14,8 +14,7 @@ graph.complementer(graph, loops = FALSE) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.complementer()} was renamed to \code{\link[=complementer]{complementer()}} to create a more -consistent API. +\code{graph.complementer()} was renamed to \code{\link[=complementer]{complementer()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Operators.html#igraph_complementer}{\code{complementer()}} diff --git a/man/graph.compose.Rd b/man/graph.compose.Rd index 7b22c646349..64f296690fd 100644 --- a/man/graph.compose.Rd +++ b/man/graph.compose.Rd @@ -11,17 +11,15 @@ graph.compose(g1, g2, byname = "auto") \item{g2}{The second input graph.} -\item{byname}{A Logical, or the character scalar \code{auto}. Whether -to perform the operation based on symbolic vertex names. If it is -\code{auto}, that means \code{TRUE} if both graphs are named and -\code{FALSE} otherwise. A warning is generated if \code{auto} and one graph, -but not both graphs are named.} +\item{byname}{A Logical, or the character scalar \code{auto}. +Whether to perform the operation based on symbolic vertex names. +If it is \code{auto}, that means \code{TRUE} if both graphs are named and \code{FALSE} otherwise. +A warning is generated if \code{auto} and one graph, but not both graphs are named.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.compose()} was renamed to \code{\link[=compose]{compose()}} to create a more -consistent API. +\code{graph.compose()} was renamed to \code{\link[=compose]{compose()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Isomorphism.html#igraph_permute_vertices}{\code{permute_vertices()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/graph.coreness.Rd b/man/graph.coreness.Rd index 2c224282090..eddc30825ef 100644 --- a/man/graph.coreness.Rd +++ b/man/graph.coreness.Rd @@ -9,16 +9,15 @@ graph.coreness(graph, mode = c("all", "out", "in")) \arguments{ \item{graph}{The input graph, it can be directed or undirected} -\item{mode}{The type of the core in directed graphs. Character constant, -possible values: \verb{in}: in-cores are computed, \code{out}: out-cores are -computed, \code{all}: the corresponding undirected graph is considered. This -argument is ignored for undirected graphs.} +\item{mode}{The type of the core in directed graphs. +Character constant, possible values: \verb{in}: in-cores are computed, \code{out}: out-cores are computed, \code{all}: +the corresponding undirected graph is considered. +This argument is ignored for undirected graphs.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.coreness()} was renamed to \code{\link[=coreness]{coreness()}} to create a more -consistent API. +\code{graph.coreness()} was renamed to \code{\link[=coreness]{coreness()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_coreness}{\code{coreness()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/graph.data.frame.Rd b/man/graph.data.frame.Rd index 65b57fb2366..55511d6eb5a 100644 --- a/man/graph.data.frame.Rd +++ b/man/graph.data.frame.Rd @@ -7,22 +7,20 @@ graph.data.frame(d, directed = TRUE, vertices = NULL) } \arguments{ -\item{d}{A data frame containing a symbolic edge list in the first two -columns. Additional columns are considered as edge attributes. Since -version 0.7 this argument is coerced to a data frame with -\code{as.data.frame}.} +\item{d}{A data frame containing a symbolic edge list in the first two columns. +Additional columns are considered as edge attributes. +Since version 0.7 this argument is coerced to a data frame with \code{as.data.frame}.} \item{directed}{Logical, whether or not to create a directed graph.} -\item{vertices}{A data frame with vertex metadata, or \code{NULL}. See -details below. Since version 0.7 this argument is coerced to a data frame -with \code{as.data.frame}, if not \code{NULL}.} +\item{vertices}{A data frame with vertex metadata, or \code{NULL}. +See details below. +Since version 0.7 this argument is coerced to a data frame with \code{as.data.frame}, if not \code{NULL}.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.data.frame()} was renamed to \code{\link[=graph_from_data_frame]{graph_from_data_frame()}} to create a more -consistent API. +\code{graph.data.frame()} was renamed to \code{\link[=graph_from_data_frame]{graph_from_data_frame()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_add_vertices}{\code{add_vertices()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_empty}{\code{empty()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/graph.de.bruijn.Rd b/man/graph.de.bruijn.Rd index 48f3160ed40..aa808d7c331 100644 --- a/man/graph.de.bruijn.Rd +++ b/man/graph.de.bruijn.Rd @@ -7,15 +7,16 @@ graph.de.bruijn(m, n) } \arguments{ -\item{m}{Integer scalar, the size of the alphabet. See details below.} +\item{m}{Integer scalar, the size of the alphabet. +See details below.} -\item{n}{Integer scalar, the length of the labels. See details below.} +\item{n}{Integer scalar, the length of the labels. +See details below.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.de.bruijn()} was renamed to \code{\link[=make_de_bruijn_graph]{make_de_bruijn_graph()}} to create a more -consistent API. +\code{graph.de.bruijn()} was renamed to \code{\link[=make_de_bruijn_graph]{make_de_bruijn_graph()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_de_bruijn}{\code{de_bruijn()}} diff --git a/man/graph.density.Rd b/man/graph.density.Rd index e4ab75e651b..b8759135194 100644 --- a/man/graph.density.Rd +++ b/man/graph.density.Rd @@ -10,15 +10,13 @@ graph.density(graph, loops = FALSE) \item{graph}{The input graph.} \item{loops}{Logical, whether loop edges may exist in the graph. -This affects the calculation of the largest possible number of edges in the -graph. If this parameter is set to FALSE yet the graph contains self-loops, -the result will not be meaningful.} +This affects the calculation of the largest possible number of edges in the graph. +If this parameter is set to FALSE yet the graph contains self-loops, the result will not be meaningful.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.density()} was renamed to \code{\link[=edge_density]{edge_density()}} to create a more -consistent API. +\code{graph.density()} was renamed to \code{\link[=edge_density]{edge_density()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_density}{\code{density()}} diff --git a/man/graph.dfs.Rd b/man/graph.dfs.Rd index cdb45188a12..7eed8bbb00a 100644 --- a/man/graph.dfs.Rd +++ b/man/graph.dfs.Rd @@ -26,33 +26,30 @@ graph.dfs( \item{root}{The single root vertex to start the search from.} \item{mode}{For directed graphs specifies the type of edges to follow. -\sQuote{out} follows outgoing, \sQuote{in} incoming edges. \sQuote{all} -ignores edge directions completely. \sQuote{total} is a synonym for -\sQuote{all}. This argument is ignored for undirected graphs.} +\sQuote{out} follows outgoing, \sQuote{in} incoming edges. +\sQuote{all} ignores edge directions completely. +\sQuote{total} is a synonym for \sQuote{all}. +This argument is ignored for undirected graphs.} -\item{unreachable}{Logical, whether the search should visit the -vertices that are unreachable from the given root vertex (or vertices). If -\code{TRUE}, then additional searches are performed until all vertices are -visited.} +\item{unreachable}{Logical, whether the search should visit the vertices that are unreachable from the given root vertex (or vertices). +If \code{TRUE}, then additional searches are performed until all vertices are visited.} -\item{order}{Logical, whether to return the DFS ordering of the -vertices.} +\item{order}{Logical, whether to return the DFS ordering of the vertices.} -\item{order.out}{Logical, whether to return the ordering based on -leaving the subtree of the vertex.} +\item{order.out}{Logical, whether to return the ordering based on leaving the subtree of the vertex.} \item{father}{Logical, whether to return the father of the vertices.} -\item{dist}{Logical, whether to return the distance from the root of -the search tree.} +\item{dist}{Logical, whether to return the distance from the root of the search tree.} \item{in.callback}{Callback function. -This is called whenever a vertex is visited. See details below. +This is called whenever a vertex is visited. +See details below. Default: \code{NULL}.} \item{out.callback}{Callback function. -This is called whenever the subtree of a vertex is completed by the -algorithm. See details below. +This is called whenever the subtree of a vertex is completed by the algorithm. +See details below. Default: \code{NULL}.} \item{extra}{Additional argument to supply to the callback function.} @@ -60,14 +57,12 @@ Default: \code{NULL}.} \item{rho}{The environment in which the callback function is evaluated. The default \code{NULL} uses the caller's environment.} -\item{neimode}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} This argument is deprecated from igraph 1.3.0; use -\code{mode} instead.} +\item{neimode}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} This argument is deprecated from igraph 1.3.0; use \code{mode} instead.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.dfs()} was renamed to \code{\link[=dfs]{dfs()}} to create a more -consistent API. +\code{graph.dfs()} was renamed to \code{\link[=dfs]{dfs()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/graph.difference.Rd b/man/graph.difference.Rd index f266a7b110c..02069e28962 100644 --- a/man/graph.difference.Rd +++ b/man/graph.difference.Rd @@ -7,13 +7,11 @@ graph.difference(...) } \arguments{ -\item{...}{Arguments, their number and interpretation depends on -the function that implements \code{difference()}.} +\item{...}{Arguments, their number and interpretation depends on the function that implements \code{difference()}.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.difference()} was renamed to \code{\link[=difference]{difference()}} to create a more -consistent API. +\code{graph.difference()} was renamed to \code{\link[=difference]{difference()}} to create a more consistent API. } \keyword{internal} diff --git a/man/graph.disjoint.union.Rd b/man/graph.disjoint.union.Rd index fcd7fbb8902..75119e27aed 100644 --- a/man/graph.disjoint.union.Rd +++ b/man/graph.disjoint.union.Rd @@ -12,8 +12,7 @@ graph.disjoint.union(...) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.disjoint.union()} was renamed to \code{\link[=disjoint_union]{disjoint_union()}} to create a more -consistent API. +\code{graph.disjoint.union()} was renamed to \code{\link[=disjoint_union]{disjoint_union()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/graph.diversity.Rd b/man/graph.diversity.Rd index bd1ca92af59..fec7280c8f3 100644 --- a/man/graph.diversity.Rd +++ b/man/graph.diversity.Rd @@ -7,11 +7,12 @@ graph.diversity(graph, weights = NULL, vids = V(graph)) } \arguments{ -\item{graph}{The input graph. Edge directions are ignored.} +\item{graph}{The input graph. +Edge directions are ignored.} -\item{weights}{\code{NULL}, or the vector of edge weights to use for the -computation. If \code{NULL}, then the \sQuote{weight} attibute is used. Note -that this measure is not defined for unweighted graphs.} +\item{weights}{\code{NULL}, or the vector of edge weights to use for the computation. +If \code{NULL}, then the \sQuote{weight} attibute is used. +Note that this measure is not defined for unweighted graphs.} \item{vids}{The vertex IDs for which to calculate the measure. The default \code{NULL} selects all vertices.} @@ -19,8 +20,7 @@ The default \code{NULL} selects all vertices.} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.diversity()} was renamed to \code{\link[=diversity]{diversity()}} to create a more -consistent API. +\code{graph.diversity()} was renamed to \code{\link[=diversity]{diversity()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_diversity}{\code{diversity()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/graph.edgelist.Rd b/man/graph.edgelist.Rd index df5d093e878..85eae208eed 100644 --- a/man/graph.edgelist.Rd +++ b/man/graph.edgelist.Rd @@ -14,8 +14,7 @@ graph.edgelist(el, directed = TRUE) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.edgelist()} was renamed to \code{\link[=graph_from_edgelist]{graph_from_edgelist()}} to create a more -consistent API. +\code{graph.edgelist()} was renamed to \code{\link[=graph_from_edgelist]{graph_from_edgelist()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_create}{\code{create()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_empty}{\code{empty()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_famous}{\code{famous()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Operators.html#igraph_simplify}{\code{simplify()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_simple}{\code{is_simple()}} diff --git a/man/graph.eigen.Rd b/man/graph.eigen.Rd index ebd3bb38c1c..3fba1a85a43 100644 --- a/man/graph.eigen.Rd +++ b/man/graph.eigen.Rd @@ -14,20 +14,19 @@ graph.eigen( \arguments{ \item{graph}{The input graph, can be directed or undirected.} -\item{algorithm}{The algorithm to use. Currently only \code{arpack} is -implemented, which uses the ARPACK solver. See also \code{\link[=arpack]{arpack()}}.} +\item{algorithm}{The algorithm to use. +Currently only \code{arpack} is implemented, which uses the ARPACK solver. +See also \code{\link[=arpack]{arpack()}}.} -\item{which}{A list to specify which eigenvalues and eigenvectors to -calculate. By default the leading (i.e. largest magnitude) eigenvalue and -the corresponding eigenvector is calculated.} +\item{which}{A list to specify which eigenvalues and eigenvectors to calculate. +By default the leading (i.e. largest magnitude) eigenvalue and the corresponding eigenvector is calculated.} -\item{options}{Options for the ARPACK solver. See -\code{\link[=arpack_defaults]{arpack_defaults()}}.} +\item{options}{Options for the ARPACK solver. +See \code{\link[=arpack_defaults]{arpack_defaults()}}.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.eigen()} was renamed to \code{\link[=spectrum]{spectrum()}} to create a more -consistent API. +\code{graph.eigen()} was renamed to \code{\link[=spectrum]{spectrum()}} to create a more consistent API. } \keyword{internal} diff --git a/man/graph.empty.Rd b/man/graph.empty.Rd index 651e243fd38..7baadcc3576 100644 --- a/man/graph.empty.Rd +++ b/man/graph.empty.Rd @@ -14,8 +14,7 @@ graph.empty(n = 0, directed = TRUE) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.empty()} was renamed to \code{\link[=make_empty_graph]{make_empty_graph()}} to create a more -consistent API. +\code{graph.empty()} was renamed to \code{\link[=make_empty_graph]{make_empty_graph()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_empty}{\code{empty()}} diff --git a/man/graph.extended.chordal.ring.Rd b/man/graph.extended.chordal.ring.Rd index e5baf01ddd5..3b27b0b2f25 100644 --- a/man/graph.extended.chordal.ring.Rd +++ b/man/graph.extended.chordal.ring.Rd @@ -9,16 +9,15 @@ graph.extended.chordal.ring(n, w, directed = FALSE) \arguments{ \item{n}{The number of vertices.} -\item{w}{A matrix which specifies the extended chordal ring. See -details below.} +\item{w}{A matrix which specifies the extended chordal ring. +See details below.} \item{directed}{Logical, whether or not to create a directed graph.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.extended.chordal.ring()} was renamed to \code{\link[=make_chordal_ring]{make_chordal_ring()}} to create a more -consistent API. +\code{graph.extended.chordal.ring()} was renamed to \code{\link[=make_chordal_ring]{make_chordal_ring()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_extended_chordal_ring}{\code{extended_chordal_ring()}} diff --git a/man/graph.famous.Rd b/man/graph.famous.Rd index 27e23a25139..5070bc99045 100644 --- a/man/graph.famous.Rd +++ b/man/graph.famous.Rd @@ -15,36 +15,29 @@ graph.famous( ) } \arguments{ -\item{edges}{A vector defining the edges, the first edge points -from the first element to the second, the second edge from the third -to the fourth, etc. For a numeric vector, these are interpreted -as internal vertex IDs. For character vectors, they are interpreted -as vertex names. +\item{edges}{A vector defining the edges, the first edge points from the first element to the second, +the second edge from the third to the fourth, etc. For a numeric vector, these are interpreted as internal vertex IDs. +For character vectors, they are interpreted as vertex names. -Alternatively, this can be a character scalar, the name of a -notable graph. See Notable graphs below. The name is case -insensitive. +Alternatively, this can be a character scalar, the name of a notable graph. +See Notable graphs below. +The name is case insensitive. -Starting from igraph 0.8.0, you can also include literals here, -via igraph's formula notation (see \code{\link[=graph_from_literal]{graph_from_literal()}}). -In this case, the first term of the formula has to start with -a \sQuote{\code{~}} character, just like regular formulae in R. +Starting from igraph 0.8.0, you can also include literals here, via igraph's formula notation (see \code{\link[=graph_from_literal]{graph_from_literal()}}). +In this case, the first term of the formula has to start with a \sQuote{\code{~}} character, just like regular formulae in R. See examples below.} -\item{...}{For \code{make_graph()}: extra arguments for the case when the -graph is given via a literal, see \code{\link[=graph_from_literal]{graph_from_literal()}}. -For \code{directed_graph()} and \code{undirected_graph()}: -Passed to \code{make_directed_graph()} or \code{make_undirected_graph()}.} +\item{...}{For \code{make_graph()}: extra arguments for the case when the graph is given via a literal, see \code{\link[=graph_from_literal]{graph_from_literal()}}. +For \code{directed_graph()} and \code{undirected_graph()}: Passed to \code{make_directed_graph()} or \code{make_undirected_graph()}.} -\item{n}{The number of vertices in the graph. This argument is -ignored (with a warning) if \code{edges} are symbolic vertex names. It -is also ignored if there is a bigger vertex ID in \code{edges}. This -means that for this function it is safe to supply zero here if the -vertex with the largest ID is not an isolate. The default \code{NULL} uses -the largest vertex ID in \code{edges}.} +\item{n}{The number of vertices in the graph. +This argument is ignored (with a warning) if \code{edges} are symbolic vertex names. +It is also ignored if there is a bigger vertex ID in \code{edges}. +This means that for this function it is safe to supply zero here if the vertex with the largest ID is not an isolate. +The default \code{NULL} uses the largest vertex ID in \code{edges}.} -\item{isolates}{Character vector, names of isolate vertices, -for symbolic edge lists. It is ignored for numeric edge lists.} +\item{isolates}{Character vector, names of isolate vertices, for symbolic edge lists. +It is ignored for numeric edge lists.} \item{directed}{Whether to create a directed graph.} @@ -56,8 +49,7 @@ Do not give both of them.} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.famous()} was renamed to \code{\link[=make_graph]{make_graph()}} to create a more -consistent API. +\code{graph.famous()} was renamed to \code{\link[=make_graph]{make_graph()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_create}{\code{create()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_famous}{\code{famous()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_empty}{\code{empty()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Operators.html#igraph_simplify}{\code{simplify()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_simple}{\code{is_simple()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/graph.formula.Rd b/man/graph.formula.Rd index 265188e832a..b72794392eb 100644 --- a/man/graph.formula.Rd +++ b/man/graph.formula.Rd @@ -7,22 +7,19 @@ graph.formula(..., simplify = TRUE) } \arguments{ -\item{...}{For \code{graph_from_literal()} the formulae giving the -structure of the graph, see details below. For \code{from_literal()} -all arguments are passed to \code{graph_from_literal()}.} +\item{...}{For \code{graph_from_literal()} the formulae giving the structure of the graph, see details below. +For \code{from_literal()} all arguments are passed to \code{graph_from_literal()}.} -\item{simplify}{Logical, whether to call \code{\link[=simplify]{simplify()}} -on the created graph. By default the graph is simplified, loop and -multiple edges are removed. \code{\link[=simplify]{simplify()}} is only called when the -created graph is not already simple, so the edge order from the -formula is preserved whenever no loops or multi-edges are present. +\item{simplify}{Logical, whether to call \code{\link[=simplify]{simplify()}} on the created graph. +By default the graph is simplified, loop and multiple edges are removed. +\code{\link[=simplify]{simplify()}} is only called when the created graph is not already simple, +so the edge order from the formula is preserved whenever no loops or multi-edges are present. When the graph does contain loops or multi-edges (and \code{simplify = TRUE}), \code{\link[=simplify]{simplify()}} reorders the edges into its canonical order.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.formula()} was renamed to \code{\link[=graph_from_literal]{graph_from_literal()}} to create a more -consistent API. +\code{graph.formula()} was renamed to \code{\link[=graph_from_literal]{graph_from_literal()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_create}{\code{create()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Operators.html#igraph_simplify}{\code{simplify()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_simple}{\code{is_simple()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_famous}{\code{famous()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_empty}{\code{empty()}} diff --git a/man/graph.full.Rd b/man/graph.full.Rd index 078a76cdf0c..0bd8e9a728b 100644 --- a/man/graph.full.Rd +++ b/man/graph.full.Rd @@ -16,8 +16,7 @@ graph.full(n, directed = FALSE, loops = FALSE) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.full()} was renamed to \code{\link[=make_full_graph]{make_full_graph()}} to create a more -consistent API. +\code{graph.full()} was renamed to \code{\link[=make_full_graph]{make_full_graph()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_full}{\code{full()}} diff --git a/man/graph.full.bipartite.Rd b/man/graph.full.bipartite.Rd index 25649b5e162..63235f870d7 100644 --- a/man/graph.full.bipartite.Rd +++ b/man/graph.full.bipartite.Rd @@ -14,16 +14,14 @@ graph.full.bipartite(n1, n2, directed = FALSE, mode = c("all", "out", "in")) \item{directed}{Logical, whether the graphs is directed.} \item{mode}{Scalar giving the kind of edges to create for directed graphs. -If this is \sQuote{\code{out}} then all vertices of the first kind are -connected to the others; \sQuote{\verb{in}} specifies the opposite -direction; \sQuote{\code{all}} creates mutual edges. This argument is -ignored for undirected graphs.x} +If this is \sQuote{\code{out}} then all vertices of the first kind are connected to the others; +\sQuote{\verb{in}} specifies the opposite direction; \sQuote{\code{all}} creates mutual edges. +This argument is ignored for undirected graphs.x} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.full.bipartite()} was renamed to \code{\link[=make_full_bipartite_graph]{make_full_bipartite_graph()}} to create a more -consistent API. +\code{graph.full.bipartite()} was renamed to \code{\link[=make_full_bipartite_graph]{make_full_bipartite_graph()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Bipartite.html#igraph_full_bipartite}{\code{full_bipartite()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/graph.full.citation.Rd b/man/graph.full.citation.Rd index 8f95b2d5c42..fba9f3d3b46 100644 --- a/man/graph.full.citation.Rd +++ b/man/graph.full.citation.Rd @@ -14,8 +14,7 @@ graph.full.citation(n, directed = TRUE) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.full.citation()} was renamed to \code{\link[=make_full_citation_graph]{make_full_citation_graph()}} to create a more -consistent API. +\code{graph.full.citation()} was renamed to \code{\link[=make_full_citation_graph]{make_full_citation_graph()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_full_citation}{\code{full_citation()}} diff --git a/man/graph.graphdb.Rd b/man/graph.graphdb.Rd index bc45919b8a4..7e258215026 100644 --- a/man/graph.graphdb.Rd +++ b/man/graph.graphdb.Rd @@ -17,41 +17,39 @@ graph.graphdb( ) } \arguments{ -\item{url}{Complete URL with the file to import. Default: \code{NULL}.} +\item{url}{Complete URL with the file to import. +Default: \code{NULL}.} -\item{prefix}{Gives the prefix. See details below. Possible values: -\code{iso}, \code{i2}, \code{si4}, \code{si6}, \code{mcs10}, \code{mcs30}, -\code{mcs50}, \code{mcs70}, \code{mcs90}.} +\item{prefix}{Gives the prefix. +See details below. +Possible values: \code{iso}, \code{i2}, \code{si4}, \code{si6}, \code{mcs10}, \code{mcs30}, \code{mcs50}, \code{mcs70}, \code{mcs90}.} -\item{type}{Gives the graph type identifier. See details below. Possible -values: \code{r001}, \code{r005}, \code{r01}, \code{r02}, \code{m2D}, -\code{m2Dr2}, \code{m2Dr4}, \code{m2Dr6} \code{m3D}, \code{m3Dr2}, -\code{m3Dr4}, \code{m3Dr6}, \code{m4D}, \code{m4Dr2}, \code{m4Dr4}, -\code{m4Dr6}, \code{b03}, \code{b03m}, \code{b06}, \code{b06m}, \code{b09}, -\code{b09m}.} +\item{type}{Gives the graph type identifier. +See details below. +Possible values: \code{r001}, \code{r005}, \code{r01}, \code{r02}, \code{m2D}, \code{m2Dr2}, \code{m2Dr4}, \code{m2Dr6} \code{m3D}, \code{m3Dr2}, \code{m3Dr4}, \code{m3Dr6}, \code{m4D}, \code{m4Dr2}, +\code{m4Dr4}, \code{m4Dr6}, \code{b03}, \code{b03m}, \code{b06}, \code{b06m}, \code{b09}, \code{b09m}.} \item{nodes}{The number of vertices in the graph.} -\item{pair}{Specifies which graph of the pair to read. Possible values: -\code{A} and \code{B}.} +\item{pair}{Specifies which graph of the pair to read. +Possible values: \code{A} and \code{B}.} -\item{which}{Gives the number of the graph to read. For every graph type -there are a number of actual graphs in the database. This argument specifies -which one to read.} +\item{which}{Gives the number of the graph to read. +For every graph type there are a number of actual graphs in the database. +This argument specifies which one to read.} -\item{base}{The base address of the database. See details below.} +\item{base}{The base address of the database. +See details below.} -\item{compressed}{Logical, if TRUE than the file is expected to be -compressed by gzip. If \code{url} is \code{NULL} then a \sQuote{\code{.gz}} -suffix is added to the filename.} +\item{compressed}{Logical, if TRUE than the file is expected to be compressed by gzip. +If \code{url} is \code{NULL} then a \sQuote{\code{.gz}} suffix is added to the filename.} \item{directed}{Logical, whether to create a directed graph.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.graphdb()} was renamed to \code{\link[=graph_from_graphdb]{graph_from_graphdb()}} to create a more -consistent API. +\code{graph.graphdb()} was renamed to \code{\link[=graph_from_graphdb]{graph_from_graphdb()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Foreign.html#igraph_read_graph_graphdb}{\code{read_graph_graphdb()}} diff --git a/man/graph.incidence.Rd b/man/graph.incidence.Rd index acdc26f04bf..317d10b3aea 100644 --- a/man/graph.incidence.Rd +++ b/man/graph.incidence.Rd @@ -14,44 +14,36 @@ graph.incidence( ) } \arguments{ -\item{incidence}{The input bipartite adjacency matrix. It can also be a sparse matrix -from the \code{Matrix} package.} +\item{incidence}{The input bipartite adjacency matrix. +It can also be a sparse matrix from the \code{Matrix} package.} \item{directed}{Logical, whether to create a directed graph.} -\item{mode}{A character constant, defines the direction of the edges in -directed graphs, ignored for undirected graphs. If \sQuote{\code{out}}, then -edges go from vertices of the first kind (corresponding to rows in the -bipartite adjacency matrix) to vertices of the second kind (columns in the incidence -matrix). If \sQuote{\verb{in}}, then the opposite direction is used. If -\sQuote{\code{all}} or \sQuote{\code{total}}, then mutual edges are created.} +\item{mode}{A character constant, defines the direction of the edges in directed graphs, ignored for undirected graphs. +If \sQuote{\code{out}}, +then edges go from vertices of the first kind (corresponding to rows in the bipartite adjacency matrix) to vertices of the second kind (columns in the incidence matrix). +If \sQuote{\verb{in}}, then the opposite direction is used. +If \sQuote{\code{all}} or \sQuote{\code{total}}, then mutual edges are created.} -\item{multiple}{Logical, specifies how to interpret the matrix -elements. See details below.} +\item{multiple}{Logical, specifies how to interpret the matrix elements. +See details below.} -\item{weighted}{This argument specifies whether to create a weighted graph -from the bipartite adjacency matrix. If it is \code{NULL} then an unweighted graph is -created and the \code{multiple} argument is used to determine the edges of -the graph. If it is a character constant then for every non-zero matrix -entry an edge is created and the value of the entry is added as an edge -attribute named by the \code{weighted} argument. If it is \code{TRUE} then a -weighted graph is created and the name of the edge attribute will be -\sQuote{\code{weight}}.} +\item{weighted}{This argument specifies whether to create a weighted graph from the bipartite adjacency matrix. +If it is \code{NULL} then an unweighted graph is created and the \code{multiple} argument is used to determine the edges of the graph. +If it is a character constant then for every non-zero matrix entry an edge is created and the value of the entry is added as an edge attribute named by the \code{weighted} argument. +If it is \code{TRUE} then a weighted graph is created and the name of the edge attribute will be \sQuote{\code{weight}}.} \item{add.names}{A character constant, \code{NA} or \code{NULL}. -\code{graph_from_biadjacency_matrix()} can add the row and column names of the incidence -matrix as vertex attributes. If this argument is \code{NULL} (the default) -and the bipartite adjacency matrix has both row and column names, then these are added -as the \sQuote{\code{name}} vertex attribute. If you want a different vertex -attribute for this, then give the name of the attributes as a character -string. If this argument is \code{NA}, then no vertex attributes (other than -type) will be added.} +\code{graph_from_biadjacency_matrix()} can add the row and column names of the incidence matrix as vertex attributes. +If this argument is \code{NULL} (the default) and the bipartite adjacency matrix has both row and column names, +then these are added as the \sQuote{\code{name}} vertex attribute. +If you want a different vertex attribute for this, then give the name of the attributes as a character string. +If this argument is \code{NA}, then no vertex attributes (other than type) will be added.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.incidence()} was renamed to \code{\link[=graph_from_biadjacency_matrix]{graph_from_biadjacency_matrix()}} to create a more -consistent API. +\code{graph.incidence()} was renamed to \code{\link[=graph_from_biadjacency_matrix]{graph_from_biadjacency_matrix()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Bipartite.html#igraph_biadjacency}{\code{biadjacency()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_create}{\code{create()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_empty}{\code{empty()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_famous}{\code{famous()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Operators.html#igraph_simplify}{\code{simplify()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_simple}{\code{is_simple()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/graph.intersection.Rd b/man/graph.intersection.Rd index 02d7a010539..610967e1248 100644 --- a/man/graph.intersection.Rd +++ b/man/graph.intersection.Rd @@ -7,13 +7,11 @@ graph.intersection(...) } \arguments{ -\item{...}{Arguments, their number and interpretation depends on -the function that implements \code{intersection()}.} +\item{...}{Arguments, their number and interpretation depends on the function that implements \code{intersection()}.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.intersection()} was renamed to \code{\link[=intersection]{intersection()}} to create a more -consistent API. +\code{graph.intersection()} was renamed to \code{\link[=intersection]{intersection()}} to create a more consistent API. } \keyword{internal} diff --git a/man/graph.isocreate.Rd b/man/graph.isocreate.Rd index 9b7f60d48e8..b897b383c61 100644 --- a/man/graph.isocreate.Rd +++ b/man/graph.isocreate.Rd @@ -16,8 +16,7 @@ graph.isocreate(size, number, directed = TRUE) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.isocreate()} was renamed to \code{\link[=graph_from_isomorphism_class]{graph_from_isomorphism_class()}} to create a more -consistent API. +\code{graph.isocreate()} was renamed to \code{\link[=graph_from_isomorphism_class]{graph_from_isomorphism_class()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Isomorphism.html#igraph_isoclass_create}{\code{isoclass_create()}} diff --git a/man/graph.kautz.Rd b/man/graph.kautz.Rd index 519ae844cce..15a6bb90c8e 100644 --- a/man/graph.kautz.Rd +++ b/man/graph.kautz.Rd @@ -7,15 +7,16 @@ graph.kautz(m, n) } \arguments{ -\item{m}{Integer scalar, the size of the alphabet. See details below.} +\item{m}{Integer scalar, the size of the alphabet. +See details below.} -\item{n}{Integer scalar, the length of the labels. See details below.} +\item{n}{Integer scalar, the length of the labels. +See details below.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.kautz()} was renamed to \code{\link[=make_kautz_graph]{make_kautz_graph()}} to create a more -consistent API. +\code{graph.kautz()} was renamed to \code{\link[=make_kautz_graph]{make_kautz_graph()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_kautz}{\code{kautz()}} diff --git a/man/graph.knn.Rd b/man/graph.knn.Rd index 70c502f64e1..2ed55dfe290 100644 --- a/man/graph.knn.Rd +++ b/man/graph.knn.Rd @@ -13,34 +13,30 @@ graph.knn( ) } \arguments{ -\item{graph}{The input graph. It may be directed.} +\item{graph}{The input graph. +It may be directed.} \item{vids}{The vertices for which the calculation is performed. -The default \code{NULL} includes all vertices. Note, that if not all vertices are given here, then -both \sQuote{\code{knn}} and \sQuote{\code{knnk}} will be calculated based -on the given vertices only.} +The default \code{NULL} includes all vertices. +Note, that if not all vertices are given here, +then both \sQuote{\code{knn}} and \sQuote{\code{knnk}} will be calculated based on the given vertices only.} -\item{mode}{Character constant to indicate the type of neighbors to consider -in directed graphs. \code{out} considers out-neighbors, \verb{in} considers -in-neighbors and \code{all} ignores edge directions.} +\item{mode}{Character constant to indicate the type of neighbors to consider in directed graphs. +\code{out} considers out-neighbors, \verb{in} considers in-neighbors and \code{all} ignores edge directions.} \item{neighbor.degree.mode}{The type of degree to average in directed graphs. -\code{out} averages out-degrees, \verb{in} averages in-degrees and \code{all} -ignores edge directions for the degree calculation.} +\code{out} averages out-degrees, \verb{in} averages in-degrees and \code{all} ignores edge directions for the degree calculation.} -\item{weights}{Weight vector. If the graph has a \code{weight} edge -attribute, then this is used by default. If this argument is given, then -vertex strength (see \code{\link[=strength]{strength()}}) is used instead of vertex -degree. But note that \code{knnk} is still given in the function of the -normal vertex degree. -Weights are are used to calculate a weighted degree (also called -\code{\link[=strength]{strength()}}) instead of the degree.} +\item{weights}{Weight vector. +If the graph has a \code{weight} edge attribute, then this is used by default. +If this argument is given, then vertex strength (see \code{\link[=strength]{strength()}}) is used instead of vertex degree. +But note that \code{knnk} is still given in the function of the normal vertex degree. +Weights are are used to calculate a weighted degree (also called \code{\link[=strength]{strength()}}) instead of the degree.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.knn()} was renamed to \code{\link[=knn]{knn()}} to create a more -consistent API. +\code{graph.knn()} was renamed to \code{\link[=knn]{knn()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_avg_nearest_neighbor_degree}{\code{avg_nearest_neighbor_degree()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/graph.laplacian.Rd b/man/graph.laplacian.Rd index e0437326ac4..3c5d74acc85 100644 --- a/man/graph.laplacian.Rd +++ b/man/graph.laplacian.Rd @@ -16,20 +16,17 @@ graph.laplacian( \item{normalized}{Deprecated, use \code{normalization} instead.} -\item{weights}{An optional vector giving edge weights for weighted Laplacian -matrix. If this is \code{NULL} and the graph has an edge attribute called -\code{weight}, then it will be used automatically. Set this to \code{NA} if -you want the unweighted Laplacian on a graph that has a \code{weight} edge -attribute.} +\item{weights}{An optional vector giving edge weights for weighted Laplacian matrix. +If this is \code{NULL} and the graph has an edge attribute called \code{weight}, then it will be used automatically. +Set this to \code{NA} if you want the unweighted Laplacian on a graph that has a \code{weight} edge attribute.} -\item{sparse}{Logical, whether to return the result as a sparse -matrix. The \code{Matrix} package is required for sparse matrices.} +\item{sparse}{Logical, whether to return the result as a sparse matrix. +The \code{Matrix} package is required for sparse matrices.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.laplacian()} was renamed to \code{\link[=laplacian_matrix]{laplacian_matrix()}} to create a more -consistent API. +\code{graph.laplacian()} was renamed to \code{\link[=laplacian_matrix]{laplacian_matrix()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_laplacian}{\code{get_laplacian()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_laplacian_sparse}{\code{get_laplacian_sparse()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_is_directed}{\code{is_directed()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/graph.lattice.Rd b/man/graph.lattice.Rd index b51b3a01045..6c4d94ee944 100644 --- a/man/graph.lattice.Rd +++ b/man/graph.lattice.Rd @@ -16,33 +16,28 @@ graph.lattice( ) } \arguments{ -\item{dimvector}{A vector giving the size of the lattice in each -dimension.} +\item{dimvector}{A vector giving the size of the lattice in each dimension.} -\item{length}{Integer constant, for regular lattices, the size of the -lattice in each dimension.} +\item{length}{Integer constant, for regular lattices, the size of the lattice in each dimension.} \item{dim}{Integer constant, the dimension of the lattice.} -\item{nei}{The distance within which (inclusive) the neighbors on the -lattice will be connected. This parameter is not used right now.} +\item{nei}{The distance within which (inclusive) the neighbors on the lattice will be connected. +This parameter is not used right now.} \item{directed}{Whether to create a directed lattice.} -\item{mutual}{Logical, if \code{TRUE} directed lattices will be -mutually connected.} +\item{mutual}{Logical, if \code{TRUE} directed lattices will be mutually connected.} -\item{periodic}{Logical vector, defines whether the generated lattice is -periodic along each dimension. This parameter may also be a single logical which will -be extended to a logical vector of `dimvector`` length.} +\item{periodic}{Logical vector, defines whether the generated lattice is periodic along each dimension. +This parameter may also be a single logical which will be extended to a logical vector of `dimvector`` length.} \item{circular}{Deprecated, use \code{periodic} instead.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.lattice()} was renamed to \code{\link[=make_lattice]{make_lattice()}} to create a more -consistent API. +\code{graph.lattice()} was renamed to \code{\link[=make_lattice]{make_lattice()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_square_lattice}{\code{square_lattice()}} diff --git a/man/graph.lcf.Rd b/man/graph.lcf.Rd index 009308639bc..30443b70563 100644 --- a/man/graph.lcf.Rd +++ b/man/graph.lcf.Rd @@ -7,8 +7,8 @@ graph.lcf(n, shifts, repeats = 1) } \arguments{ -\item{n}{Integer, the number of vertices in the graph. If \code{NULL} (default), -it is set to \code{len(shifts) * repeats}.} +\item{n}{Integer, the number of vertices in the graph. +If \code{NULL} (default), it is set to \code{len(shifts) * repeats}.} \item{shifts}{Integer vector, the shifts.} @@ -17,8 +17,7 @@ it is set to \code{len(shifts) * repeats}.} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.lcf()} was renamed to \code{\link[=graph_from_lcf]{graph_from_lcf()}} to create a more -consistent API. +\code{graph.lcf()} was renamed to \code{\link[=graph_from_lcf]{graph_from_lcf()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_lcf_vector}{\code{lcf_vector()}} diff --git a/man/graph.maxflow.Rd b/man/graph.maxflow.Rd index 1a6dc568ecc..c270870aeb7 100644 --- a/man/graph.maxflow.Rd +++ b/man/graph.maxflow.Rd @@ -13,15 +13,14 @@ graph.maxflow(graph, source, target, capacity = NULL) \item{target}{The ID of the target vertex (sometimes also called sink).} -\item{capacity}{Vector giving the capacity of the edges. If this is -\code{NULL} (the default) then the \code{capacity} edge attribute is used. +\item{capacity}{Vector giving the capacity of the edges. +If this is \code{NULL} (the default) then the \code{capacity} edge attribute is used. Note that the \code{weight} edge attribute is not used by this function.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.maxflow()} was renamed to \code{\link[=max_flow]{max_flow()}} to create a more -consistent API. +\code{graph.maxflow()} was renamed to \code{\link[=max_flow]{max_flow()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Flows.html#igraph_maxflow}{\code{maxflow()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}} diff --git a/man/graph.mincut.Rd b/man/graph.mincut.Rd index beb0f0e82eb..18bb2e7032e 100644 --- a/man/graph.mincut.Rd +++ b/man/graph.mincut.Rd @@ -19,18 +19,16 @@ graph.mincut( \item{target}{The ID of the target vertex (sometimes also called sink).} -\item{capacity}{Vector giving the capacity of the edges. If this is -\code{NULL} (the default) then the \code{capacity} edge attribute is used.} +\item{capacity}{Vector giving the capacity of the edges. +If this is \code{NULL} (the default) then the \code{capacity} edge attribute is used.} -\item{value.only}{Logical, if \code{TRUE} only the minimum cut value -is returned, if \code{FALSE} the edges in the cut and a the two (or more) -partitions are also returned.} +\item{value.only}{Logical, if \code{TRUE} only the minimum cut value is returned, +if \code{FALSE} the edges in the cut and a the two (or more) partitions are also returned.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.mincut()} was renamed to \code{\link[=min_cut]{min_cut()}} to create a more -consistent API. +\code{graph.mincut()} was renamed to \code{\link[=min_cut]{min_cut()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Flows.html#igraph_mincut}{\code{mincut()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Flows.html#igraph_mincut_value}{\code{mincut_value()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Flows.html#igraph_st_mincut}{\code{st_mincut()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Flows.html#igraph_st_mincut_value}{\code{st_mincut_value()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}} diff --git a/man/graph.motifs.Rd b/man/graph.motifs.Rd index 6097a72c37b..2b2cbb0f027 100644 --- a/man/graph.motifs.Rd +++ b/man/graph.motifs.Rd @@ -9,19 +9,16 @@ graph.motifs(graph, size = 3, cut.prob = rep(0, size)) \arguments{ \item{graph}{Graph object, the input graph.} -\item{size}{The size of the motif, currently sizes 3 and 4 are supported in -directed graphs and sizes 3 to 6 in undirected graphs.} +\item{size}{The size of the motif, currently sizes 3 and 4 are supported in directed graphs and sizes 3 to 6 in undirected graphs.} -\item{cut.prob}{Numeric vector giving the probabilities that the search -graph is cut at a certain level. Its length should be the same as the size -of the motif (the \code{size} argument). +\item{cut.prob}{Numeric vector giving the probabilities that the search graph is cut at a certain level. +Its length should be the same as the size of the motif (the \code{size} argument). If \verb{rep(0, size))}, the default, no cuts are made.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.motifs()} was renamed to \code{\link[=motifs]{motifs()}} to create a more -consistent API. +\code{graph.motifs()} was renamed to \code{\link[=motifs]{motifs()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Motifs.html#igraph_motifs_randesu_callback}{\code{motifs_randesu_callback()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Motifs.html#igraph_motifs_randesu}{\code{motifs_randesu()}} diff --git a/man/graph.motifs.est.Rd b/man/graph.motifs.est.Rd index 702194f8114..e61b351aabf 100644 --- a/man/graph.motifs.est.Rd +++ b/man/graph.motifs.est.Rd @@ -15,16 +15,14 @@ graph.motifs.est( \arguments{ \item{graph}{Graph object, the input graph.} -\item{size}{The size of the motif, currently size 3 and 4 are supported -in directed graphs and sizes 3-6 in undirected graphs.} +\item{size}{The size of the motif, currently size 3 and 4 are supported in directed graphs and sizes 3-6 in undirected graphs.} -\item{cut.prob}{Numeric vector giving the probabilities that the search -graph is cut at a certain level. Its length should be the same as the size -of the motif (the \code{size} argument). +\item{cut.prob}{Numeric vector giving the probabilities that the search graph is cut at a certain level. +Its length should be the same as the size of the motif (the \code{size} argument). If \verb{rep(0, size))}, the default, no cuts are made.} -\item{sample.size}{The number of vertices to use as a starting point for -finding motifs. Only used if the \code{sample} argument is \code{NULL}. +\item{sample.size}{The number of vertices to use as a starting point for finding motifs. +Only used if the \code{sample} argument is \code{NULL}. The default is \code{ceiling(vcount(graph) / 10)} .} \item{sample}{Vertices to use as a starting point for finding motifs. @@ -33,8 +31,7 @@ Default: \code{NULL}.} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.motifs.est()} was renamed to \code{\link[=sample_motifs]{sample_motifs()}} to create a more -consistent API. +\code{graph.motifs.est()} was renamed to \code{\link[=sample_motifs]{sample_motifs()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Motifs.html#igraph_motifs_randesu_estimate}{\code{motifs_randesu_estimate()}} diff --git a/man/graph.motifs.no.Rd b/man/graph.motifs.no.Rd index 35d4dbd3b8c..cba0d710b3c 100644 --- a/man/graph.motifs.no.Rd +++ b/man/graph.motifs.no.Rd @@ -11,16 +11,14 @@ graph.motifs.no(graph, size = 3, cut.prob = rep(0, size)) \item{size}{The size of the motif.} -\item{cut.prob}{Numeric vector giving the probabilities that the search -graph is cut at a certain level. Its length should be the same as the size -of the motif (the \code{size} argument). +\item{cut.prob}{Numeric vector giving the probabilities that the search graph is cut at a certain level. +Its length should be the same as the size of the motif (the \code{size} argument). If \code{NULL}, the default, no cuts are made.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.motifs.no()} was renamed to \code{\link[=count_motifs]{count_motifs()}} to create a more -consistent API. +\code{graph.motifs.no()} was renamed to \code{\link[=count_motifs]{count_motifs()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Motifs.html#igraph_motifs_randesu_no}{\code{motifs_randesu_no()}} diff --git a/man/graph.neighborhood.Rd b/man/graph.neighborhood.Rd index 2ed769672d3..bf224bc72ac 100644 --- a/man/graph.neighborhood.Rd +++ b/man/graph.neighborhood.Rd @@ -15,27 +15,25 @@ graph.neighborhood( \arguments{ \item{graph}{The input graph.} -\item{order}{Integer giving the order of the neighborhood. Negative values -indicate an infinite order.} +\item{order}{Integer giving the order of the neighborhood. +Negative values indicate an infinite order.} \item{nodes}{The vertices for which the calculation is performed. The default \code{NULL} selects all vertices.} -\item{mode}{Character constant, it specifies how to use the direction of -the edges if a directed graph is analyzed. For \sQuote{out} only the -outgoing edges are followed, so all vertices reachable from the source -vertex in at most \code{order} steps are counted. For \sQuote{"in"} all -vertices from which the source vertex is reachable in at most \code{order} -steps are counted. \sQuote{"all"} ignores the direction of the edges. This -argument is ignored for undirected graphs.} +\item{mode}{Character constant, it specifies how to use the direction of the edges if a directed graph is analyzed. +For \sQuote{out} only the outgoing edges are followed, +so all vertices reachable from the source vertex in at most \code{order} steps are counted. +For \sQuote{"in"} all vertices from which the source vertex is reachable in at most \code{order} steps are counted. +\sQuote{"all"} ignores the direction of the edges. +This argument is ignored for undirected graphs.} \item{mindist}{The minimum distance to include the vertex in the result.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.neighborhood()} was renamed to \code{\link[=make_ego_graph]{make_ego_graph()}} to create a more -consistent API. +\code{graph.neighborhood()} was renamed to \code{\link[=make_ego_graph]{make_ego_graph()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/graph.ring.Rd b/man/graph.ring.Rd index 153380f6475..a116bc274dd 100644 --- a/man/graph.ring.Rd +++ b/man/graph.ring.Rd @@ -11,18 +11,16 @@ graph.ring(n, directed = FALSE, mutual = FALSE, circular = TRUE) \item{directed}{Whether the graph is directed.} -\item{mutual}{Whether directed edges are mutual. It is ignored in -undirected graphs.} +\item{mutual}{Whether directed edges are mutual. +It is ignored in undirected graphs.} -\item{circular}{Whether to create a circular ring. A non-circular -ring is essentially a \dQuote{line}: a tree where every non-leaf -vertex has one child.} +\item{circular}{Whether to create a circular ring. +A non-circular ring is essentially a \dQuote{line}: a tree where every non-leaf vertex has one child.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.ring()} was renamed to \code{\link[=make_ring]{make_ring()}} to create a more -consistent API. +\code{graph.ring()} was renamed to \code{\link[=make_ring]{make_ring()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_ring}{\code{ring()}} diff --git a/man/graph.star.Rd b/man/graph.star.Rd index 40d33ca94b6..24e0fa2427c 100644 --- a/man/graph.star.Rd +++ b/man/graph.star.Rd @@ -9,19 +9,15 @@ graph.star(n, mode = c("in", "out", "mutual", "undirected"), center = 1) \arguments{ \item{n}{Number of vertices.} -\item{mode}{It defines the direction of the -edges, \verb{in}: the edges point \emph{to} the center, \code{out}: -the edges point \emph{from} the center, \code{mutual}: a directed -star is created with mutual edges, \code{undirected}: the edges -are undirected.} +\item{mode}{It defines the direction of the edges, \verb{in}: the edges point \emph{to} the center, \code{out}: the edges point \emph{from} the center, +\code{mutual}: a directed star is created with mutual edges, \code{undirected}: the edges are undirected.} \item{center}{ID of the center vertex.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.star()} was renamed to \code{\link[=make_star]{make_star()}} to create a more -consistent API. +\code{graph.star()} was renamed to \code{\link[=make_star]{make_star()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_star}{\code{star()}} diff --git a/man/graph.strength.Rd b/man/graph.strength.Rd index daf41c663fa..3282e9d1533 100644 --- a/man/graph.strength.Rd +++ b/man/graph.strength.Rd @@ -18,23 +18,20 @@ graph.strength( \item{vids}{The vertices for which the strength will be calculated. The default \code{NULL} selects all vertices.} -\item{mode}{Character string, \dQuote{out} for out-degree, \dQuote{in} for -in-degree or \dQuote{all} for the sum of the two. For undirected graphs this -argument is ignored.} +\item{mode}{Character string, \dQuote{out} for out-degree, \dQuote{in} for in-degree or \dQuote{all} for the sum of the two. +For undirected graphs this argument is ignored.} \item{loops}{Logical; whether the loop edges are also counted.} -\item{weights}{Weight vector. If the graph has a \code{weight} edge -attribute, then this is used by default. If the graph does not have a -\code{weight} edge attribute and this argument is \code{NULL}, then a -\code{\link[=degree]{degree()}} is called. If this is \code{NA}, then no edge weights are used -(even if the graph has a \code{weight} edge attribute).} +\item{weights}{Weight vector. +If the graph has a \code{weight} edge attribute, then this is used by default. +If the graph does not have a \code{weight} edge attribute and this argument is \code{NULL}, then a \code{\link[=degree]{degree()}} is called. +If this is \code{NA}, then no edge weights are used (even if the graph has a \code{weight} edge attribute).} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.strength()} was renamed to \code{\link[=strength]{strength()}} to create a more -consistent API. +\code{graph.strength()} was renamed to \code{\link[=strength]{strength()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_strength}{\code{strength()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/graph.tree.Rd b/man/graph.tree.Rd index 754ef310199..9dfbe77ffe0 100644 --- a/man/graph.tree.Rd +++ b/man/graph.tree.Rd @@ -9,20 +9,16 @@ graph.tree(n, children = 2, mode = c("out", "in", "undirected")) \arguments{ \item{n}{Number of vertices.} -\item{children}{Integer scalar, the number of children of a vertex -(except for leafs)} +\item{children}{Integer scalar, the number of children of a vertex (except for leafs)} -\item{mode}{Defines the direction of the -edges. \code{out} indicates that the edges point from the parent to -the children, \verb{in} indicates that they point from the children -to their parents, while \code{undirected} creates an undirected -graph.} +\item{mode}{Defines the direction of the edges. +\code{out} indicates that the edges point from the parent to the children, +\verb{in} indicates that they point from the children to their parents, while \code{undirected} creates an undirected graph.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.tree()} was renamed to \code{\link[=make_tree]{make_tree()}} to create a more -consistent API. +\code{graph.tree()} was renamed to \code{\link[=make_tree]{make_tree()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_kary_tree}{\code{kary_tree()}} diff --git a/man/graph.union.Rd b/man/graph.union.Rd index a87f5e1a2ee..6b346e21ba5 100644 --- a/man/graph.union.Rd +++ b/man/graph.union.Rd @@ -9,17 +9,15 @@ graph.union(..., byname = "auto") \arguments{ \item{...}{Graph objects or lists of graph objects.} -\item{byname}{A Logical, or the character scalar \code{auto}. Whether -to perform the operation based on symbolic vertex names. If it is -\code{auto}, that means \code{TRUE} if all graphs are named and \code{FALSE} -otherwise. A warning is generated if \code{auto} and some (but not all) -graphs are named.} +\item{byname}{A Logical, or the character scalar \code{auto}. +Whether to perform the operation based on symbolic vertex names. +If it is \code{auto}, that means \code{TRUE} if all graphs are named and \code{FALSE} otherwise. +A warning is generated if \code{auto} and some (but not all) graphs are named.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph.union()} was renamed to \code{\link[=union.igraph]{union.igraph()}} to create a more -consistent API. +\code{graph.union()} was renamed to \code{\link[=union.igraph]{union.igraph()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Isomorphism.html#igraph_permute_vertices}{\code{permute_vertices()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/graph_attr-set.Rd b/man/graph_attr-set.Rd index cc970f30733..ddd84cdb030 100644 --- a/man/graph_attr-set.Rd +++ b/man/graph_attr-set.Rd @@ -10,9 +10,8 @@ graph_attr(graph, name) <- value \arguments{ \item{graph}{The graph.} -\item{name}{The name of the attribute to set. If missing, then -\code{value} should be a named list, and all list members -are set as attributes.} +\item{name}{The name of the attribute to set. +If missing, then \code{value} should be a named list, and all list members are set as attributes.} \item{value}{The value of the attribute to set} } diff --git a/man/graph_attr.Rd b/man/graph_attr.Rd index 119a44f9f95..5516d224ec3 100644 --- a/man/graph_attr.Rd +++ b/man/graph_attr.Rd @@ -10,8 +10,8 @@ graph_attr(graph, name) \arguments{ \item{graph}{Input graph.} -\item{name}{The name of attribute to query. If missing, then all -attributes are returned in a list.} +\item{name}{The name of attribute to query. +If missing, then all attributes are returned in a list.} } \value{ A list of graph attributes, or a single graph attribute. diff --git a/man/graph_center.Rd b/man/graph_center.Rd index 501dda469bb..6583cb6c96e 100644 --- a/man/graph_center.Rd +++ b/man/graph_center.Rd @@ -11,18 +11,16 @@ graph_center(graph, ..., weights = NULL, mode = c("all", "out", "in", "total")) \item{...}{These dots are for future extensions and must be empty.} -\item{weights}{Possibly a numeric vector giving edge weights. If this is -\code{NULL} and the graph has a \code{weight} edge attribute, then the -attribute is used. If this is \code{NA} then no weights are used (even if -the graph has a \code{weight} attribute). In a weighted graph, the length -of a path is the sum of the weights of its constituent edges.} - -\item{mode}{Character constant, gives whether the shortest paths to or from -the given vertices should be calculated for directed graphs. If \code{out} -then the shortest paths \emph{from} the vertex, if \verb{in} then \emph{to} -it will be considered. If \code{all}, the default, then the graph is treated -as undirected, i.e. edge directions are not taken into account. This -argument is ignored for undirected graphs.} +\item{weights}{Possibly a numeric vector giving edge weights. +If this is \code{NULL} and the graph has a \code{weight} edge attribute, then the attribute is used. +If this is \code{NA} then no weights are used (even if the graph has a \code{weight} attribute). +In a weighted graph, the length of a path is the sum of the weights of its constituent edges.} + +\item{mode}{Character constant, +gives whether the shortest paths to or from the given vertices should be calculated for directed graphs. +If \code{out} then the shortest paths \emph{from} the vertex, if \verb{in} then \emph{to} it will be considered. +If \code{all}, the default, then the graph is treated as undirected, i.e. edge directions are not taken into account. +This argument is ignored for undirected graphs.} } \value{ The vertex IDs of the central vertices. diff --git a/man/graph_from_adj_list.Rd b/man/graph_from_adj_list.Rd index 0104a57779f..295f6426b05 100644 --- a/man/graph_from_adj_list.Rd +++ b/man/graph_from_adj_list.Rd @@ -12,22 +12,18 @@ graph_from_adj_list( ) } \arguments{ -\item{adjlist}{The adjacency list. It should be consistent, i.e. the maximum -throughout all vectors in the list must be less than the number of vectors -(=the number of vertices in the graph).} +\item{adjlist}{The adjacency list. +It should be consistent, +i.e. the maximum throughout all vectors in the list must be less than the number of vectors (=the number of vertices in the graph).} \item{...}{These dots are for future extensions and must be empty.} -\item{mode}{Character scalar, it specifies whether the graph to create is -undirected (\sQuote{all} or \sQuote{total}) or directed; and in the latter -case, whether it contains the outgoing (\sQuote{out}) or the incoming -(\sQuote{in}) neighbors of the vertices.} +\item{mode}{Character scalar, it specifies whether the graph to create is undirected (\sQuote{all} or \sQuote{total}) or directed; +and in the latter case, whether it contains the outgoing (\sQuote{out}) or the incoming (\sQuote{in}) neighbors of the vertices.} -\item{duplicate}{Logical. For undirected graphs it gives whether -edges are included in the list twice. E.g. if it is \code{TRUE} then for an -undirected \code{{A,B}} edge \code{graph_from_adj_list()} expects \code{A} -included in the neighbors of \code{B} and \code{B} to be included in the -neighbors of \code{A}. +\item{duplicate}{Logical. +For undirected graphs it gives whether edges are included in the list twice. +E.g. if it is \code{TRUE} then for an undirected \code{{A,B}} edge \code{graph_from_adj_list()} expects \code{A} included in the neighbors of \code{B} and \code{B} to be included in the neighbors of \code{A}. This argument is ignored if \code{mode} is \code{out} or \verb{in}.} } @@ -35,17 +31,15 @@ This argument is ignored if \code{mode} is \code{out} or \verb{in}.} An igraph graph object. } \description{ -An adjacency list is a list of numeric vectors, containing the neighbor -vertices for each vertex. This function creates an igraph graph object from -such a list. +An adjacency list is a list of numeric vectors, containing the neighbor vertices for each vertex. +This function creates an igraph graph object from such a list. } \details{ -Adjacency lists are handy if you intend to do many (small) modifications to -a graph. In this case adjacency lists are more efficient than igraph graphs. +Adjacency lists are handy if you intend to do many (small) modifications to a graph. +In this case adjacency lists are more efficient than igraph graphs. -The idea is that you convert your graph to an adjacency list by -\code{\link[=as_adj_list]{as_adj_list()}}, do your modifications to the graphs and finally -create again an igraph graph by calling \code{graph_from_adj_list()}. +The idea is that you convert your graph to an adjacency list by \code{\link[=as_adj_list]{as_adj_list()}}, +do your modifications to the graphs and finally create again an igraph graph by calling \code{graph_from_adj_list()}. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_adjlist}{\code{adjlist()}} diff --git a/man/graph_from_adjacency_matrix.Rd b/man/graph_from_adjacency_matrix.Rd index 4959fcba910..29175c2a08a 100644 --- a/man/graph_from_adjacency_matrix.Rd +++ b/man/graph_from_adjacency_matrix.Rd @@ -26,60 +26,49 @@ from_adjacency( ) } \arguments{ -\item{adjmatrix}{A square adjacency matrix. From igraph version 0.5.1 this -can be a sparse matrix created with the \code{Matrix} package.} +\item{adjmatrix}{A square adjacency matrix. +From igraph version 0.5.1 this can be a sparse matrix created with the \code{Matrix} package.} \item{...}{These dots are for future extensions and must be empty.} -\item{mode}{Character scalar, specifies how igraph should interpret the -supplied matrix. See also the \code{weighted} argument, the interpretation -depends on that too. Possible values are: \code{directed}, -\code{undirected}, \code{upper}, \code{lower}, \code{max}, \code{min}, -\code{plus}. See details below.} +\item{mode}{Character scalar, specifies how igraph should interpret the supplied matrix. +See also the \code{weighted} argument, the interpretation depends on that too. +Possible values are: \code{directed}, \code{undirected}, \code{upper}, \code{lower}, \code{max}, \code{min}, \code{plus}. +See details below.} -\item{weighted}{This argument specifies whether to create a weighted graph -from an adjacency matrix. If it is \code{NULL} then an unweighted graph is -created and the elements of the adjacency matrix gives the number of edges -between the vertices. If it is a character constant then for every non-zero -matrix entry an edge is created and the value of the entry is added as an -edge attribute named by the \code{weighted} argument. If it is \code{TRUE} -then a weighted graph is created and the name of the edge attribute will be -\code{weight}. See also details below.} +\item{weighted}{This argument specifies whether to create a weighted graph from an adjacency matrix. +If it is \code{NULL} then an unweighted graph is created and the elements of the adjacency matrix gives the number of edges between the vertices. +If it is a character constant then for every non-zero matrix entry an edge is created and the value of the entry is added as an edge attribute named by the \code{weighted} argument. +If it is \code{TRUE} then a weighted graph is created and the name of the edge attribute will be \code{weight}. +See also details below.} -\item{diag}{Logical, whether to include the diagonal of the matrix in -the calculation. If this is \code{FALSE} then the diagonal is zerod out -first.} +\item{diag}{Logical, whether to include the diagonal of the matrix in the calculation. +If this is \code{FALSE} then the diagonal is zerod out first.} -\item{add.colnames}{Character scalar, whether to add the column names as -vertex attributes. If it is \code{NULL} (the default) then, if -present, column names are added as vertex attribute \sQuote{name}. If -\code{NA} or \code{FALSE} then they will not be added. If a character constant, -then it gives the name of the vertex attribute to add.} +\item{add.colnames}{Character scalar, whether to add the column names as vertex attributes. +If it is \code{NULL} (the default) then, if present, column names are added as vertex attribute \sQuote{name}. +If \code{NA} or \code{FALSE} then they will not be added. +If a character constant, then it gives the name of the vertex attribute to add.} -\item{add.rownames}{Character scalar, whether to add the row names as vertex -attributes. Possible values the same as the previous argument. By default -row names are not added. If \sQuote{\code{add.rownames}} and -\sQuote{\code{add.colnames}} specify the same vertex attribute, then the -former is ignored.} +\item{add.rownames}{Character scalar, whether to add the row names as vertex attributes. +Possible values the same as the previous argument. +By default row names are not added. +If \sQuote{\code{add.rownames}} and \sQuote{\code{add.colnames}} specify the same vertex attribute, then the former is ignored.} } \value{ An igraph graph object. } \description{ -\code{graph_from_adjacency_matrix()} is a flexible function for creating \code{igraph} -graphs from adjacency matrices. +\code{graph_from_adjacency_matrix()} is a flexible function for creating \code{igraph} graphs from adjacency matrices. } \details{ -The order of the vertices are preserved, i.e. the vertex corresponding to -the first row will be vertex 0 in the graph, etc. +The order of the vertices are preserved, i.e. the vertex corresponding to the first row will be vertex 0 in the graph, etc. -\code{graph_from_adjacency_matrix()} operates in two main modes, depending on the -\code{weighted} argument. +\code{graph_from_adjacency_matrix()} operates in two main modes, depending on the \code{weighted} argument. -If this argument is \code{NULL} then an unweighted graph is created and an -element of the adjacency matrix gives the number of edges to create between -the two corresponding vertices. The details depend on the value of the -\code{mode} argument: +If this argument is \code{NULL} then an unweighted graph is created +and an element of the adjacency matrix gives the number of edges to create between the two corresponding vertices. +The details depend on the value of the \code{mode} argument: \describe{ \item{"directed"}{ The graph will be directed and a matrix element gives @@ -111,9 +100,8 @@ between vertex \code{i} and \code{j}. } } -If the \code{weighted} argument is not \code{NULL} then the elements of the -matrix give the weights of the edges (if they are not zero). The details -depend on the value of the \code{mode} argument: +If the \code{weighted} argument is not \code{NULL} then the elements of the matrix give the weights of the edges (if they are not zero). +The details depend on the value of the \code{mode} argument: \describe{ \item{"directed"}{ The graph will be directed and a matrix element gives the edge weights. @@ -255,8 +243,7 @@ summary(g10) } \seealso{ -\code{\link[=make_graph]{make_graph()}} and \code{\link[=graph_from_literal]{graph_from_literal()}} for other ways to -create graphs. +\code{\link[=make_graph]{make_graph()}} and \code{\link[=graph_from_literal]{graph_from_literal()}} for other ways to create graphs. } \author{ Gabor Csardi \email{csardi.gabor@gmail.com} diff --git a/man/graph_from_atlas.Rd b/man/graph_from_atlas.Rd index a85002edc9f..ed23580d945 100644 --- a/man/graph_from_atlas.Rd +++ b/man/graph_from_atlas.Rd @@ -16,11 +16,8 @@ atlas(n) An igraph graph. } \description{ -\code{graph_from_atlas()} creates graphs from the book -\sQuote{An Atlas of Graphs} by -Roland C. Read and Robin J. Wilson. The atlas contains all undirected -graphs with up to seven vertices, numbered from 0 up to 1252. The -graphs are listed: +\code{graph_from_atlas()} creates graphs from the book \sQuote{An Atlas of Graphs} by Roland C. Read and Robin J. Wilson. +The atlas contains all undirected graphs with up to seven vertices, numbered from 0 up to 1252. The graphs are listed: \enumerate{ \item in increasing order of number of nodes; \item for a fixed number of nodes, in increasing order of the number diff --git a/man/graph_from_biadjacency_matrix.Rd b/man/graph_from_biadjacency_matrix.Rd index 3dd28ab7658..89c660736de 100644 --- a/man/graph_from_biadjacency_matrix.Rd +++ b/man/graph_from_biadjacency_matrix.Rd @@ -15,64 +15,51 @@ graph_from_biadjacency_matrix( ) } \arguments{ -\item{incidence}{The input bipartite adjacency matrix. It can also be a sparse matrix -from the \code{Matrix} package.} +\item{incidence}{The input bipartite adjacency matrix. +It can also be a sparse matrix from the \code{Matrix} package.} \item{...}{These dots are for future extensions and must be empty.} \item{directed}{Logical, whether to create a directed graph.} -\item{mode}{A character constant, defines the direction of the edges in -directed graphs, ignored for undirected graphs. If \sQuote{\code{out}}, then -edges go from vertices of the first kind (corresponding to rows in the -bipartite adjacency matrix) to vertices of the second kind (columns in the incidence -matrix). If \sQuote{\verb{in}}, then the opposite direction is used. If -\sQuote{\code{all}} or \sQuote{\code{total}}, then mutual edges are created.} +\item{mode}{A character constant, defines the direction of the edges in directed graphs, ignored for undirected graphs. +If \sQuote{\code{out}}, +then edges go from vertices of the first kind (corresponding to rows in the bipartite adjacency matrix) to vertices of the second kind (columns in the incidence matrix). +If \sQuote{\verb{in}}, then the opposite direction is used. +If \sQuote{\code{all}} or \sQuote{\code{total}}, then mutual edges are created.} -\item{multiple}{Logical, specifies how to interpret the matrix -elements. See details below.} +\item{multiple}{Logical, specifies how to interpret the matrix elements. +See details below.} -\item{weighted}{This argument specifies whether to create a weighted graph -from the bipartite adjacency matrix. If it is \code{NULL} then an unweighted graph is -created and the \code{multiple} argument is used to determine the edges of -the graph. If it is a character constant then for every non-zero matrix -entry an edge is created and the value of the entry is added as an edge -attribute named by the \code{weighted} argument. If it is \code{TRUE} then a -weighted graph is created and the name of the edge attribute will be -\sQuote{\code{weight}}.} +\item{weighted}{This argument specifies whether to create a weighted graph from the bipartite adjacency matrix. +If it is \code{NULL} then an unweighted graph is created and the \code{multiple} argument is used to determine the edges of the graph. +If it is a character constant then for every non-zero matrix entry an edge is created and the value of the entry is added as an edge attribute named by the \code{weighted} argument. +If it is \code{TRUE} then a weighted graph is created and the name of the edge attribute will be \sQuote{\code{weight}}.} \item{add.names}{A character constant, \code{NA} or \code{NULL}. -\code{graph_from_biadjacency_matrix()} can add the row and column names of the incidence -matrix as vertex attributes. If this argument is \code{NULL} (the default) -and the bipartite adjacency matrix has both row and column names, then these are added -as the \sQuote{\code{name}} vertex attribute. If you want a different vertex -attribute for this, then give the name of the attributes as a character -string. If this argument is \code{NA}, then no vertex attributes (other than -type) will be added.} +\code{graph_from_biadjacency_matrix()} can add the row and column names of the incidence matrix as vertex attributes. +If this argument is \code{NULL} (the default) and the bipartite adjacency matrix has both row and column names, +then these are added as the \sQuote{\code{name}} vertex attribute. +If you want a different vertex attribute for this, then give the name of the attributes as a character string. +If this argument is \code{NA}, then no vertex attributes (other than type) will be added.} } \value{ -A bipartite igraph graph. In other words, an igraph graph that has a -vertex attribute \code{type}. +A bipartite igraph graph. +In other words, an igraph graph that has a vertex attribute \code{type}. } \description{ -\code{graph_from_biadjacency_matrix()} creates a bipartite igraph graph from an incidence -matrix. +\code{graph_from_biadjacency_matrix()} creates a bipartite igraph graph from an incidence matrix. } \details{ Bipartite graphs have a \sQuote{\code{type}} vertex attribute in igraph, -this is boolean and \code{FALSE} for the vertices of the first kind and -\code{TRUE} for vertices of the second kind. +this is boolean and \code{FALSE} for the vertices of the first kind and \code{TRUE} for vertices of the second kind. -\code{graph_from_biadjacency_matrix()} can operate in two modes, depending on the -\code{multiple} argument. If it is \code{FALSE} then a single edge is -created for every non-zero element in the bipartite adjacency matrix. If -\code{multiple} is \code{TRUE}, then the matrix elements are rounded up to -the closest non-negative integer to get the number of edges to create -between a pair of vertices. +\code{graph_from_biadjacency_matrix()} can operate in two modes, depending on the \code{multiple} argument. +If it is \code{FALSE} then a single edge is created for every non-zero element in the bipartite adjacency matrix. +If \code{multiple} is \code{TRUE}, +then the matrix elements are rounded up to the closest non-negative integer to get the number of edges to create between a pair of vertices. -Some authors refer to the bipartite adjacency matrix as the -"bipartite incidence matrix". igraph 1.6.0 and later does not use -this naming to avoid confusion with the edge-vertex incidence matrix. +Some authors refer to the bipartite adjacency matrix as the "bipartite incidence matrix". igraph 1.6.0 and later does not use this naming to avoid confusion with the edge-vertex incidence matrix. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Bipartite.html#igraph_biadjacency}{\code{biadjacency()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_create}{\code{create()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_empty}{\code{empty()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_famous}{\code{famous()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Operators.html#igraph_simplify}{\code{simplify()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_simple}{\code{is_simple()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} @@ -87,8 +74,7 @@ graph_from_biadjacency_matrix(inc) } \seealso{ -\code{\link[=make_bipartite_graph]{make_bipartite_graph()}} for another way to create bipartite -graphs +\code{\link[=make_bipartite_graph]{make_bipartite_graph()}} for another way to create bipartite graphs Other biadjacency: \code{\link[=as_data_frame]{as_data_frame()}} diff --git a/man/graph_from_data_frame.Rd b/man/graph_from_data_frame.Rd index 3be6d13a4c3..0012ae1ab89 100644 --- a/man/graph_from_data_frame.Rd +++ b/man/graph_from_data_frame.Rd @@ -12,84 +12,68 @@ graph_from_data_frame(d, directed = TRUE, ..., vertices = NULL) \arguments{ \item{x}{An igraph object.} -\item{what}{Character constant, whether to return info about vertices, -edges, or both. The default is \sQuote{edges}.} +\item{what}{Character constant, whether to return info about vertices, edges, or both. +The default is \sQuote{edges}.} -\item{d}{A data frame containing a symbolic edge list in the first two -columns. Additional columns are considered as edge attributes. Since -version 0.7 this argument is coerced to a data frame with -\code{as.data.frame}.} +\item{d}{A data frame containing a symbolic edge list in the first two columns. +Additional columns are considered as edge attributes. +Since version 0.7 this argument is coerced to a data frame with \code{as.data.frame}.} \item{directed}{Logical, whether or not to create a directed graph.} \item{...}{These dots are for future extensions and must be empty.} -\item{vertices}{A data frame with vertex metadata, or \code{NULL}. See -details below. Since version 0.7 this argument is coerced to a data frame -with \code{as.data.frame}, if not \code{NULL}.} +\item{vertices}{A data frame with vertex metadata, or \code{NULL}. +See details below. +Since version 0.7 this argument is coerced to a data frame with \code{as.data.frame}, if not \code{NULL}.} } \value{ -An igraph graph object for \code{graph_from_data_frame()}, and either a -data frame or a list of two data frames named \code{edges} and -\code{vertices} for \code{as.data.frame}. +An igraph graph object for \code{graph_from_data_frame()}, +and either a data frame or a list of two data frames named \code{edges} and \code{vertices} for \code{as.data.frame}. } \description{ -This function creates an igraph graph from one or two data frames containing -the (symbolic) edge list and edge/vertex attributes. +This function creates an igraph graph from one or two data frames containing the (symbolic) edge list and edge/vertex attributes. } \details{ \code{graph_from_data_frame()} creates igraph graphs from one or two data frames. -It has two modes of operation, depending whether the \code{vertices} -argument is \code{NULL} or not. +It has two modes of operation, depending whether the \code{vertices} argument is \code{NULL} or not. -If \code{vertices} is \code{NULL}, then the first two columns of \code{d} -are used as a symbolic edge list and additional columns as edge attributes. +If \code{vertices} is \code{NULL}, then the first two columns of \code{d} are used as a symbolic edge list and additional columns as edge attributes. The names of the attributes are taken from the names of the columns. -If \code{vertices} is not \code{NULL}, then it must be a data frame giving -vertex metadata. The first column of \code{vertices} is assumed to contain -symbolic vertex names, this will be added to the graphs as the -\sQuote{\code{name}} vertex attribute. Other columns will be added as -additional vertex attributes. If \code{vertices} is not \code{NULL} then the -symbolic edge list given in \code{d} is checked to contain only vertex names -listed in \code{vertices}. +If \code{vertices} is not \code{NULL}, then it must be a data frame giving vertex metadata. +The first column of \code{vertices} is assumed to contain symbolic vertex names, +this will be added to the graphs as the \sQuote{\code{name}} vertex attribute. +Other columns will be added as additional vertex attributes. +If \code{vertices} is not \code{NULL} then the symbolic edge list given in \code{d} is checked to contain only vertex names listed in \code{vertices}. -Typically, the data frames are exported from some spreadsheet software like -Excel and are imported into R via \code{\link[=read.table]{read.table()}}, +Typically, the data frames are exported from some spreadsheet software like Excel and are imported into R via \code{\link[=read.table]{read.table()}}, \code{\link[=read.delim]{read.delim()}} or \code{\link[=read.csv]{read.csv()}}. -All edges in the data frame are included in the graph, which may include -multiple parallel edges and loops. +All edges in the data frame are included in the graph, which may include multiple parallel edges and loops. -\code{as_data_frame()} converts the igraph graph into one or more data -frames, depending on the \code{what} argument. +\code{as_data_frame()} converts the igraph graph into one or more data frames, depending on the \code{what} argument. -If the \code{what} argument is \code{edges} (the default), then the edges of -the graph and also the edge attributes are returned. The edges will be in -the first two columns, named \code{from} and \code{to}. (This also denotes -edge direction for directed graphs.) For named graphs, the vertex names -will be included in these columns, for other graphs, the numeric vertex IDs. -The edge attributes will be in the other columns. It is not a good idea to -have an edge attribute named \code{from} or \code{to}, because then the -column named in the data frame will not be unique. The edges are listed in -the order of their numeric IDs. +If the \code{what} argument is \code{edges} (the default), then the edges of the graph and also the edge attributes are returned. +The edges will be in the first two columns, named \code{from} and \code{to}. +(This also denotes edge direction for directed graphs.) +For named graphs, the vertex names will be included in these columns, for other graphs, the numeric vertex IDs. +The edge attributes will be in the other columns. +It is not a good idea to have an edge attribute named \code{from} or \code{to}, because then the column named in the data frame will not be unique. +The edges are listed in the order of their numeric IDs. -If the \code{what} argument is \code{vertices}, then vertex attributes are -returned. Vertices are listed in the order of their numeric vertex IDs. +If the \code{what} argument is \code{vertices}, then vertex attributes are returned. +Vertices are listed in the order of their numeric vertex IDs. -If the \code{what} argument is \code{both}, then both vertex and edge data -is returned, in a list with named entries \code{vertices} and \code{edges}. +If the \code{what} argument is \code{both}, then both vertex and edge data is returned, in a list with named entries \code{vertices} and \code{edges}. } \note{ -For \code{graph_from_data_frame()} \code{NA} elements in the first two -columns \sQuote{d} are replaced by the string \dQuote{NA} before creating -the graph. This means that all \code{NA}s will correspond to a single -vertex. - -\code{NA} elements in the first column of \sQuote{vertices} are also -replaced by the string \dQuote{NA}, but the rest of \sQuote{vertices} is not -touched. In other words, vertex names (=the first column) cannot be -\code{NA}, but other vertex attributes can. +For \code{graph_from_data_frame()} \code{NA} elements in the first two columns \sQuote{d} are replaced by the string \dQuote{NA} before creating the graph. +This means that all \code{NA}s will correspond to a single vertex. + +\code{NA} elements in the first column of \sQuote{vertices} are also replaced by the string \dQuote{NA}, +but the rest of \sQuote{vertices} is not touched. +In other words, vertex names (=the first column) cannot be \code{NA}, but other vertex attributes can. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_edgelist}{\code{get_edgelist()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_add_vertices}{\code{add_vertices()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_empty}{\code{empty()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} @@ -125,10 +109,8 @@ as_data_frame(g, what = "edges") } \seealso{ -\code{\link[=graph_from_literal]{graph_from_literal()}} -for another way to create graphs, \code{\link[=read.table]{read.table()}} to read in tables -from files. See \code{\link[=from_data_frame]{from_data_frame()}} to build a lazy constructor -specification for \code{\link[=make_]{make_()}} or \code{\link[=sample_]{sample_()}}. +\code{\link[=graph_from_literal]{graph_from_literal()}} for another way to create graphs, \code{\link[=read.table]{read.table()}} to read in tables from files. +See \code{\link[=from_data_frame]{from_data_frame()}} to build a lazy constructor specification for \code{\link[=make_]{make_()}} or \code{\link[=sample_]{sample_()}}. Other conversion: \code{\link[=as.matrix.igraph]{as.matrix.igraph()}}, diff --git a/man/graph_from_edgelist.Rd b/man/graph_from_edgelist.Rd index ca80ca830d6..d7113b72f37 100644 --- a/man/graph_from_edgelist.Rd +++ b/man/graph_from_edgelist.Rd @@ -17,12 +17,11 @@ graph_from_edgelist(el, ..., directed = TRUE) An igraph graph. } \description{ -\code{graph_from_edgelist()} creates a graph from an edge list. Its argument -is a two-column matrix, each row defines one edge. If it is -a numeric matrix then its elements are interpreted as vertex IDs. If -it is a character matrix then it is interpreted as symbolic vertex -names and a vertex ID will be assigned to each name, and also a -\code{name} vertex attribute will be added. +\code{graph_from_edgelist()} creates a graph from an edge list. +Its argument is a two-column matrix, each row defines one edge. +If it is a numeric matrix then its elements are interpreted as vertex IDs. +If it is a character matrix then it is interpreted as symbolic vertex names and a vertex ID will be assigned to each name, +and also a \code{name} vertex attribute will be added. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_create}{\code{create()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_empty}{\code{empty()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_famous}{\code{famous()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Operators.html#igraph_simplify}{\code{simplify()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_simple}{\code{is_simple()}} @@ -36,8 +35,7 @@ graph_from_edgelist(el) graph_from_edgelist(cbind(1:10, c(2:10, 1))) } \seealso{ -\code{\link[=from_edgelist]{from_edgelist()}} to build a lazy constructor specification for -\code{\link[=make_]{make_()}} or \code{\link[=sample_]{sample_()}}. +\code{\link[=from_edgelist]{from_edgelist()}} to build a lazy constructor specification for \code{\link[=make_]{make_()}} or \code{\link[=sample_]{sample_()}}. Other deterministic constructors: \code{\link[=graph_from_atlas]{graph_from_atlas()}}, diff --git a/man/graph_from_graphdb.Rd b/man/graph_from_graphdb.Rd index 3b87c241a5c..04fc7ac7fce 100644 --- a/man/graph_from_graphdb.Rd +++ b/man/graph_from_graphdb.Rd @@ -18,35 +18,34 @@ graph_from_graphdb( ) } \arguments{ -\item{url}{Complete URL with the file to import. Default: \code{NULL}.} +\item{url}{Complete URL with the file to import. +Default: \code{NULL}.} \item{...}{These dots are for future extensions and must be empty.} -\item{prefix}{Gives the prefix. See details below. Possible values: -\code{iso}, \code{i2}, \code{si4}, \code{si6}, \code{mcs10}, \code{mcs30}, -\code{mcs50}, \code{mcs70}, \code{mcs90}.} +\item{prefix}{Gives the prefix. +See details below. +Possible values: \code{iso}, \code{i2}, \code{si4}, \code{si6}, \code{mcs10}, \code{mcs30}, \code{mcs50}, \code{mcs70}, \code{mcs90}.} -\item{type}{Gives the graph type identifier. See details below. Possible -values: \code{r001}, \code{r005}, \code{r01}, \code{r02}, \code{m2D}, -\code{m2Dr2}, \code{m2Dr4}, \code{m2Dr6} \code{m3D}, \code{m3Dr2}, -\code{m3Dr4}, \code{m3Dr6}, \code{m4D}, \code{m4Dr2}, \code{m4Dr4}, -\code{m4Dr6}, \code{b03}, \code{b03m}, \code{b06}, \code{b06m}, \code{b09}, -\code{b09m}.} +\item{type}{Gives the graph type identifier. +See details below. +Possible values: \code{r001}, \code{r005}, \code{r01}, \code{r02}, \code{m2D}, \code{m2Dr2}, \code{m2Dr4}, \code{m2Dr6} \code{m3D}, \code{m3Dr2}, \code{m3Dr4}, \code{m3Dr6}, \code{m4D}, \code{m4Dr2}, +\code{m4Dr4}, \code{m4Dr6}, \code{b03}, \code{b03m}, \code{b06}, \code{b06m}, \code{b09}, \code{b09m}.} \item{nodes}{The number of vertices in the graph.} -\item{pair}{Specifies which graph of the pair to read. Possible values: -\code{A} and \code{B}.} +\item{pair}{Specifies which graph of the pair to read. +Possible values: \code{A} and \code{B}.} -\item{which}{Gives the number of the graph to read. For every graph type -there are a number of actual graphs in the database. This argument specifies -which one to read.} +\item{which}{Gives the number of the graph to read. +For every graph type there are a number of actual graphs in the database. +This argument specifies which one to read.} -\item{base}{The base address of the database. See details below.} +\item{base}{The base address of the database. +See details below.} -\item{compressed}{Logical, if TRUE than the file is expected to be -compressed by gzip. If \code{url} is \code{NULL} then a \sQuote{\code{.gz}} -suffix is added to the filename.} +\item{compressed}{Logical, if TRUE than the file is expected to be compressed by gzip. +If \code{url} is \code{NULL} then a \sQuote{\code{.gz}} suffix is added to the filename.} \item{directed}{Logical, whether to create a directed graph.} } @@ -54,25 +53,20 @@ suffix is added to the filename.} A new graph object. } \description{ -This function downloads a graph from a database created for the evaluation -of graph isomorphism testing algorithms. +This function downloads a graph from a database created for the evaluation of graph isomorphism testing algorithms. } \details{ -\code{graph_from_graphdb()} reads a graph from the graph database from an FTP or -HTTP server or from a local copy. It has two modes of operation: +\code{graph_from_graphdb()} reads a graph from the graph database from an FTP or HTTP server or from a local copy. +It has two modes of operation: -If the \code{url} argument is specified then it should the complete path to -a local or remote graph database file. In this case we simply call -\code{\link[=read_graph]{read_graph()}} with the proper arguments to read the file. +If the \code{url} argument is specified then it should the complete path to a local or remote graph database file. +In this case we simply call \code{\link[=read_graph]{read_graph()}} with the proper arguments to read the file. -If \code{url} is \code{NULL}, and this is the default, then the filename is -assembled from the \code{base}, \code{prefix}, \code{type}, \code{nodes}, +If \code{url} is \code{NULL}, and this is the default, then the filename is assembled from the \code{base}, \code{prefix}, \code{type}, \code{nodes}, \code{pair} and \code{which} arguments. -Unfortunately the original graph database homepage is now defunct, but see -its old version at -\url{https://web.archive.org/web/20090215182331/http://amalfi.dis.unina.it/graph/db/doc/graphdbat.html} -for the actual format of a graph database file and other information. +Unfortunately the original graph database homepage is now defunct, +but see its old version at \url{https://web.archive.org/web/20090215182331/http://amalfi.dis.unina.it/graph/db/doc/graphdbat.html} for the actual format of a graph database file and other information. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Foreign.html#igraph_read_graph_graphdb}{\code{read_graph_graphdb()}} diff --git a/man/graph_from_graphnel.Rd b/man/graph_from_graphnel.Rd index d1bdc8853d5..77a1c9149a3 100644 --- a/man/graph_from_graphnel.Rd +++ b/man/graph_from_graphnel.Rd @@ -17,34 +17,27 @@ graph_from_graphnel( \item{...}{These dots are for future extensions and must be empty.} -\item{name}{Logical, whether to add graphNEL vertex names as an -igraph vertex attribute called \sQuote{\code{name}}.} +\item{name}{Logical, whether to add graphNEL vertex names as an igraph vertex attribute called \sQuote{\code{name}}.} -\item{weight}{Logical, whether to add graphNEL edge weights as an -igraph edge attribute called \sQuote{\code{weight}}. (graphNEL graphs are -always weighted.)} +\item{weight}{Logical, whether to add graphNEL edge weights as an igraph edge attribute called \sQuote{\code{weight}}. +(graphNEL graphs are always weighted.)} -\item{unlist.attrs}{Logical. graphNEL attribute query functions -return the values of the attributes in R lists, if this argument is -\code{TRUE} (the default) these will be converted to atomic vectors, -whenever possible, before adding them to the igraph graph.} +\item{unlist.attrs}{Logical. graphNEL attribute query functions return the values of the attributes in R lists, +if this argument is \code{TRUE} (the default) these will be converted to atomic vectors, whenever possible, +before adding them to the igraph graph.} } \value{ \code{graph_from_graphnel()} returns an igraph graph object. } \description{ -The graphNEL class is defined in the \code{graph} package, it is another -way to represent graphs. \code{graph_from_graphnel()} takes a graphNEL -graph and converts it to an igraph graph. It handles all -graph/vertex/edge attributes. If the graphNEL graph has a vertex -attribute called \sQuote{\code{name}} it will be used as igraph vertex -attribute \sQuote{\code{name}} and the graphNEL vertex names will be -ignored. +The graphNEL class is defined in the \code{graph} package, it is another way to represent graphs. +\code{graph_from_graphnel()} takes a graphNEL graph and converts it to an igraph graph. +It handles all graph/vertex/edge attributes. +If the graphNEL graph has a vertex attribute called \sQuote{\code{name}} it will be used as igraph vertex attribute \sQuote{\code{name}} and the graphNEL vertex names will be ignored. } \details{ -Because graphNEL graphs poorly support multiple edges, the edge -attributes of the multiple edges are lost: they are all replaced by the -attributes of the first of the multiple edges. +Because graphNEL graphs poorly support multiple edges, the edge attributes of the multiple edges are lost: +they are all replaced by the attributes of the first of the multiple edges. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_edgelist}{\code{get_edgelist()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_adjlist}{\code{adjlist()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} @@ -68,10 +61,8 @@ g4 \dontshow{\}) # examplesIf} } \seealso{ -\code{\link[=as_graphnel]{as_graphnel()}} for the other direction, -\code{\link[=as_adjacency_matrix]{as_adjacency_matrix()}}, \code{\link[=graph_from_adjacency_matrix]{graph_from_adjacency_matrix()}}, -\code{\link[=as_adj_list]{as_adj_list()}} and \code{\link[=graph_from_adj_list]{graph_from_adj_list()}} for other -graph representations. +\code{\link[=as_graphnel]{as_graphnel()}} for the other direction, \code{\link[=as_adjacency_matrix]{as_adjacency_matrix()}}, \code{\link[=graph_from_adjacency_matrix]{graph_from_adjacency_matrix()}}, +\code{\link[=as_adj_list]{as_adj_list()}} and \code{\link[=graph_from_adj_list]{graph_from_adj_list()}} for other graph representations. Other conversion: \code{\link[=as.matrix.igraph]{as.matrix.igraph()}}, diff --git a/man/graph_from_incidence_matrix.Rd b/man/graph_from_incidence_matrix.Rd index 6b41f6729a4..6e45f3491e0 100644 --- a/man/graph_from_incidence_matrix.Rd +++ b/man/graph_from_incidence_matrix.Rd @@ -12,13 +12,10 @@ graph_from_incidence_matrix(...) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graph_from_incidence_matrix()} was renamed to \code{\link[=graph_from_biadjacency_matrix]{graph_from_biadjacency_matrix()}} to create a more -consistent API. +\code{graph_from_incidence_matrix()} was renamed to \code{\link[=graph_from_biadjacency_matrix]{graph_from_biadjacency_matrix()}} to create a more consistent API. } \details{ -Some authors refer to the bipartite adjacency matrix as the -"bipartite incidence matrix". igraph 1.6.0 and later does not use -this naming to avoid confusion with the edge-vertex incidence matrix. +Some authors refer to the bipartite adjacency matrix as the "bipartite incidence matrix". igraph 1.6.0 and later does not use this naming to avoid confusion with the edge-vertex incidence matrix. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Bipartite.html#igraph_biadjacency}{\code{biadjacency()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_create}{\code{create()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_empty}{\code{empty()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_famous}{\code{famous()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Operators.html#igraph_simplify}{\code{simplify()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_simple}{\code{is_simple()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/graph_from_isomorphism_class.Rd b/man/graph_from_isomorphism_class.Rd index cd518d3c408..5788576c68f 100644 --- a/man/graph_from_isomorphism_class.Rd +++ b/man/graph_from_isomorphism_class.Rd @@ -16,15 +16,12 @@ graph_from_isomorphism_class(size, number, ..., directed = TRUE) \item{directed}{Whether to create a directed graph (the default).} } \value{ -An igraph object, the graph of the given size, directedness -and isomorphism class. +An igraph object, the graph of the given size, directedness and isomorphism class. } \description{ The isomorphism class is a non-negative integer number. -Graphs (with the same number of vertices) having the same isomorphism -class are isomorphic and isomorphic graphs always have the same -isomorphism class. Currently it can handle directed graphs with 3 or 4 -vertices and undirected graphd with 3 to 6 vertices. +Graphs (with the same number of vertices) having the same isomorphism class are isomorphic and isomorphic graphs always have the same isomorphism class. +Currently it can handle directed graphs with 3 or 4 vertices and undirected graphd with 3 to 6 vertices. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Isomorphism.html#igraph_isoclass_create}{\code{isoclass_create()}} diff --git a/man/graph_from_lcf.Rd b/man/graph_from_lcf.Rd index 94fd3d0e74a..7b21ec71d8e 100644 --- a/man/graph_from_lcf.Rd +++ b/man/graph_from_lcf.Rd @@ -11,8 +11,8 @@ graph_from_lcf(shifts, ..., n = NULL, repeats = 1L) \item{...}{These dots are for future extensions and must be empty.} -\item{n}{Integer, the number of vertices in the graph. If \code{NULL} (default), -it is set to \code{len(shifts) * repeats}.} +\item{n}{Integer, the number of vertices in the graph. +If \code{NULL} (default), it is set to \code{len(shifts) * repeats}.} \item{repeats}{Integer constant, how many times to repeat the shifts.} } @@ -20,11 +20,9 @@ it is set to \code{len(shifts) * repeats}.} A graph object. } \description{ -LCF is short for Lederberg-Coxeter-Frucht, it is a concise notation for -3-regular Hamiltonian graphs. It constists of three parameters, the number -of vertices in the graph, a list of shifts giving additional edges to a -cycle backbone and another integer giving how many times the shifts should -be performed. +LCF is short for Lederberg-Coxeter-Frucht, it is a concise notation for 3-regular Hamiltonian graphs. +It constists of three parameters, the number of vertices in the graph, +a list of shifts giving additional edges to a cycle backbone and another integer giving how many times the shifts should be performed. See \url{https://mathworld.wolfram.com/LCFNotation.html} for details. } \section{Related documentation in the C library}{ @@ -39,8 +37,7 @@ g2 <- make_graph("Franklin") isomorphic(g1, g2) } \seealso{ -\code{\link[=make_graph]{make_graph()}} can create arbitrary graphs, see also the other -functions on the its manual page for creating special graphs. +\code{\link[=make_graph]{make_graph()}} can create arbitrary graphs, see also the other functions on the its manual page for creating special graphs. } \author{ Gabor Csardi \email{csardi.gabor@gmail.com} diff --git a/man/graph_from_literal.Rd b/man/graph_from_literal.Rd index 1bbb94926a5..be7981a9a54 100644 --- a/man/graph_from_literal.Rd +++ b/man/graph_from_literal.Rd @@ -10,87 +10,73 @@ graph_from_literal(..., simplify = TRUE) from_literal(...) } \arguments{ -\item{...}{For \code{graph_from_literal()} the formulae giving the -structure of the graph, see details below. For \code{from_literal()} -all arguments are passed to \code{graph_from_literal()}.} - -\item{simplify}{Logical, whether to call \code{\link[=simplify]{simplify()}} -on the created graph. By default the graph is simplified, loop and -multiple edges are removed. \code{\link[=simplify]{simplify()}} is only called when the -created graph is not already simple, so the edge order from the -formula is preserved whenever no loops or multi-edges are present. +\item{...}{For \code{graph_from_literal()} the formulae giving the structure of the graph, see details below. +For \code{from_literal()} all arguments are passed to \code{graph_from_literal()}.} + +\item{simplify}{Logical, whether to call \code{\link[=simplify]{simplify()}} on the created graph. +By default the graph is simplified, loop and multiple edges are removed. +\code{\link[=simplify]{simplify()}} is only called when the created graph is not already simple, +so the edge order from the formula is preserved whenever no loops or multi-edges are present. When the graph does contain loops or multi-edges (and \code{simplify = TRUE}), \code{\link[=simplify]{simplify()}} reorders the edges into its canonical order.} } \value{ An igraph graph } \description{ -This function is useful if you want to create a small (named) graph -quickly, it works for both directed and undirected graphs. +This function is useful if you want to create a small (named) graph quickly, it works for both directed and undirected graphs. } \details{ \code{graph_from_literal()} is very handy for creating small graphs quickly. -You need to supply one or more R expressions giving the structure of -the graph. The expressions consist of vertex names and edge -operators. An edge operator is a sequence of \sQuote{\code{-}} and -\sQuote{\code{+}} characters, the former is for the edges and the -latter is used for arrow heads. The edges can be arbitrarily long, -i.e. you may use as many \sQuote{\code{-}} characters to \dQuote{draw} -them as you like. - -If all edge operators consist of only \sQuote{\code{-}} characters -then the graph will be undirected, whereas a single \sQuote{\code{+}} -character implies a directed graph. - -Let us see some simple examples. Without arguments the function -creates an empty graph: +You need to supply one or more R expressions giving the structure of the graph. +The expressions consist of vertex names and edge operators. +An edge operator is a sequence of \sQuote{\code{-}} and \sQuote{\code{+}} characters, +the former is for the edges and the latter is used for arrow heads. +The edges can be arbitrarily long, i.e. you may use as many \sQuote{\code{-}} characters to \dQuote{draw} them as you like. + +If all edge operators consist of only \sQuote{\code{-}} characters then the graph will be undirected, +whereas a single \sQuote{\code{+}} character implies a directed graph. + +Let us see some simple examples. +Without arguments the function creates an empty graph: \preformatted{ graph_from_literal() } -A simple undirected graph with two vertices called \sQuote{A} and -\sQuote{B} and one edge only: +A simple undirected graph with two vertices called \sQuote{A} and \sQuote{B} and one edge only: \preformatted{ graph_from_literal(A-B) } -Remember that the length of the edges does not matter, so we could -have written the following, this creates the same graph: +Remember that the length of the edges does not matter, so we could have written the following, this creates the same graph: \preformatted{ graph_from_literal( A-----B ) } -If you have many disconnected components in the graph, separate them -with commas. You can also give isolate vertices. +If you have many disconnected components in the graph, separate them with commas. +You can also give isolate vertices. \preformatted{ graph_from_literal( A--B, C--D, E--F, G--H, I, J, K ) } -The \sQuote{\code{:}} operator can be used to define vertex sets. If -an edge operator connects two vertex sets then every vertex from the -first set will be connected to every vertex in the second set. The -following form creates a full graph, including loop edges: +The \sQuote{\code{:}} operator can be used to define vertex sets. +If an edge operator connects two vertex sets then every vertex from the first set will be connected to every vertex in the second set. +The following form creates a full graph, including loop edges: \preformatted{ graph_from_literal( A:B:C:D -- A:B:C:D ) } -In directed graphs, edges will be created only if the edge operator -includes a arrow head (\sQuote{+}) \emph{at the end} of the edge: +In directed graphs, edges will be created only if the edge operator includes a arrow head (\sQuote{+}) \emph{at the end} of the edge: \preformatted{ graph_from_literal( A -+ B -+ C ) graph_from_literal( A +- B -+ C ) graph_from_literal( A +- B -- C ) } -Thus in the third example no edge is created between vertices \code{B} -and \code{C}. +Thus in the third example no edge is created between vertices \code{B} and \code{C}. Mutual edges can be also created with a simple edge operator: \preformatted{ graph_from_literal( A +-+ B +---+ C ++ D + E) } -Note again that the length of the edge operators is arbitrary, -\sQuote{\code{+}}, \sQuote{\verb{++}} and \sQuote{\verb{+-----+}} have -exactly the same meaning. +Note again that the length of the edge operators is arbitrary, \sQuote{\code{+}}, +\sQuote{\verb{++}} and \sQuote{\verb{+-----+}} have exactly the same meaning. -If the vertex names include spaces or other special characters then -you need to quote them: +If the vertex names include spaces or other special characters then you need to quote them: \preformatted{ graph_from_literal( "this is" +- "a silly" -+ "graph here" ) } -You can include any character in the vertex names this way, even -\sQuote{+} and \sQuote{-} characters. +You can include any character in the vertex names this way, even \sQuote{+} and \sQuote{-} characters. See more examples below. } diff --git a/man/graph_id.Rd b/man/graph_id.Rd index 76f32e6c2ae..e197340c2a9 100644 --- a/man/graph_id.Rd +++ b/man/graph_id.Rd @@ -12,13 +12,12 @@ graph_id(x, ...) \item{...}{Not used currently.} } \value{ -The ID of the graph, a character scalar. For -vertex and edge sequences the ID of the graph they were created from. +The ID of the graph, a character scalar. +For vertex and edge sequences the ID of the graph they were created from. } \description{ -Graph IDs are used to check that a vertex or edge sequence -belongs to a graph. If you create a new graph by changing the -structure of a graph, the new graph will have a new ID. +Graph IDs are used to check that a vertex or edge sequence belongs to a graph. +If you create a new graph by changing the structure of a graph, the new graph will have a new ID. Changing the attributes will not change the ID. } \examples{ diff --git a/man/graph_version.Rd b/man/graph_version.Rd index 01652934eb5..3bc741104e4 100644 --- a/man/graph_version.Rd +++ b/man/graph_version.Rd @@ -7,24 +7,21 @@ graph_version(graph) } \arguments{ -\item{graph}{The input graph. If it is missing, then -the version number of the current data format is returned.} +\item{graph}{The input graph. +If it is missing, then the version number of the current data format is returned.} } \value{ An integer scalar. } \description{ -igraph's internal data representation changes sometimes between -versions. This means that it is not always possible to use igraph objects -that were created (and possibly saved to a file) with an older -igraph version. +igraph's internal data representation changes sometimes between versions. +This means that it is not always possible to use igraph objects that were created (and possibly saved to a file) with an older igraph version. } \details{ \code{graph_version()} queries the current data format, or the data format of a possibly older igraph graph. -\code{\link[=upgrade_graph]{upgrade_graph()}} can convert an older data format -to the current one. +\code{\link[=upgrade_graph]{upgrade_graph()}} can convert an older data format to the current one. } \seealso{ upgrade_graph to convert the data format of a graph. diff --git a/man/graphlet_basis.Rd b/man/graphlet_basis.Rd index 88ce6849e76..dafcd1a858a 100644 --- a/man/graphlet_basis.Rd +++ b/man/graphlet_basis.Rd @@ -13,22 +13,20 @@ graphlet_proj(graph, ..., weights = NULL, cliques, niter = 1000, Mu = NULL) graphlets(graph, ..., weights = NULL, niter = 1000) } \arguments{ -\item{graph}{The input graph, edge directions are ignored. Only simple graph -(i.e. graphs without self-loops and multiple edges) are supported.} +\item{graph}{The input graph, edge directions are ignored. +Only simple graph (i.e. graphs without self-loops and multiple edges) are supported.} \item{...}{These dots are for future extensions and must be empty.} -\item{weights}{Edge weights. If the graph has a \code{weight} edge attribute -and this argument is \code{NULL} (the default), then the \code{weight} edge -attribute is used.} +\item{weights}{Edge weights. +If the graph has a \code{weight} edge attribute and this argument is \code{NULL} (the default), then the \code{weight} edge attribute is used.} -\item{cliques}{A list of vertex IDs, the graphlet basis to use for the -projection.} +\item{cliques}{A list of vertex IDs, the graphlet basis to use for the projection.} \item{niter}{Integer scalar, the number of iterations to perform.} -\item{Mu}{Starting weights for the projection. The default \code{NULL} uses a -weight of one for each clique.} +\item{Mu}{Starting weights for the projection. +The default \code{NULL} uses a weight of one for each clique.} } \value{ \code{graphlets()} returns a list with two members: @@ -53,24 +51,20 @@ The weight thresholds used for finding the subgraphs. } } -\code{graphlet_proj()} return a numeric vector, the weights of the graphlet -basis subgraphs. +\code{graphlet_proj()} return a numeric vector, the weights of the graphlet basis subgraphs. } \description{ -Graphlet decomposition models a weighted undirected graph via the union of -potentially overlapping dense social groups. This is done by a two-step -algorithm. In the first step a candidate set of groups (a candidate basis) -is created by finding cliques if the thresholded input graph. In the second -step these the graph is projected on the candidate basis, resulting a weight -coefficient for each clique in the candidate basis. +Graphlet decomposition models a weighted undirected graph via the union of potentially overlapping dense social groups. +This is done by a two-step algorithm. +In the first step a candidate set of groups (a candidate basis) is created by finding cliques if the thresholded input graph. +In the second step these the graph is projected on the candidate basis, +resulting a weight coefficient for each clique in the candidate basis. } \details{ -igraph contains three functions for performing the graph decomponsition of a -graph. The first is \code{graphlets()}, which performed both steps on the -method and returns a list of subgraphs, with their corresponding weights. -The second and third functions correspond to the first and second steps of -the algorithm, and they are useful if the user wishes to perform them -individually: \code{graphlet_basis()} and \code{graphlet_proj()}. +igraph contains three functions for performing the graph decomponsition of a graph. +The first is \code{graphlets()}, which performed both steps on the method and returns a list of subgraphs, with their corresponding weights. +The second and third functions correspond to the first and second steps of the algorithm, +and they are useful if the user wishes to perform them individually: \code{graphlet_basis()} and \code{graphlet_proj()}. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Graphlets.html#igraph_graphlets_candidate_basis}{\code{graphlets_candidate_basis()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Graphlets.html#igraph_graphlets_project}{\code{graphlets_project()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Graphlets.html#igraph_graphlets}{\code{graphlets()}} diff --git a/man/graphlets.candidate.basis.Rd b/man/graphlets.candidate.basis.Rd index b72de6dc592..686c8400d54 100644 --- a/man/graphlets.candidate.basis.Rd +++ b/man/graphlets.candidate.basis.Rd @@ -7,18 +7,16 @@ graphlets.candidate.basis(graph, weights = NULL) } \arguments{ -\item{graph}{The input graph, edge directions are ignored. Only simple graph -(i.e. graphs without self-loops and multiple edges) are supported.} +\item{graph}{The input graph, edge directions are ignored. +Only simple graph (i.e. graphs without self-loops and multiple edges) are supported.} -\item{weights}{Edge weights. If the graph has a \code{weight} edge attribute -and this argument is \code{NULL} (the default), then the \code{weight} edge -attribute is used.} +\item{weights}{Edge weights. +If the graph has a \code{weight} edge attribute and this argument is \code{NULL} (the default), then the \code{weight} edge attribute is used.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graphlets.candidate.basis()} was renamed to \code{\link[=graphlet_basis]{graphlet_basis()}} to create a more -consistent API. +\code{graphlets.candidate.basis()} was renamed to \code{\link[=graphlet_basis]{graphlet_basis()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Graphlets.html#igraph_graphlets_candidate_basis}{\code{graphlets_candidate_basis()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/graphlets.project.Rd b/man/graphlets.project.Rd index 535c2c5e9cc..ab77aef46a7 100644 --- a/man/graphlets.project.Rd +++ b/man/graphlets.project.Rd @@ -13,26 +13,23 @@ graphlets.project( ) } \arguments{ -\item{graph}{The input graph, edge directions are ignored. Only simple graph -(i.e. graphs without self-loops and multiple edges) are supported.} +\item{graph}{The input graph, edge directions are ignored. +Only simple graph (i.e. graphs without self-loops and multiple edges) are supported.} -\item{weights}{Edge weights. If the graph has a \code{weight} edge attribute -and this argument is \code{NULL} (the default), then the \code{weight} edge -attribute is used.} +\item{weights}{Edge weights. +If the graph has a \code{weight} edge attribute and this argument is \code{NULL} (the default), then the \code{weight} edge attribute is used.} -\item{cliques}{A list of vertex IDs, the graphlet basis to use for the -projection.} +\item{cliques}{A list of vertex IDs, the graphlet basis to use for the projection.} \item{niter}{Integer scalar, the number of iterations to perform.} -\item{Mu}{Starting weights for the projection. The default \code{NULL} uses a -weight of one for each clique.} +\item{Mu}{Starting weights for the projection. +The default \code{NULL} uses a weight of one for each clique.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{graphlets.project()} was renamed to \code{\link[=graphlet_proj]{graphlet_proj()}} to create a more -consistent API. +\code{graphlets.project()} was renamed to \code{\link[=graphlet_proj]{graphlet_proj()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Graphlets.html#igraph_graphlets_project}{\code{graphlets_project()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/greedy_vertex_coloring.Rd b/man/greedy_vertex_coloring.Rd index cf0a5e4b8b9..238bcebed88 100644 --- a/man/greedy_vertex_coloring.Rd +++ b/man/greedy_vertex_coloring.Rd @@ -16,28 +16,21 @@ greedy_vertex_coloring( \item{...}{These dots are for future extensions and must be empty.} \item{heuristic}{The selection heuristic for the next vertex to consider. -Possible values are: \dQuote{colored_neighbors} selects the vertex with the -largest number of already colored neighbors. \dQuote{dsatur} selects the -vertex with the largest number of unique colors in its neighborhood, i.e. -its "saturation degree"; when there are several maximum saturation degree -vertices, the one with the most uncolored neighbors will be selected.} +Possible values are: \dQuote{colored_neighbors} selects the vertex with the largest number of already colored neighbors. +\dQuote{dsatur} selects the vertex with the largest number of unique colors in its neighborhood, i.e. its "saturation degree"; +when there are several maximum saturation degree vertices, the one with the most uncolored neighbors will be selected.} } \value{ -A numeric vector where item \code{i} contains the color index -associated to vertex \code{i}. +A numeric vector where item \code{i} contains the color index associated to vertex \code{i}. } \description{ -\code{greedy_vertex_coloring()} finds a coloring for the vertices of a graph -based on a simple greedy algorithm. +\code{greedy_vertex_coloring()} finds a coloring for the vertices of a graph based on a simple greedy algorithm. } \details{ -The goal of vertex coloring is to assign a "color" (represented as a positive -integer) to each vertex of the graph such that neighboring vertices never -have the same color. This function solves the problem by considering the -vertices one by one according to a heuristic, always choosing the smallest -color that differs from that of already colored neighbors. The coloring -obtained this way is not necessarily minimum but it can be calculated in -linear time. +The goal of vertex coloring is to assign a "color" (represented as a positive integer) to each vertex of the graph such that neighboring vertices never have the same color. +This function solves the problem by considering the vertices one by one according to a heuristic, +always choosing the smallest color that differs from that of already colored neighbors. +The coloring obtained this way is not necessarily minimum but it can be calculated in linear time. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Coloring.html#igraph_vertex_coloring_greedy}{\code{vertex_coloring_greedy()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/grg.game.Rd b/man/grg.game.Rd index 22343e30481..d4ab3ca38e6 100644 --- a/man/grg.game.Rd +++ b/man/grg.game.Rd @@ -9,19 +9,16 @@ grg.game(nodes, radius, torus = FALSE, coords = FALSE) \arguments{ \item{nodes}{The number of vertices in the graph.} -\item{radius}{The radius within which the vertices will be connected by an -edge.} +\item{radius}{The radius within which the vertices will be connected by an edge.} \item{torus}{Logical, whether to use a torus instead of a square.} -\item{coords}{Logical, whether to add the positions of the vertices -as vertex attributes called \sQuote{\code{x}} and \sQuote{\code{y}}.} +\item{coords}{Logical, whether to add the positions of the vertices as vertex attributes called \sQuote{\code{x}} and \sQuote{\code{y}}.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{grg.game()} was renamed to \code{\link[=sample_grg]{sample_grg()}} to create a more -consistent API. +\code{grg.game()} was renamed to \code{\link[=sample_grg]{sample_grg()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/groups.Rd b/man/groups.Rd index 55861d7bc0c..4570eafe08b 100644 --- a/man/groups.Rd +++ b/man/groups.Rd @@ -9,22 +9,21 @@ groups(x) } \arguments{ -\item{x}{Some object that represents a grouping of the vertices. See details -below.} +\item{x}{Some object that represents a grouping of the vertices. +See details below.} } \value{ -A named list of numeric or character vectors. The names are just -numbers that refer to the groups. The vectors themselves are numeric or -symbolic vertex IDs. +A named list of numeric or character vectors. +The names are just numbers that refer to the groups. +The vectors themselves are numeric or symbolic vertex IDs. } \description{ -Create a list of vertex groups from some graph clustering or community -structure. +Create a list of vertex groups from some graph clustering or community structure. } \details{ -Currently two methods are defined for this function. The default method -works on the output of \code{\link[=components]{components()}}. (In fact it works on any -object that is a list with an entry called \code{membership}.) +Currently two methods are defined for this function. +The default method works on the output of \code{\link[=components]{components()}}. +(In fact it works on any object that is a list with an entry called \code{membership}.) The second method works on \code{\link[=communities]{communities()}} objects. } @@ -37,8 +36,7 @@ g2 <- make_ring(10) + make_full_graph(5) groups(components(g2)) } \seealso{ -\code{\link[=components]{components()}} and the various community finding -functions. +\code{\link[=components]{components()}} and the various community finding functions. Community detection: \code{\link[=as_membership]{as_membership()}}, diff --git a/man/growing.random.game.Rd b/man/growing.random.game.Rd index 1f10b90f700..3175df616fa 100644 --- a/man/growing.random.game.Rd +++ b/man/growing.random.game.Rd @@ -13,14 +13,13 @@ growing.random.game(n, m = 1, directed = TRUE, citation = FALSE) \item{directed}{Logical, whether to create a directed graph.} -\item{citation}{Logical. If \code{TRUE} a citation graph is created, i.e. in -each time step the added edges are originating from the new vertex.} +\item{citation}{Logical. +If \code{TRUE} a citation graph is created, i.e. in each time step the added edges are originating from the new vertex.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{growing.random.game()} was renamed to \code{\link[=sample_growing]{sample_growing()}} to create a more -consistent API. +\code{growing.random.game()} was renamed to \code{\link[=sample_growing]{sample_growing()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_growing_random_game}{\code{growing_random_game()}} diff --git a/man/handle_vertex_type_arg.Rd b/man/handle_vertex_type_arg.Rd index 52fdb07eede..d3e7c408808 100644 --- a/man/handle_vertex_type_arg.Rd +++ b/man/handle_vertex_type_arg.Rd @@ -14,18 +14,15 @@ handle_vertex_type_arg(types, graph, required = TRUE) \item{required}{whether the graph has to be bipartite} } \value{ -A logical vector representing the resolved vertex type for each -vertex in the graph +A logical vector representing the resolved vertex type for each vertex in the graph } \description{ -This function takes the \code{types} and \code{graph} arguments from a -public igraph function call and validates the vertex type vector. +This function takes the \code{types} and \code{graph} arguments from a public igraph function call and validates the vertex type vector. } \details{ -When the provided vertex types are NULL and the graph has a \code{types} -vertex attribute, then the value of this vertex attribute will be used as -vertex types. Non-logical vertex type vectors are coerced into logical -vectors after printing a warning. +When the provided vertex types are NULL and the graph has a \code{types} vertex attribute, +then the value of this vertex attribute will be used as vertex types. +Non-logical vertex type vectors are coerced into logical vectors after printing a warning. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/harmonic_centrality.Rd b/man/harmonic_centrality.Rd index 1c93bc61cac..f521ff41046 100644 --- a/man/harmonic_centrality.Rd +++ b/man/harmonic_centrality.Rd @@ -22,39 +22,34 @@ The default \code{NULL} selects all vertices.} \item{...}{These dots are for future extensions and must be empty.} -\item{mode}{Character string, defining the types of the paths used for -measuring the distance in directed graphs. \dQuote{out} follows paths along -the edge directions only, \dQuote{in} traverses the edges in reverse, while -\dQuote{all} ignores edge directions. This argument is ignored for undirected -graphs.} +\item{mode}{Character string, defining the types of the paths used for measuring the distance in directed graphs. +\dQuote{out} follows paths along the edge directions only, \dQuote{in} traverses the edges in reverse, +while \dQuote{all} ignores edge directions. +This argument is ignored for undirected graphs.} -\item{weights}{Optional positive weight vector for calculating weighted -harmonic centrality. If the graph has a \code{weight} edge attribute, then -this is used by default. Weights are used for calculating weighted shortest -paths, so they are interpreted as distances.} +\item{weights}{Optional positive weight vector for calculating weighted harmonic centrality. +If the graph has a \code{weight} edge attribute, then this is used by default. +Weights are used for calculating weighted shortest paths, so they are interpreted as distances.} -\item{normalized}{Logical, whether to calculate the normalized -harmonic centrality. If true, the result is the mean inverse path length to -other vertices, i.e. it is normalized by the number of vertices minus one. +\item{normalized}{Logical, whether to calculate the normalized harmonic centrality. +If true, the result is the mean inverse path length to other vertices, i.e. it is normalized by the number of vertices minus one. If false, the result is the sum of inverse path lengths to other vertices.} -\item{cutoff}{The maximum path length to consider when calculating the -harmonic centrality. There is no such limit when the cutoff is negative. Note that -zero cutoff means that only paths of at most length 0 are considered.} +\item{cutoff}{The maximum path length to consider when calculating the harmonic centrality. +There is no such limit when the cutoff is negative. +Note that zero cutoff means that only paths of at most length 0 are considered.} } \value{ -Numeric vector with the harmonic centrality scores of all the vertices in -\code{v}. +Numeric vector with the harmonic centrality scores of all the vertices in \code{v}. } \description{ -The harmonic centrality of a vertex is the mean inverse distance to all other -vertices. The inverse distance to an unreachable vertex is considered to be zero. +The harmonic centrality of a vertex is the mean inverse distance to all other vertices. +The inverse distance to an unreachable vertex is considered to be zero. } \details{ -The \code{cutoff} argument can be used to restrict the calculation to paths -of length \code{cutoff} or smaller only; this can be used for larger graphs -to speed up the calculation. If \code{cutoff} is negative (which is the -default), then the function calculates the exact harmonic centrality scores. +The \code{cutoff} argument can be used to restrict the calculation to paths of length \code{cutoff} or smaller only; +this can be used for larger graphs to speed up the calculation. +If \code{cutoff} is negative (which is the default), then the function calculates the exact harmonic centrality scores. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_harmonic_centrality_cutoff}{\code{harmonic_centrality_cutoff()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/has.multiple.Rd b/man/has.multiple.Rd index 318966fa07e..717725bfdd2 100644 --- a/man/has.multiple.Rd +++ b/man/has.multiple.Rd @@ -12,8 +12,7 @@ has.multiple(graph) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{has.multiple()} was renamed to \code{\link[=any_multiple]{any_multiple()}} to create a more -consistent API. +\code{has.multiple()} was renamed to \code{\link[=any_multiple]{any_multiple()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_has_multiple}{\code{has_multiple()}} diff --git a/man/has_eulerian_path.Rd b/man/has_eulerian_path.Rd index 26e6d70d8cc..8bbb14c57c2 100644 --- a/man/has_eulerian_path.Rd +++ b/man/has_eulerian_path.Rd @@ -19,10 +19,9 @@ eulerian_cycle(graph) \item{graph}{An igraph graph object} } \value{ -For \code{has_eulerian_path()} and \code{has_eulerian_cycle()}, a logical -value that indicates whether the graph contains an Eulerian path or cycle. -For \code{eulerian_path()} and \code{eulerian_cycle()}, a named list with two -entries: +For \code{has_eulerian_path()} and \code{has_eulerian_cycle()}, +a logical value that indicates whether the graph contains an Eulerian path or cycle. +For \code{eulerian_path()} and \code{eulerian_cycle()}, a named list with two entries: \describe{ \item{epath}{ A vector containing the edge IDs along the Eulerian path or cycle. @@ -33,23 +32,20 @@ A vector containing the vertex IDs along the Eulerian path or cycle. } } \description{ -\code{has_eulerian_path()} and \code{has_eulerian_cycle()} checks whether there -is an Eulerian path or cycle in the input graph. \code{eulerian_path()} and -\code{eulerian_cycle()} return such a path or cycle if it exists, and throws -an error otherwise. +\code{has_eulerian_path()} and \code{has_eulerian_cycle()} checks whether there is an Eulerian path or cycle in the input graph. +\code{eulerian_path()} and \code{eulerian_cycle()} return such a path or cycle if it exists, and throws an error otherwise. } \details{ -\code{has_eulerian_path()} decides whether the input graph has an Eulerian -\emph{path}, i.e. a path that passes through every edge of the graph exactly -once, and returns a logical value as a result. \code{eulerian_path()} returns -a possible Eulerian path, described with its edge and vertex sequence, or -throws an error if no such path exists. +\code{has_eulerian_path()} decides whether the input graph has an Eulerian \emph{path}, +i.e. a path that passes through every edge of the graph exactly once, and returns a logical value as a result. +\code{eulerian_path()} returns a possible Eulerian path, described with its edge and vertex sequence, +or throws an error if no such path exists. -\code{has_eulerian_cycle()} decides whether the input graph has an Eulerian -\emph{cycle}, i.e. a path that passes through every edge of the graph exactly -once and that returns to its starting point, and returns a logical value as -a result. \code{eulerian_cycle()} returns a possible Eulerian cycle, described -with its edge and vertex sequence, or throws an error if no such cycle exists. +\code{has_eulerian_cycle()} decides whether the input graph has an Eulerian \emph{cycle}, +i.e. a path that passes through every edge of the graph exactly once and that returns to its starting point, +and returns a logical value as a result. +\code{eulerian_cycle()} returns a possible Eulerian cycle, described with its edge and vertex sequence, +or throws an error if no such cycle exists. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Cycles.html#igraph_is_eulerian}{\code{is_eulerian()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Cycles.html#igraph_eulerian_path}{\code{eulerian_path()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Cycles.html#igraph_eulerian_cycle}{\code{eulerian_cycle()}} diff --git a/man/head_of.Rd b/man/head_of.Rd index 4e916b2631c..c368735364d 100644 --- a/man/head_of.Rd +++ b/man/head_of.Rd @@ -15,9 +15,8 @@ head_of(graph, es) A vertex sequence with the head(s) of the edge(s). } \description{ -For undirected graphs, head and tail is not defined. In this case -\code{head_of()} returns vertices incident to the supplied edges, and -\code{tail_of()} returns the other end(s) of the edge(s). +For undirected graphs, head and tail is not defined. +In this case \code{head_of()} returns vertices incident to the supplied edges, and \code{tail_of()} returns the other end(s) of the edge(s). } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/head_print.Rd b/man/head_print.Rd index 603eccca3dd..16974412a1e 100644 --- a/man/head_print.Rd +++ b/man/head_print.Rd @@ -14,11 +14,10 @@ head_print( ) } \arguments{ -\item{x}{The object to print, or a callback function. See -\code{\link[=printer_callback]{printer_callback()}} for details.} +\item{x}{The object to print, or a callback function. +See \code{\link[=printer_callback]{printer_callback()}} for details.} -\item{max_lines}{Maximum number of lines to print, \emph{not} -including the header and the footer.} +\item{max_lines}{Maximum number of lines to print, \emph{not} including the header and the footer.} \item{header}{The header, if a function, then it will be called, otherwise printed using \code{cat}.} @@ -26,9 +25,8 @@ otherwise printed using \code{cat}.} \item{footer}{The footer, if a function, then it will be called, otherwise printed using \code{cat}.} -\item{omitted_footer}{Footer that is only printed if anything -is omitted from the printout. If a function, then it will be called, -otherwise printed using \code{cat}.} +\item{omitted_footer}{Footer that is only printed if anything is omitted from the printout. +If a function, then it will be called, otherwise printed using \code{cat}.} \item{...}{Extra arguments to pass to \code{print()}.} } diff --git a/man/hits_scores.Rd b/man/hits_scores.Rd index ee1440b68c5..94f5c84868e 100644 --- a/man/hits_scores.Rd +++ b/man/hits_scores.Rd @@ -11,18 +11,18 @@ hits_scores(graph, ..., scale = TRUE, weights = NULL, options = NULL) \item{...}{These dots are for future extensions and must be empty.} -\item{scale}{Logical, whether to scale the result to have a maximum -score of one. If no scaling is used then the result vector has unit length -in the Euclidean norm.} +\item{scale}{Logical, whether to scale the result to have a maximum score of one. +If no scaling is used then the result vector has unit length in the Euclidean norm.} -\item{weights}{Optional positive weight vector for calculating weighted -scores. If the graph has a \code{weight} edge attribute, then this is used -by default. Pass \code{NA} to ignore the weight attribute. This function -interprets edge weights as connection strengths. The weights of parallel -edges are effectively added up.} +\item{weights}{Optional positive weight vector for calculating weighted scores. +If the graph has a \code{weight} edge attribute, then this is used by default. +Pass \code{NA} to ignore the weight attribute. +This function interprets edge weights as connection strengths. +The weights of parallel edges are effectively added up.} -\item{options}{A named list, to override some ARPACK options. See -\code{\link[=arpack]{arpack()}} for details. The default \code{NULL} uses \code{\link[=arpack_defaults]{arpack_defaults()}}.} +\item{options}{A named list, to override some ARPACK options. +See \code{\link[=arpack]{arpack()}} for details. +The default \code{NULL} uses \code{\link[=arpack_defaults]{arpack_defaults()}}.} } \value{ A named list with members: @@ -42,17 +42,14 @@ Some information about the ARPACK computation, it has the same members as the \c } } \description{ -The hub scores of the vertices are defined as the principal eigenvector -of \eqn{A A^T}{A*t(A)}, where \eqn{A} is the adjacency matrix of the -graph. +The hub scores of the vertices are defined as the principal eigenvector of \eqn{A A^T}{A*t(A)}, +where \eqn{A} is the adjacency matrix of the graph. } \details{ -Similarly, the authority scores of the vertices are defined as the principal -eigenvector of \eqn{A^T A}{t(A)*A}, where \eqn{A} is the adjacency matrix of -the graph. +Similarly, the authority scores of the vertices are defined as the principal eigenvector of \eqn{A^T A}{t(A)*A}, +where \eqn{A} is the adjacency matrix of the graph. -For undirected matrices the adjacency matrix is symmetric and the hub -scores are the same as authority scores. +For undirected matrices the adjacency matrix is symmetric and the hub scores are the same as authority scores. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_hub_and_authority_scores}{\code{hub_and_authority_scores()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} @@ -74,9 +71,8 @@ environment. \emph{Proc. 9th ACM-SIAM Symposium on Discrete Algorithms}, as IBM Research Report RJ 10076, May 1997. } \seealso{ -\code{\link[=eigen_centrality]{eigen_centrality()}} for eigenvector centrality, -\code{\link[=page_rank]{page_rank()}} for the Page Rank scores. \code{\link[=arpack]{arpack()}} for -the underlining machinery of the computation. +\code{\link[=eigen_centrality]{eigen_centrality()}} for eigenvector centrality, \code{\link[=page_rank]{page_rank()}} for the Page Rank scores. +\code{\link[=arpack]{arpack()}} for the underlining machinery of the computation. Centrality measures: \code{\link[=alpha_centrality]{alpha_centrality()}}, diff --git a/man/hrg-methods.Rd b/man/hrg-methods.Rd index 11306813906..baf842f570c 100644 --- a/man/hrg-methods.Rd +++ b/man/hrg-methods.Rd @@ -7,24 +7,18 @@ Fitting and sampling hierarchical random graph models. } \details{ -A hierarchical random graph is an ensemble of undirected graphs with \eqn{n} -vertices. It is defined via a binary tree with \eqn{n} leaf and \eqn{n-1} -internal vertices, where the internal vertices are labeled with -probabilities. The probability that two vertices are connected in the -random graph is given by the probability label at their closest common -ancestor. +A hierarchical random graph is an ensemble of undirected graphs with \eqn{n} vertices. +It is defined via a binary tree with \eqn{n} leaf and \eqn{n-1} internal vertices, +where the internal vertices are labeled with probabilities. +The probability that two vertices are connected in the random graph is given by the probability label at their closest common ancestor. Please see references below for more about hierarchical random graphs. -igraph contains functions for fitting HRG models to a given network -(\code{fit_hrg()}, for generating networks from a given HRG ensemble -(\code{sample_hrg()}), converting an igraph graph to a HRG and back -(\code{hrg()}, \code{hrg_tree()}), for calculating a consensus tree from a set -of sampled HRGs (\code{consensus_tree()}) and for predicting missing edges in -a network based on its HRG models (\code{predict_edges()}). +igraph contains functions for fitting HRG models to a given network (\code{fit_hrg()}, +for generating networks from a given HRG ensemble (\code{sample_hrg()}), converting an igraph graph to a HRG and back (\code{hrg()}, \code{hrg_tree()}), +for calculating a consensus tree from a set of sampled HRGs (\code{consensus_tree()}) and for predicting missing edges in a network based on its HRG models (\code{predict_edges()}). -The igraph HRG implementation is heavily based on the code published by -Aaron Clauset, at his website (not functional any more). +The igraph HRG implementation is heavily based on the code published by Aaron Clauset, at his website (not functional any more). } \seealso{ Other hierarchical random graph functions: diff --git a/man/hrg.Rd b/man/hrg.Rd index 5e46f51b9ce..25361eb6bf2 100644 --- a/man/hrg.Rd +++ b/man/hrg.Rd @@ -9,17 +9,15 @@ hrg(graph, prob) \arguments{ \item{graph}{The igraph graph to create the HRG from.} -\item{prob}{A vector of probabilities, one for each vertex, in the order of -vertex IDs.} +\item{prob}{A vector of probabilities, one for each vertex, in the order of vertex IDs.} } \value{ \code{hrg()} returns an \code{igraphHRG} object. } \description{ -\code{hrg()} creates a HRG from an igraph graph. The igraph graph must be -a directed binary tree, with \eqn{n-1} internal and \eqn{n} leaf -vertices. The \code{prob} argument contains the HRG probability labels -for each vertex; these are ignored for leaf vertices. +\code{hrg()} creates a HRG from an igraph graph. +The igraph graph must be a directed binary tree, with \eqn{n-1} internal and \eqn{n} leaf vertices. +The \code{prob} argument contains the HRG probability labels for each vertex; these are ignored for leaf vertices. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-HRG.html#igraph_hrg_create}{\code{hrg_create()}} diff --git a/man/hrg.consensus.Rd b/man/hrg.consensus.Rd index 1b38683cbc5..d29c812e16c 100644 --- a/man/hrg.consensus.Rd +++ b/man/hrg.consensus.Rd @@ -9,22 +9,17 @@ hrg.consensus(graph, hrg = NULL, start = FALSE, num.samples = 10000) \arguments{ \item{graph}{The graph the models were fitted to.} -\item{hrg}{A hierarchical random graph model, in the form of an -\code{igraphHRG} object. \code{consensus_tree()} allows this to be -\code{NULL} as well, then a HRG is fitted to the graph first, from a -random starting point.} +\item{hrg}{A hierarchical random graph model, in the form of an \code{igraphHRG} object. +\code{consensus_tree()} allows this to be \code{NULL} as well, then a HRG is fitted to the graph first, from a random starting point.} -\item{start}{Logical, whether to start the fitting/sampling from the -supplied \code{igraphHRG} object, or from a random starting point.} +\item{start}{Logical, whether to start the fitting/sampling from the supplied \code{igraphHRG} object, or from a random starting point.} -\item{num.samples}{Number of samples to use for consensus generation or -missing edge prediction.} +\item{num.samples}{Number of samples to use for consensus generation or missing edge prediction.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{hrg.consensus()} was renamed to \code{\link[=consensus_tree]{consensus_tree()}} to create a more -consistent API. +\code{hrg.consensus()} was renamed to \code{\link[=consensus_tree]{consensus_tree()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-HRG.html#igraph_hrg_consensus}{\code{hrg_consensus()}} diff --git a/man/hrg.create.Rd b/man/hrg.create.Rd index 886c8600894..0afdfc2a86c 100644 --- a/man/hrg.create.Rd +++ b/man/hrg.create.Rd @@ -9,14 +9,12 @@ hrg.create(graph, prob) \arguments{ \item{graph}{The igraph graph to create the HRG from.} -\item{prob}{A vector of probabilities, one for each vertex, in the order of -vertex IDs.} +\item{prob}{A vector of probabilities, one for each vertex, in the order of vertex IDs.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{hrg.create()} was renamed to \code{\link[=hrg]{hrg()}} to create a more -consistent API. +\code{hrg.create()} was renamed to \code{\link[=hrg]{hrg()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-HRG.html#igraph_hrg_create}{\code{hrg_create()}} diff --git a/man/hrg.dendrogram.Rd b/man/hrg.dendrogram.Rd index 75c18c76c22..45f2046666d 100644 --- a/man/hrg.dendrogram.Rd +++ b/man/hrg.dendrogram.Rd @@ -12,8 +12,7 @@ hrg.dendrogram(hrg) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{hrg.dendrogram()} was renamed to \code{\link[=hrg_tree]{hrg_tree()}} to create a more -consistent API. +\code{hrg.dendrogram()} was renamed to \code{\link[=hrg_tree]{hrg_tree()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-HRG.html#igraph_from_hrg_dendrogram}{\code{from_hrg_dendrogram()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/hrg.fit.Rd b/man/hrg.fit.Rd index 688a2628ce9..ca1af17da48 100644 --- a/man/hrg.fit.Rd +++ b/man/hrg.fit.Rd @@ -7,24 +7,21 @@ hrg.fit(graph, hrg = NULL, start = FALSE, steps = 0) } \arguments{ -\item{graph}{The graph to fit the model to. Edge directions are ignored in -directed graphs.} +\item{graph}{The graph to fit the model to. +Edge directions are ignored in directed graphs.} -\item{hrg}{A hierarchical random graph model, in the form of an -\code{igraphHRG} object. \code{fit_hrg()} allows this to be \code{NULL}, in -which case a random starting point is used for the fitting.} +\item{hrg}{A hierarchical random graph model, in the form of an \code{igraphHRG} object. +\code{fit_hrg()} allows this to be \code{NULL}, in which case a random starting point is used for the fitting.} -\item{start}{Logical, whether to start the fitting/sampling from the -supplied \code{igraphHRG} object, or from a random starting point.} +\item{start}{Logical, whether to start the fitting/sampling from the supplied \code{igraphHRG} object, or from a random starting point.} -\item{steps}{The number of MCMC steps to make. If this is zero, then the -MCMC procedure is performed until convergence.} +\item{steps}{The number of MCMC steps to make. +If this is zero, then the MCMC procedure is performed until convergence.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{hrg.fit()} was renamed to \code{\link[=fit_hrg]{fit_hrg()}} to create a more -consistent API. +\code{hrg.fit()} was renamed to \code{\link[=fit_hrg]{fit_hrg()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-HRG.html#igraph_hrg_fit}{\code{hrg_fit()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/hrg.game.Rd b/man/hrg.game.Rd index c2c70f5960a..d075fe1f453 100644 --- a/man/hrg.game.Rd +++ b/man/hrg.game.Rd @@ -12,8 +12,7 @@ hrg.game(hrg) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{hrg.game()} was renamed to \code{\link[=sample_hrg]{sample_hrg()}} to create a more -consistent API. +\code{hrg.game()} was renamed to \code{\link[=sample_hrg]{sample_hrg()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-HRG.html#igraph_hrg_game}{\code{hrg_game()}} diff --git a/man/hrg.predict.Rd b/man/hrg.predict.Rd index 6ec3fdb1dc9..779a876c372 100644 --- a/man/hrg.predict.Rd +++ b/man/hrg.predict.Rd @@ -13,28 +13,23 @@ hrg.predict( ) } \arguments{ -\item{graph}{The graph to fit the model to. Edge directions are ignored in -directed graphs.} +\item{graph}{The graph to fit the model to. +Edge directions are ignored in directed graphs.} -\item{hrg}{A hierarchical random graph model, in the form of an -\code{igraphHRG} object. \code{predict_edges()} allow this to be -\code{NULL} as well, then a HRG is fitted to the graph first, from a -random starting point.} +\item{hrg}{A hierarchical random graph model, in the form of an \code{igraphHRG} object. +\code{predict_edges()} allow this to be \code{NULL} as well, then a HRG is fitted to the graph first, from a random starting point.} -\item{start}{Logical, whether to start the fitting/sampling from the -supplied \code{igraphHRG} object, or from a random starting point.} +\item{start}{Logical, whether to start the fitting/sampling from the supplied \code{igraphHRG} object, or from a random starting point.} -\item{num.samples}{Number of samples to use for consensus generation or -missing edge prediction.} +\item{num.samples}{Number of samples to use for consensus generation or missing edge prediction.} -\item{num.bins}{Number of bins for the edge probabilities. Give a higher -number for a more accurate prediction.} +\item{num.bins}{Number of bins for the edge probabilities. +Give a higher number for a more accurate prediction.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{hrg.predict()} was renamed to \code{\link[=predict_edges]{predict_edges()}} to create a more -consistent API. +\code{hrg.predict()} was renamed to \code{\link[=predict_edges]{predict_edges()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-HRG.html#igraph_hrg_predict}{\code{hrg_predict()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/hrg_tree.Rd b/man/hrg_tree.Rd index 814046c1684..4ff1e173bf8 100644 --- a/man/hrg_tree.Rd +++ b/man/hrg_tree.Rd @@ -13,8 +13,7 @@ hrg_tree(hrg) An igraph graph with a vertex attribute called \code{"probability"}. } \description{ -\code{hrg_tree()} creates the corresponsing igraph tree of a hierarchical -random graph model. +\code{hrg_tree()} creates the corresponsing igraph tree of a hierarchical random graph model. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-HRG.html#igraph_from_hrg_dendrogram}{\code{from_hrg_dendrogram()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/hub.score.Rd b/man/hub.score.Rd index c36dff232ed..eb23bb65e95 100644 --- a/man/hub.score.Rd +++ b/man/hub.score.Rd @@ -9,24 +9,20 @@ hub.score(graph, scale = TRUE, weights = NULL, options = arpack_defaults()) \arguments{ \item{graph}{The input graph.} -\item{scale}{Logical, whether to scale the result to have a maximum -score of one. If no scaling is used then the result vector has unit length -in the Euclidean norm.} +\item{scale}{Logical, whether to scale the result to have a maximum score of one. +If no scaling is used then the result vector has unit length in the Euclidean norm.} -\item{weights}{Optional positive weight vector for calculating weighted -scores. If the graph has a \code{weight} edge attribute, then this is used -by default. -This function interprets edge weights as connection strengths. In the -random surfer model, an edge with a larger weight is more likely to be -selected by the surfer.} +\item{weights}{Optional positive weight vector for calculating weighted scores. +If the graph has a \code{weight} edge attribute, then this is used by default. +This function interprets edge weights as connection strengths. +In the random surfer model, an edge with a larger weight is more likely to be selected by the surfer.} -\item{options}{A named list, to override some ARPACK options. See -\code{\link[=arpack]{arpack()}} for details.} +\item{options}{A named list, to override some ARPACK options. +See \code{\link[=arpack]{arpack()}} for details.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{hub.score()} was renamed to \code{\link[=hub_score]{hub_score()}} to create a more -consistent API. +\code{hub.score()} was renamed to \code{\link[=hub_score]{hub_score()}} to create a more consistent API. } \keyword{internal} diff --git a/man/hub_score.Rd b/man/hub_score.Rd index 8bfd4b8636d..41e7660c94d 100644 --- a/man/hub_score.Rd +++ b/man/hub_score.Rd @@ -17,19 +17,16 @@ hub_score(graph, scale = TRUE, weights = NULL, options = arpack_defaults()) \arguments{ \item{graph}{The input graph.} -\item{scale}{Logical, whether to scale the result to have a maximum -score of one. If no scaling is used then the result vector has unit length -in the Euclidean norm.} +\item{scale}{Logical, whether to scale the result to have a maximum score of one. +If no scaling is used then the result vector has unit length in the Euclidean norm.} -\item{weights}{Optional positive weight vector for calculating weighted -scores. If the graph has a \code{weight} edge attribute, then this is used -by default. -This function interprets edge weights as connection strengths. In the -random surfer model, an edge with a larger weight is more likely to be -selected by the surfer.} +\item{weights}{Optional positive weight vector for calculating weighted scores. +If the graph has a \code{weight} edge attribute, then this is used by default. +This function interprets edge weights as connection strengths. +In the random surfer model, an edge with a larger weight is more likely to be selected by the surfer.} -\item{options}{A named list, to override some ARPACK options. See -\code{\link[=arpack]{arpack()}} for details.} +\item{options}{A named list, to override some ARPACK options. +See \code{\link[=arpack]{arpack()}} for details.} } \description{ Kleinberg's authority centrality scores. diff --git a/man/identical_graphs.Rd b/man/identical_graphs.Rd index ed60154f8c6..6ead78497c7 100644 --- a/man/identical_graphs.Rd +++ b/man/identical_graphs.Rd @@ -17,18 +17,14 @@ identical_graphs(g1, g2, ..., attrs = TRUE) Logical scalar } \description{ -Two graphs are considered identical by this function if and only if -they are represented in exactly the same way in the internal R -representation. This means that the two graphs must have the same -list of vertices and edges, in exactly the same order, with same -directedness, and the two graphs must also have identical graph, vertex and -edge attributes. +Two graphs are considered identical by this function if and only +if they are represented in exactly the same way in the internal R representation. +This means that the two graphs must have the same list of vertices and edges, in exactly the same order, with same directedness, +and the two graphs must also have identical graph, vertex and edge attributes. } \details{ -This is similar to \code{identical} in the \code{base} package, -but it ignores the mutable piece of igraph objects; those might be -different even if the two graphs are identical. +This is similar to \code{identical} in the \code{base} package, but it ignores the mutable piece of igraph objects; +those might be different even if the two graphs are identical. -Attribute comparison can be turned off with the \code{attrs} parameter if -the attributes of the two graphs are allowed to be different. +Attribute comparison can be turned off with the \code{attrs} parameter if the attributes of the two graphs are allowed to be different. } diff --git a/man/igraph-attribute-combination.Rd b/man/igraph-attribute-combination.Rd index 03e5e10f460..ff15f7b94fb 100644 --- a/man/igraph-attribute-combination.Rd +++ b/man/igraph-attribute-combination.Rd @@ -5,19 +5,14 @@ \alias{attribute.combination} \title{How igraph functions handle attributes when the graph changes} \description{ -Many times, when the structure of a graph is modified, vertices/edges map of -the original graph map to vertices/edges in the newly created (modified) -graph. For example \code{\link[=simplify]{simplify()}} maps multiple edges to single -edges. igraph provides a flexible mechanism to specify what to do with the -vertex/edge attributes in these cases. +Many times, when the structure of a graph is modified, +vertices/edges map of the original graph map to vertices/edges in the newly created (modified) graph. +For example \code{\link[=simplify]{simplify()}} maps multiple edges to single edges. igraph provides a flexible mechanism to specify what to do with the 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} -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 -attributes of the new graph. +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} 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 attributes of the new graph. The specification of the combination of (vertex or edge) attributes can be given as \enumerate{ @@ -26,21 +21,19 @@ given as \enumerate{ \item a list of character scalars and/or function objects. } -If it is a character scalar, then it refers to one of the predefined -combinations, see their list below. +If it is a character scalar, then it refers to one of the predefined combinations, see their list below. -If it is a function, then the given function is expected to perform the -combination. It will be called once for each new vertex/edge in the graph, -with a single argument: the attribute values of the vertices that map to -that single vertex. +If it is a function, then the given function is expected to perform the combination. +It will be called once for each new vertex/edge in the graph, with a single argument: +the attribute values of the vertices that map to that single vertex. -The third option, a list can be used to specify different combination -methods for different attributes. A named entry of the list corresponds to -the attribute with the same name. An unnamed entry (i.e. if the name is the -empty string) of the list specifies the default combination method. I.e. +The third option, a list can be used to specify different combination methods for different attributes. +A named entry of the list corresponds to the attribute with the same name. +An unnamed entry (i.e. if the name is the empty string) of the list specifies the default combination method. +I.e. \preformatted{list(weight="sum", "ignore")} specifies that the weight of the -new edge should be sum of the weights of the corresponding edges in the old -graph; and that the rest of the attributes should be ignored (=dropped). +new edge should be sum of the weights of the corresponding edges in the old graph; +and that the rest of the attributes should be ignored (=dropped). } \section{Predefined combination functions}{ The following combination @@ -94,16 +87,13 @@ Concatenate the attributes, using the \code{\link[=c]{c()}} function. This results almost always a complex attribute. } \item{"rename"}{ -Keep clashing attributes side-by-side under disambiguated names by -appending \verb{_1}, \verb{_2}, ... suffixes. For example, if two graphs each -have an attribute called \code{group}, the resulting graph will have -attributes \code{group_1} and \code{group_2}, corresponding to the first and -second input graph, respectively. This is the default for the -graph operators \code{\link[=union]{union()}}, \code{\link[=intersection]{intersection()}}, \code{\link[=compose]{compose()}} and -\code{\link[=disjoint_union]{disjoint_union()}} and preserves their historical behaviour. -Only those operators accept \code{"rename"}; \code{\link[=simplify]{simplify()}} and -\code{\link[=contract]{contract()}} will reject it because the rename strategy has no -per-element interpretation when many input values collapse into one. +Keep clashing attributes side-by-side under disambiguated names by appending \verb{_1}, \verb{_2}, ... suffixes. +For example, if two graphs each have an attribute called \code{group}, the resulting graph will have attributes \code{group_1} and \code{group_2}, +corresponding to the first and second input graph, respectively. +This is the default for the graph operators \code{\link[=union]{union()}}, \code{\link[=intersection]{intersection()}}, \code{\link[=compose]{compose()}} and \code{\link[=disjoint_union]{disjoint_union()}} +and preserves their historical behaviour. +Only those operators accept \code{"rename"}; \code{\link[=simplify]{simplify()}} and \code{\link[=contract]{contract()}} will reject it because the rename strategy has no per-element interpretation +when many input values collapse into one. } } } @@ -140,9 +130,8 @@ simplify(g, edge.attr.comb = list( )) } \seealso{ -\code{\link[=graph_attr]{graph_attr()}}, \code{\link[=vertex_attr]{vertex_attr()}}, -\code{\link[=edge_attr]{edge_attr()}} on how to use graph/vertex/edge attributes in -general. \code{\link[=igraph_options]{igraph_options()}} on igraph parameters. +\code{\link[=graph_attr]{graph_attr()}}, \code{\link[=vertex_attr]{vertex_attr()}}, \code{\link[=edge_attr]{edge_attr()}} on how to use graph/vertex/edge attributes in general. +\code{\link[=igraph_options]{igraph_options()}} on igraph parameters. Vertex, edge and graph attributes: \code{\link[=delete_edge_attr]{delete_edge_attr()}}, diff --git a/man/igraph-dollar.Rd b/man/igraph-dollar.Rd index 5a79ec0b8b6..707256a14c8 100644 --- a/man/igraph-dollar.Rd +++ b/man/igraph-dollar.Rd @@ -18,9 +18,8 @@ \item{value}{New value of the graph attribute.} } \description{ -The \code{$} operator is a shortcut to get and and set -graph attributes. It is shorter and just as readable as -\code{\link[=graph_attr]{graph_attr()}} and \code{\link[=set_graph_attr]{set_graph_attr()}}. +The \code{$} operator is a shortcut to get and and set graph attributes. +It is shorter and just as readable as \code{\link[=graph_attr]{graph_attr()}} and \code{\link[=set_graph_attr]{set_graph_attr()}}. } \examples{ g <- make_ring(10) diff --git a/man/igraph-es-attributes.Rd b/man/igraph-es-attributes.Rd index 02196b74b07..572eeda6136 100644 --- a/man/igraph-es-attributes.Rd +++ b/man/igraph-es-attributes.Rd @@ -20,40 +20,35 @@ E(x, path = NULL, P = NULL, directed = NULL) <- value } \arguments{ -\item{x}{An edge sequence. For \verb{E<-} it is a graph.} +\item{x}{An edge sequence. +For \verb{E<-} it is a graph.} \item{i}{Index.} -\item{value}{New value of the attribute, for the edges in the edge -sequence.} +\item{value}{New value of the attribute, for the edges in the edge sequence.} \item{name}{Name of the edge attribute to query or set.} -\item{path}{Select edges along a path, given by a vertex sequence See -\code{\link[=E]{E()}}.} +\item{path}{Select edges along a path, given by a vertex sequence See \code{\link[=E]{E()}}.} -\item{P}{Select edges via pairs of vertices. See \code{\link[=E]{E()}}.} +\item{P}{Select edges via pairs of vertices. +See \code{\link[=E]{E()}}.} -\item{directed}{Whether to use edge directions for the \code{path} or -\code{P} arguments.} +\item{directed}{Whether to use edge directions for the \code{path} or \code{P} arguments.} } \value{ -A vector or list, containing the values of the attribute -\code{name} for the edges in the sequence. For numeric, character or -logical attributes, it is a vector of the appropriate type, otherwise -it is a list. +A vector or list, containing the values of the attribute \code{name} for the edges in the sequence. +For numeric, character or logical attributes, it is a vector of the appropriate type, otherwise it is a list. } \description{ -The \code{$} operator is a syntactic sugar to query and set -edge attributes, for edges in an edge sequence. +The \code{$} operator is a syntactic sugar to query and set edge attributes, for edges in an edge sequence. } \details{ The query form of \code{$} is a shortcut for \code{\link[=edge_attr]{edge_attr()}}, e.g. \code{E(g)[idx]$attr} is equivalent to \code{edge_attr(g, attr, E(g)[idx])}. -The assignment form of \code{$} is a shortcut for -\code{\link[=set_edge_attr]{set_edge_attr()}}, e.g. \code{E(g)[idx]$attr <- value} is -equivalent to \code{g <- set_edge_attr(g, attr, E(g)[idx], value)}. +The assignment form of \code{$} is a shortcut for \code{\link[=set_edge_attr]{set_edge_attr()}}, +e.g. \code{E(g)[idx]$attr <- value} is equivalent to \code{g <- set_edge_attr(g, attr, E(g)[idx], value)}. } \examples{ # color edges of the largest component diff --git a/man/igraph-es-indexing.Rd b/man/igraph-es-indexing.Rd index aa72a58666b..06248ca6dcc 100644 --- a/man/igraph-es-indexing.Rd +++ b/man/igraph-es-indexing.Rd @@ -24,10 +24,9 @@ with some extras. } \section{Multiple indices}{ -When using multiple indices within the bracket, all of them -are evaluated independently, and then the results are concatenated -using the \code{c()} function. E.g. \code{E(g)[1, 2, .inc(1)]} -is equivalent to \code{c(E(g)[1], E(g)[2], E(g)[.inc(1)])}. +When using multiple indices within the bracket, all of them are evaluated independently, +and then the results are concatenated using the \code{c()} function. +E.g. \code{E(g)[1, 2, .inc(1)]} is equivalent to \code{c(E(g)[1], E(g)[2], E(g)[.inc(1)])}. } \section{Index types}{ @@ -35,45 +34,38 @@ is equivalent to \code{c(E(g)[1], E(g)[2], E(g)[.inc(1)])}. Edge sequences can be indexed with positive numeric vectors, negative numeric vectors, logical vectors, character vectors: \itemize{ -\item When indexed with positive numeric vectors, the edges at the -given positions in the sequence are selected. This is the same as -indexing a regular R atomic vector with positive numeric vectors. -\item When indexed with negative numeric vectors, the edges at the -given positions in the sequence are omitted. Again, this is the same -as indexing a regular R atomic vector. -\item When indexed with a logical vector, the lengths of the edge -sequence and the index must match, and the edges for which the -index is \code{TRUE} are selected. -\item Named graphs can be indexed with character vectors, -to select edges with the given names. Note that a graph may -have edge names and vertex names, and both can be used to select -edges. Edge names are simply used as names of the numeric -edge ID vector. Vertex names effectively only work in graphs without -multiple edges, and must be separated with a \code{|} bar character -to select an edges that incident to the two given vertices. See -examples below. +\item When indexed with positive numeric vectors, the edges at the given positions in the sequence are selected. +This is the same as indexing a regular R atomic vector with positive numeric vectors. +\item When indexed with negative numeric vectors, the edges at the given positions in the sequence are omitted. +Again, this is the same as indexing a regular R atomic vector. +\item When indexed with a logical vector, the lengths of the edge sequence and the index must match, and the edges for +which the index is \code{TRUE} are selected. +\item Named graphs can be indexed with character vectors, to select edges with the given names. +Note that a graph may have edge names and vertex names, and both can be used to select edges. +Edge names are simply used as names of the numeric edge ID vector. +Vertex names effectively only work in graphs without multiple edges, and must be separated with a \code{|} bar character to select an edges +that incident to the two given vertices. +See examples below. } } \section{Edge attributes}{ -When indexing edge sequences, edge attributes can be referred -to simply by using their names. E.g. if a graph has a \code{weight} edge -attribute, then \code{E(G)[weight > 1]} selects all edges with a weight -larger than one. See more examples below. Note that attribute names mask the -names of variables present in the calling environment; if you need to look up -a variable and you do not want a similarly named edge attribute to mask it, -use the \code{.env} pronoun to perform the name lookup in the calling -environment. In other words, use \code{E(g)[.env$weight > 1]} to make sure -that \code{weight} is looked up from the calling environment even if there is -an edge attribute with the same name. Similarly, you can use \code{.data} to -match attribute names only. +When indexing edge sequences, edge attributes can be referred to simply by using their names. +E.g. if a graph has a \code{weight} edge attribute, then \code{E(G)[weight > 1]} selects all edges with a weight larger than one. +See more examples below. +Note that attribute names mask the names of variables present in the calling environment; +if you need to look up a variable and you do not want a similarly named edge attribute to mask it, +use the \code{.env} pronoun to perform the name lookup in the calling environment. +In other words, +use \code{E(g)[.env$weight > 1]} to make sure that \code{weight} is looked up from the calling environment even +if there is an edge attribute with the same name. +Similarly, you can use \code{.data} to match attribute names only. } \section{Special functions}{ -There are some special igraph functions that can be used -only in expressions indexing edge sequences: +There are some special igraph functions that can be used only in expressions indexing edge sequences: \describe{ \item{\code{.inc}}{ takes a vertex sequence, and selects all edges that have at least one incident vertex in the vertex sequence. @@ -97,9 +89,8 @@ similar to \verb{\\\%--\\\%}, but edges \emph{to} the left hand side argument, pointing \emph{from} the right hand side argument, are selected, in directed graphs. } } -Note that multiple special functions can be used together, or with -regular indices, and then their results are concatenated. See more -examples below. +Note that multiple special functions can be used together, or with regular indices, and then their results are concatenated. +See more examples below. } \examples{ diff --git a/man/igraph-es-indexing2.Rd b/man/igraph-es-indexing2.Rd index 3bede629f78..cb93eb0537f 100644 --- a/man/igraph-es-indexing2.Rd +++ b/man/igraph-es-indexing2.Rd @@ -17,14 +17,11 @@ Another edge sequence, with metadata printing turned on. See details below. } \description{ -The double bracket operator can be used on edge sequences, to print -the meta-data (edge attributes) of the edges in the sequence. +The double bracket operator can be used on edge sequences, to print the meta-data (edge attributes) of the edges in the sequence. } \details{ -Technically, when used with edge sequences, the double bracket -operator does exactly the same as the single bracket operator, -but the resulting edge sequence is printed differently: all -attributes of the edges in the sequence are printed as well. +Technically, when used with edge sequences, the double bracket operator does exactly the same as the single bracket operator, +but the resulting edge sequence is printed differently: all attributes of the edges in the sequence are printed as well. See \code{\link{[.igraph.es}} for more about indexing edge sequences. } diff --git a/man/igraph-minus.Rd b/man/igraph-minus.Rd index 4b27541daf9..130c579f0a8 100644 --- a/man/igraph-minus.Rd +++ b/man/igraph-minus.Rd @@ -19,9 +19,8 @@ An igraph graph. Delete vertices or edges from a graph } \details{ -The minus operator (\sQuote{\code{-}}) can be used to remove vertices -or edges from the graph. The operation performed is selected based on -the type of the right hand side argument: +The minus operator (\sQuote{\code{-}}) can be used to remove vertices or edges from the graph. +The operation performed is selected based on the type of the right hand side argument: \itemize{ \item If it is an igraph graph object, then the difference of the two graphs is calculated, see \code{\link[=difference]{difference()}}. @@ -30,19 +29,13 @@ as a vector of vertex IDs and the specified vertices will be deleted from the graph. Example: \preformatted{ g <- make_ring(10) V(g)$name <- letters[1:10] g <- g - c("a", "b")} -\item If \code{e2} is a vertex sequence (e.g. created by the -\code{\link[=V]{V()}} function), then these vertices will be deleted from -the graph. -\item If it is an edge sequence (e.g. created by the \code{\link[=E]{E()}} -function), then these edges will be deleted from the graph. -\item If it is an object created with the \code{\link[=vertex]{vertex()}} (or the -\code{\link[=vertices]{vertices()}}) function, then all arguments of \code{\link[=vertices]{vertices()}} are -concatenated and the result is interpreted as a vector of vertex -IDs. These vertices will be removed from the graph. -\item If it is an object created with the \code{\link[=edge]{edge()}} (or the -\code{\link[=edges]{edges()}}) function, then all arguments of \code{\link[=edges]{edges()}} are -concatenated and then interpreted as edges to be removed from the -graph. +\item If \code{e2} is a vertex sequence (e.g. created by the \code{\link[=V]{V()}} function), then these vertices will be deleted from the graph. +\item If it is an edge sequence (e.g. created by the \code{\link[=E]{E()}} function), then these edges will be deleted from the graph. +\item If it is an object created with the \code{\link[=vertex]{vertex()}} (or the \code{\link[=vertices]{vertices()}}) function, then all arguments of \code{\link[=vertices]{vertices()}} are concatenated +and the result is interpreted as a vector of vertex IDs. +These vertices will be removed from the graph. +\item If it is an object created with the \code{\link[=edge]{edge()}} (or the \code{\link[=edges]{edges()}}) function, then all arguments of \code{\link[=edges]{edges()}} are concatenated and +then interpreted as edges to be removed from the graph. Example: \preformatted{ g <- make_ring(10) V(g)$name <- letters[1:10] E(g)$name <- LETTERS[1:10] diff --git a/man/igraph-vs-attributes.Rd b/man/igraph-vs-attributes.Rd index b9f7d6e4cf6..554dcfbe0f1 100644 --- a/man/igraph-vs-attributes.Rd +++ b/man/igraph-vs-attributes.Rd @@ -20,33 +20,27 @@ V(x) <- value } \arguments{ -\item{x}{A vertex sequence. For \verb{V<-} it is a graph.} +\item{x}{A vertex sequence. +For \verb{V<-} it is a graph.} \item{i}{Index.} -\item{value}{New value of the attribute, for the vertices in the -vertex sequence.} +\item{value}{New value of the attribute, for the vertices in the vertex sequence.} \item{name}{Name of the vertex attribute to query or set.} } \value{ -A vector or list, containing the values of -attribute \code{name} for the vertices in the vertex sequence. -For numeric, character or logical attributes, it is a vector of the -appropriate type, otherwise it is a list. +A vector or list, containing the values of attribute \code{name} for the vertices in the vertex sequence. +For numeric, character or logical attributes, it is a vector of the appropriate type, otherwise it is a list. } \description{ -The \code{$} operator is a syntactic sugar to query and set the -attributes of the vertices in a vertex sequence. +The \code{$} operator is a syntactic sugar to query and set the attributes of the vertices in a vertex sequence. } \details{ -The query form of \code{$} is a shortcut for -\code{\link[=vertex_attr]{vertex_attr()}}, e.g. \code{V(g)[idx]$attr} is equivalent -to \code{vertex_attr(g, attr, V(g)[idx])}. +The query form of \code{$} is a shortcut for \code{\link[=vertex_attr]{vertex_attr()}}, e.g. \code{V(g)[idx]$attr} is equivalent to \code{vertex_attr(g, attr, V(g)[idx])}. -The assignment form of \code{$} is a shortcut for -\code{\link[=set_vertex_attr]{set_vertex_attr()}}, e.g. \code{V(g)[idx]$attr <- value} is -equivalent to \code{g <- set_vertex_attr(g, attr, V(g)[idx], value)}. +The assignment form of \code{$} is a shortcut for \code{\link[=set_vertex_attr]{set_vertex_attr()}}, +e.g. \code{V(g)[idx]$attr <- value} is equivalent to \code{g <- set_vertex_attr(g, attr, V(g)[idx], value)}. } \examples{ g <- make_( diff --git a/man/igraph-vs-indexing.Rd b/man/igraph-vs-indexing.Rd index c89e0e27d3a..a3c8ba4ba5b 100644 --- a/man/igraph-vs-indexing.Rd +++ b/man/igraph-vs-indexing.Rd @@ -12,8 +12,7 @@ \item{...}{Indices, see details below.} -\item{na_ok}{Whether it is OK to have \code{NA}s in the vertex -sequence.} +\item{na_ok}{Whether it is OK to have \code{NA}s in the vertex sequence.} } \value{ Another vertex sequence, referring to the same graph. @@ -23,18 +22,14 @@ Vertex sequences can be indexed very much like a plain numeric R vector, with some extras. } \details{ -Vertex sequences can be indexed using both the single bracket and -the double bracket operators, and they both work the same way. -The only difference between them is that the double bracket operator -marks the result for printing vertex attributes. +Vertex sequences can be indexed using both the single bracket and the double bracket operators, and they both work the same way. +The only difference between them is that the double bracket operator marks the result for printing vertex attributes. } \section{Multiple indices}{ -When using multiple indices within the bracket, all of them -are evaluated independently, and then the results are concatenated -using the \code{c()} function (except for the \code{na_ok} argument, -which is special an must be named. E.g. \code{V(g)[1, 2, .nei(1)]} -is equivalent to \code{c(V(g)[1], V(g)[2], V(g)[.nei(1)])}. +When using multiple indices within the bracket, all of them are evaluated independently, +and then the results are concatenated using the \code{c()} function (except for the \code{na_ok} argument, which is special an must be named. +E.g. \code{V(g)[1, 2, .nei(1)]} is equivalent to \code{c(V(g)[1], V(g)[2], V(g)[.nei(1)])}. } \section{Index types}{ @@ -42,39 +37,33 @@ is equivalent to \code{c(V(g)[1], V(g)[2], V(g)[.nei(1)])}. Vertex sequences can be indexed with positive numeric vectors, negative numeric vectors, logical vectors, character vectors: \itemize{ -\item When indexed with positive numeric vectors, the vertices at the -given positions in the sequence are selected. This is the same as -indexing a regular R atomic vector with positive numeric vectors. -\item When indexed with negative numeric vectors, the vertices at the -given positions in the sequence are omitted. Again, this is the same -as indexing a regular R atomic vector. -\item When indexed with a logical vector, the lengths of the vertex -sequence and the index must match, and the vertices for which the -index is \code{TRUE} are selected. -\item Named graphs can be indexed with character vectors, -to select vertices with the given names. +\item When indexed with positive numeric vectors, the vertices at the given positions in the sequence are selected. +This is the same as indexing a regular R atomic vector with positive numeric vectors. +\item When indexed with negative numeric vectors, the vertices at the given positions in the sequence are omitted. +Again, this is the same as indexing a regular R atomic vector. +\item When indexed with a logical vector, the lengths of the vertex sequence and the index must match, and the vertices for +which the index is \code{TRUE} are selected. +\item Named graphs can be indexed with character vectors, to select vertices with the given names. } } \section{Vertex attributes}{ -When indexing vertex sequences, vertex attributes can be referred -to simply by using their names. E.g. if a graph has a \code{name} vertex -attribute, then \code{V(g)[name == "foo"]} is equivalent to -\code{V(g)[V(g)$name == "foo"]}. See more examples below. Note that attribute -names mask the names of variables present in the calling environment; if -you need to look up a variable and you do not want a similarly named -vertex attribute to mask it, use the \code{.env} pronoun to perform the -name lookup in the calling environment. In other words, use -\code{V(g)[.env$name == "foo"]} to make sure that \code{name} is looked up -from the calling environment even if there is a vertex attribute with the -same name. Similarly, you can use \code{.data} to match attribute names only. +When indexing vertex sequences, vertex attributes can be referred to simply by using their names. +E.g. if a graph has a \code{name} vertex attribute, then \code{V(g)[name == "foo"]} is equivalent to \code{V(g)[V(g)$name == "foo"]}. +See more examples below. +Note that attribute names mask the names of variables present in the calling environment; +if you need to look up a variable and you do not want a similarly named vertex attribute to mask it, +use the \code{.env} pronoun to perform the name lookup in the calling environment. +In other words, +use \code{V(g)[.env$name == "foo"]} to make sure that \code{name} is looked up from the calling environment even +if there is a vertex attribute with the same name. +Similarly, you can use \code{.data} to match attribute names only. } \section{Special functions}{ -There are some special igraph functions that can be used only -in expressions indexing vertex sequences: +There are some special igraph functions that can be used only in expressions indexing vertex sequences: \describe{ \item{\code{.nei}}{ takes a vertex sequence as its argument @@ -97,9 +86,8 @@ Similar to \code{.inc}, but only considers the heads of the edges. and \code{.outnei(v)} is a shorthand for \code{.nei(v, mode = "out")}. } } -Note that multiple special functions can be used together, or with -regular indices, and then their results are concatenated. See more -examples below. +Note that multiple special functions can be used together, or with regular indices, and then their results are concatenated. +See more examples below. } \examples{ diff --git a/man/igraph-vs-indexing2.Rd b/man/igraph-vs-indexing2.Rd index 37df820b503..9a99377a7e9 100644 --- a/man/igraph-vs-indexing2.Rd +++ b/man/igraph-vs-indexing2.Rd @@ -13,18 +13,15 @@ \item{...}{Additional arguments, passed to \code{[}.} } \value{ -The double bracket operator returns another vertex sequence, -with meta-data (attribute) printing turned on. See details below. +The double bracket operator returns another vertex sequence, with meta-data (attribute) printing turned on. +See details below. } \description{ -The double bracket operator can be used on vertex sequences, to print -the meta-data (vertex attributes) of the vertices in the sequence. +The double bracket operator can be used on vertex sequences, to print the meta-data (vertex attributes) of the vertices in the sequence. } \details{ -Technically, when used with vertex sequences, the double bracket -operator does exactly the same as the single bracket operator, -but the resulting vertex sequence is printed differently: all -attributes of the vertices in the sequence are printed as well. +Technically, when used with vertex sequences, the double bracket operator does exactly the same as the single bracket operator, +but the resulting vertex sequence is printed differently: all attributes of the vertices in the sequence are printed as well. See \code{\link{[.igraph.vs}} for more about indexing vertex sequences. } diff --git a/man/igraph.console.Rd b/man/igraph.console.Rd index 6903d3c1bd7..f6c48e46dc6 100644 --- a/man/igraph.console.Rd +++ b/man/igraph.console.Rd @@ -9,7 +9,6 @@ igraph.console() \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{igraph.console()} was renamed to \code{\link[=console]{console()}} to create a more -consistent API. +\code{igraph.console()} was renamed to \code{\link[=console]{console()}} to create a more consistent API. } \keyword{internal} diff --git a/man/igraph.from.graphNEL.Rd b/man/igraph.from.graphNEL.Rd index e539b1235f4..c4ca4dbb28b 100644 --- a/man/igraph.from.graphNEL.Rd +++ b/man/igraph.from.graphNEL.Rd @@ -9,23 +9,19 @@ igraph.from.graphNEL(graphNEL, name = TRUE, weight = TRUE, unlist.attrs = TRUE) \arguments{ \item{graphNEL}{The graphNEL graph.} -\item{name}{Logical, whether to add graphNEL vertex names as an -igraph vertex attribute called \sQuote{\code{name}}.} +\item{name}{Logical, whether to add graphNEL vertex names as an igraph vertex attribute called \sQuote{\code{name}}.} -\item{weight}{Logical, whether to add graphNEL edge weights as an -igraph edge attribute called \sQuote{\code{weight}}. (graphNEL graphs are -always weighted.)} +\item{weight}{Logical, whether to add graphNEL edge weights as an igraph edge attribute called \sQuote{\code{weight}}. +(graphNEL graphs are always weighted.)} -\item{unlist.attrs}{Logical. graphNEL attribute query functions -return the values of the attributes in R lists, if this argument is -\code{TRUE} (the default) these will be converted to atomic vectors, -whenever possible, before adding them to the igraph graph.} +\item{unlist.attrs}{Logical. graphNEL attribute query functions return the values of the attributes in R lists, +if this argument is \code{TRUE} (the default) these will be converted to atomic vectors, whenever possible, +before adding them to the igraph graph.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{igraph.from.graphNEL()} was renamed to \code{\link[=graph_from_graphnel]{graph_from_graphnel()}} to create a more -consistent API. +\code{igraph.from.graphNEL()} was renamed to \code{\link[=graph_from_graphnel]{graph_from_graphnel()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_edgelist}{\code{get_edgelist()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_adjlist}{\code{adjlist()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/igraph.options.Rd b/man/igraph.options.Rd index 819399bb70e..52a9a701c67 100644 --- a/man/igraph.options.Rd +++ b/man/igraph.options.Rd @@ -7,14 +7,13 @@ igraph.options(...) } \arguments{ -\item{...}{A list may be given as the only argument, or any number of -arguments may be in the \code{name=value} form, or no argument at all may be -given. See the Value and Details sections for explanation.} +\item{...}{A list may be given as the only argument, or any number of arguments may be in the \code{name=value} form, +or no argument at all may be given. +See the Value and Details sections for explanation.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{igraph.options()} was renamed to \code{\link[=igraph_options]{igraph_options()}} to create a more -consistent API. +\code{igraph.options()} was renamed to \code{\link[=igraph_options]{igraph_options()}} to create a more consistent API. } \keyword{internal} diff --git a/man/igraph.sample.Rd b/man/igraph.sample.Rd index 11dbb5cb1c3..01c0b6fc586 100644 --- a/man/igraph.sample.Rd +++ b/man/igraph.sample.Rd @@ -16,8 +16,7 @@ igraph.sample(low, high, length) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{igraph.sample()} was renamed to \code{\link[=sample_seq]{sample_seq()}} to create a more -consistent API. +\code{igraph.sample()} was renamed to \code{\link[=sample_seq]{sample_seq()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Nongraph.html#igraph_random_sample}{\code{random_sample()}} diff --git a/man/igraph.shape.noclip.Rd b/man/igraph.shape.noclip.Rd index f3c32d1c89b..b5d846878e9 100644 --- a/man/igraph.shape.noclip.Rd +++ b/man/igraph.shape.noclip.Rd @@ -9,7 +9,6 @@ igraph.shape.noclip(coords, el, params, end = c("both", "from", "to")) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{igraph.shape.noclip()} was renamed to \code{\link[=shape_noclip]{shape_noclip()}} to create a more -consistent API. +\code{igraph.shape.noclip()} was renamed to \code{\link[=shape_noclip]{shape_noclip()}} to create a more consistent API. } \keyword{internal} diff --git a/man/igraph.shape.noplot.Rd b/man/igraph.shape.noplot.Rd index c97f1fc969f..9d995a4e138 100644 --- a/man/igraph.shape.noplot.Rd +++ b/man/igraph.shape.noplot.Rd @@ -9,7 +9,6 @@ igraph.shape.noplot(coords, v = NULL, params) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{igraph.shape.noplot()} was renamed to \code{\link[=shape_noplot]{shape_noplot()}} to create a more -consistent API. +\code{igraph.shape.noplot()} was renamed to \code{\link[=shape_noplot]{shape_noplot()}} to create a more consistent API. } \keyword{internal} diff --git a/man/igraph.to.graphNEL.Rd b/man/igraph.to.graphNEL.Rd index 6ed6c0a0347..937a7802112 100644 --- a/man/igraph.to.graphNEL.Rd +++ b/man/igraph.to.graphNEL.Rd @@ -12,8 +12,7 @@ igraph.to.graphNEL(graph) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{igraph.to.graphNEL()} was renamed to \code{\link[=as_graphnel]{as_graphnel()}} to create a more -consistent API. +\code{igraph.to.graphNEL()} was renamed to \code{\link[=as_graphnel]{as_graphnel()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_edgelist}{\code{get_edgelist()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_is_directed}{\code{is_directed()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_has_multiple}{\code{has_multiple()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/igraph.version.Rd b/man/igraph.version.Rd index ddd5bcd1b09..4e1f49f6b1f 100644 --- a/man/igraph.version.Rd +++ b/man/igraph.version.Rd @@ -9,8 +9,7 @@ igraph.version() \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{igraph.version()} was renamed to \code{\link[=igraph_version]{igraph_version()}} to create a more -consistent API. +\code{igraph.version()} was renamed to \code{\link[=igraph_version]{igraph_version()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Nongraph.html#igraph_version}{\code{version()}} diff --git a/man/igraph_opt.Rd b/man/igraph_opt.Rd index c2dbecd3368..dabc09c4a9f 100644 --- a/man/igraph_opt.Rd +++ b/man/igraph_opt.Rd @@ -11,17 +11,14 @@ igraph_opt(x, ..., default = NULL) \item{...}{These dots are for future extensions and must be empty.} -\item{default}{If the specified option is not set in the options list, this -value is returned. This facilitates retrieving an option and checking -whether it is set and setting it separately if not.} +\item{default}{If the specified option is not set in the options list, this value is returned. +This facilitates retrieving an option and checking whether it is set and setting it separately if not.} } \value{ -The current value set for option \code{x}, or \code{NULL} if the option is -unset. +The current value set for option \code{x}, or \code{NULL} if the option is unset. } \description{ -Retrieve the current value of one igraph option set via -\code{\link[=igraph_options]{igraph_options()}}. +Retrieve the current value of one igraph option set via \code{\link[=igraph_options]{igraph_options()}}. } \examples{ oldval <- igraph_opt("verbose") @@ -30,7 +27,8 @@ layout_with_kk(make_ring(10)) igraph_options(verbose = oldval) } \seealso{ -Similar to \code{\link[=getOption]{getOption()}}. See \code{\link[=igraph_options]{igraph_options()}} to set options. +Similar to \code{\link[=getOption]{getOption()}}. +See \code{\link[=igraph_options]{igraph_options()}} to set options. Other igraph options: \code{\link[=igraph_options]{igraph_options()}}, diff --git a/man/igraph_options.Rd b/man/igraph_options.Rd index 7cf8b8f7982..68e3b98502c 100644 --- a/man/igraph_options.Rd +++ b/man/igraph_options.Rd @@ -7,27 +7,24 @@ igraph_options(...) } \arguments{ -\item{\dots}{A list may be given as the only argument, or any number of -arguments may be in the \code{name=value} form, or no argument at all may be -given. See the Value and Details sections for explanation.} +\item{\dots}{A list may be given as the only argument, or any number of arguments may be in the \code{name=value} form, +or no argument at all may be given. +See the Value and Details sections for explanation.} } \value{ A list with the old values of the updated parameters, invisibly. Without any arguments, it returns the values of all options. } \description{ -igraph has some parameters which (usually) affect the behavior of many -functions. These can be set for the whole session via \code{igraph_options()}. +igraph has some parameters which (usually) affect the behavior of many functions. +These can be set for the whole session via \code{igraph_options()}. } \details{ -The parameter values set via a call to the \code{igraph_options()} function -will remain in effect for the rest of the session, affecting the subsequent -behaviour of the other functions of the \code{igraph} package for which the -given parameters are relevant. +The parameter values set via a call to the \code{igraph_options()} function will remain in effect for the rest of the session, +affecting the subsequent behaviour of the other functions of the \code{igraph} package for which the given parameters are relevant. -This offers the possibility of customizing the functioning of the -\code{igraph} package, for instance by insertions of appropriate calls to -\code{igraph_options()} in a load hook for package \pkg{igraph}. +This offers the possibility of customizing the functioning of the \code{igraph} package, +for instance by insertions of appropriate calls to \code{igraph_options()} in a load hook for package \pkg{igraph}. The currently used parameters in alphabetical order: \describe{ @@ -58,10 +55,9 @@ The default value is \code{list(weight="sum", name="concat", "ignore")}. See \code{\link[=attribute.combination]{attribute.combination()}} for details on this. } \item{graph.attr.comb}{ -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 -name clash by appending \verb{_1}, \verb{_2}, ... suffixes. +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 name clash by appending \verb{_1}, \verb{_2}, ... suffixes. See \code{\link[=attribute.combination]{attribute.combination()}} for details on this. } \item{print.edge.attributes}{ @@ -79,12 +75,9 @@ Logical constant, whether to print graph attributes when printing graphs. Defaul Logical constant, whether to print vertex attributes when printing graphs. Defaults to \code{FALSE}. } \item{print.style}{ -Character string controlling the visual style used by -\code{\link[=print.igraph]{print.igraph()}}, \code{\link[=summary.igraph]{summary.igraph()}}, \code{\link[=print.igraph.vs]{print.igraph.vs()}} and -\code{\link[=print.igraph.es]{print.igraph.es()}}. Possible values are \code{"cli"} (default, a -cli-styled output with section rules, Unicode arrows for edges and -typed attribute listings) and \code{"classic"} (the historical -\verb{IGRAPH ... DNW-} header relied on by tutorials and parsers). +Character string controlling the visual style used by \code{\link[=print.igraph]{print.igraph()}}, \code{\link[=summary.igraph]{summary.igraph()}}, \code{\link[=print.igraph.vs]{print.igraph.vs()}} +and \code{\link[=print.igraph.es]{print.igraph.es()}}. +Possible values are \code{"cli"} (default, a cli-styled output with section rules, Unicode arrows for edges and typed attribute listings) and \code{"classic"} (the historical \verb{IGRAPH ... DNW-} header relied on by tutorials and parsers). } \item{return.vs.es}{ Whether functions that return a set or sequence of vertices/edges @@ -122,8 +115,8 @@ igraph_opt("verbose") } \seealso{ -Similar to \code{\link[=options]{options()}}. See \code{\link[=igraph_opt]{igraph_opt()}} to retrieve the -value of a single option. +Similar to \code{\link[=options]{options()}}. +See \code{\link[=igraph_opt]{igraph_opt()}} to retrieve the value of a single option. Other igraph options: \code{\link[=igraph_opt]{igraph_opt()}}, diff --git a/man/igraph_version.Rd b/man/igraph_version.Rd index cf8ed8559aa..5d2089dd25d 100644 --- a/man/igraph_version.Rd +++ b/man/igraph_version.Rd @@ -7,8 +7,7 @@ igraph_version() } \value{ -A character scalar, the igraph version string, with an attribute -\code{"c_version"} giving the C library version string. +A character scalar, the igraph version string, with an attribute \code{"c_version"} giving the C library version string. } \description{ Returns the R package version, diff --git a/man/incident.Rd b/man/incident.Rd index c0833e46395..50400d01511 100644 --- a/man/incident.Rd +++ b/man/incident.Rd @@ -13,13 +13,11 @@ incident(graph, v, ..., mode = c("all", "out", "in", "total")) \item{...}{These dots are for future extensions and must be empty.} -\item{mode}{Whether to query outgoing (\sQuote{out}), incoming -(\sQuote{in}) edges, or both types (\sQuote{all}). This is -ignored for undirected graphs.} +\item{mode}{Whether to query outgoing (\sQuote{out}), incoming (\sQuote{in}) edges, or both types (\sQuote{all}). +This is ignored for undirected graphs.} } \value{ -An edge sequence containing the incident edges of -the input vertex. +An edge sequence containing the incident edges of the input vertex. } \description{ Incident edges of a vertex in a graph diff --git a/man/incident_edges.Rd b/man/incident_edges.Rd index 325ae62623c..3c0620a9fcc 100644 --- a/man/incident_edges.Rd +++ b/man/incident_edges.Rd @@ -13,16 +13,14 @@ incident_edges(graph, v, ..., mode = c("out", "in", "all", "total")) \item{...}{These dots are for future extensions and must be empty.} -\item{mode}{Whether to query outgoing (\sQuote{out}), incoming -(\sQuote{in}) edges, or both types (\sQuote{all}). This is -ignored for undirected graphs.} +\item{mode}{Whether to query outgoing (\sQuote{out}), incoming (\sQuote{in}) edges, or both types (\sQuote{all}). +This is ignored for undirected graphs.} } \value{ A list of edge sequences. } \description{ -This function is similar to \code{\link[=incident]{incident()}}, but it -queries multiple vertices at once. +This function is similar to \code{\link[=incident]{incident()}}, but it queries multiple vertices at once. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/indent_print.Rd b/man/indent_print.Rd index abb86623476..28c120812a6 100644 --- a/man/indent_print.Rd +++ b/man/indent_print.Rd @@ -11,8 +11,8 @@ indent_print(..., .indent = " ", .printer = NULL) \item{.indent}{Character scalar, indent the printout with this.} -\item{.printer}{The printing function. The default \code{NULL} uses -\link{print}.} +\item{.printer}{The printing function. +The default \code{NULL} uses \link{print}.} } \value{ The first element in \code{...}, invisibly. diff --git a/man/independence.number.Rd b/man/independence.number.Rd index 2fe69fcef73..a07673dfdc0 100644 --- a/man/independence.number.Rd +++ b/man/independence.number.Rd @@ -12,8 +12,7 @@ independence.number(graph) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{independence.number()} was renamed to \code{\link[=ivs_size]{ivs_size()}} to create a more -consistent API. +\code{independence.number()} was renamed to \code{\link[=ivs_size]{ivs_size()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Cliques.html#igraph_independence_number}{\code{independence_number()}} diff --git a/man/independent.vertex.sets.Rd b/man/independent.vertex.sets.Rd index 742b5d11683..89ee9c70c05 100644 --- a/man/independent.vertex.sets.Rd +++ b/man/independent.vertex.sets.Rd @@ -9,17 +9,16 @@ independent.vertex.sets(graph, min = NULL, max = NULL) \arguments{ \item{graph}{The input graph.} -\item{min}{Numeric constant, limit for the minimum size of the independent -vertex sets to find. \code{NULL} means no limit.} +\item{min}{Numeric constant, limit for the minimum size of the independent vertex sets to find. +\code{NULL} means no limit.} -\item{max}{Numeric constant, limit for the maximum size of the independent -vertex sets to find. \code{NULL} means no limit.} +\item{max}{Numeric constant, limit for the maximum size of the independent vertex sets to find. +\code{NULL} means no limit.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{independent.vertex.sets()} was renamed to \code{\link[=ivs]{ivs()}} to create a more -consistent API. +\code{independent.vertex.sets()} was renamed to \code{\link[=ivs]{ivs()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/induced.subgraph.Rd b/man/induced.subgraph.Rd index 78e14f9f85c..fc94b434c00 100644 --- a/man/induced.subgraph.Rd +++ b/man/induced.subgraph.Rd @@ -13,23 +13,18 @@ induced.subgraph( \arguments{ \item{graph}{The original graph.} -\item{vids}{Numeric vector, the vertices of the original graph which will -form the subgraph.} +\item{vids}{Numeric vector, the vertices of the original graph which will form the subgraph.} -\item{impl}{Character scalar, to choose between two implementation of the -subgraph calculation. \sQuote{\code{copy_and_delete}} copies the graph -first, and then deletes the vertices and edges that are not included in the -result graph. \sQuote{\code{create_from_scratch}} searches for all vertices -and edges that must be kept and then uses them to create the graph from -scratch. \sQuote{\code{auto}} chooses between the two implementations -automatically, using heuristics based on the size of the original and the -result graph.} +\item{impl}{Character scalar, to choose between two implementation of the subgraph calculation. +\sQuote{\code{copy_and_delete}} copies the graph first, and then deletes the vertices and edges that are not included in the result graph. +\sQuote{\code{create_from_scratch}} searches for all vertices and edges that must be kept and then uses them to create the graph from scratch. +\sQuote{\code{auto}} chooses between the two implementations automatically, +using heuristics based on the size of the original and the result graph.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{induced.subgraph()} was renamed to \code{\link[=induced_subgraph]{induced_subgraph()}} to create a more -consistent API. +\code{induced.subgraph()} was renamed to \code{\link[=induced_subgraph]{induced_subgraph()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Operators.html#igraph_induced_subgraph}{\code{induced_subgraph()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/infomap.community.Rd b/man/infomap.community.Rd index a8da00bd7a5..83335eb70cc 100644 --- a/man/infomap.community.Rd +++ b/man/infomap.community.Rd @@ -13,32 +13,29 @@ infomap.community( ) } \arguments{ -\item{graph}{The input graph. Edge directions will be taken into account.} +\item{graph}{The input graph. +Edge directions will be taken into account.} \item{e.weights}{Numeric vector of edge weights. -The length must match the number of edges in the graph. By default (\code{NULL}) the -\sQuote{\code{weight}} edge attribute is used as weights. If it is not -present, then all edges are considered to have the same weight. +The length must match the number of edges in the graph. +By default (\code{NULL}) the \sQuote{\code{weight}} edge attribute is used as weights. +If it is not present, then all edges are considered to have the same weight. Larger edge weights correspond to stronger connections.} -\item{v.weights}{Numeric vector of vertex -weights. The length must match the number of vertices in the graph. By -default (\code{NULL}) the \sQuote{\code{weight}} vertex attribute is used as weights. If -it is not present, then all vertices are considered to have the same weight. -A larger vertex weight means a larger probability that the random surfer -jumps to that vertex.} +\item{v.weights}{Numeric vector of vertex weights. +The length must match the number of vertices in the graph. +By default (\code{NULL}) the \sQuote{\code{weight}} vertex attribute is used as weights. +If it is not present, then all vertices are considered to have the same weight. +A larger vertex weight means a larger probability that the random surfer jumps to that vertex.} -\item{nb.trials}{The number of attempts to partition the network (can be any -integer value equal or larger than 1).} +\item{nb.trials}{The number of attempts to partition the network (can be any integer value equal or larger than 1).} -\item{modularity}{Logical, whether to calculate the modularity score -of the detected community structure.} +\item{modularity}{Logical, whether to calculate the modularity score of the detected community structure.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{infomap.community()} was renamed to \code{\link[=cluster_infomap]{cluster_infomap()}} to create a more -consistent API. +\code{infomap.community()} was renamed to \code{\link[=cluster_infomap]{cluster_infomap()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Community.html#igraph_community_infomap}{\code{community_infomap()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/interconnected.islands.game.Rd b/man/interconnected.islands.game.Rd index 77498be227a..ea6d00c1156 100644 --- a/man/interconnected.islands.game.Rd +++ b/man/interconnected.islands.game.Rd @@ -11,16 +11,14 @@ interconnected.islands.game(islands.n, islands.size, islands.pin, n.inter) \item{islands.size}{The size of islands in the graph.} -\item{islands.pin}{The probability to create each possible edge into each -island.} +\item{islands.pin}{The probability to create each possible edge into each island.} \item{n.inter}{The number of edges to create between two islands.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{interconnected.islands.game()} was renamed to \code{\link[=sample_islands]{sample_islands()}} to create a more -consistent API. +\code{interconnected.islands.game()} was renamed to \code{\link[=sample_islands]{sample_islands()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_simple_interconnected_islands_game}{\code{simple_interconnected_islands_game()}} diff --git a/man/intersection.Rd b/man/intersection.Rd index e2f7689ff97..6f6d3895762 100644 --- a/man/intersection.Rd +++ b/man/intersection.Rd @@ -7,19 +7,16 @@ intersection(...) } \arguments{ -\item{...}{Arguments, their number and interpretation depends on -the function that implements \code{intersection()}.} +\item{...}{Arguments, their number and interpretation depends on the function that implements \code{intersection()}.} } \value{ Depends on the function that implements this method. } \description{ -This is an S3 generic function. See \code{methods("intersection")} -for the actual implementations for various S3 classes. Initially -it is implemented for igraph graphs and igraph vertex and edge -sequences. See -\code{\link[=intersection.igraph]{intersection.igraph()}}, and -\code{\link[=intersection.igraph.vs]{intersection.igraph.vs()}}. +This is an S3 generic function. +See \code{methods("intersection")} for the actual implementations for various S3 classes. +Initially it is implemented for igraph graphs and igraph vertex and edge sequences. +See \code{\link[=intersection.igraph]{intersection.igraph()}}, and \code{\link[=intersection.igraph.vs]{intersection.igraph.vs()}}. } \seealso{ Other functions for manipulating graph structure: diff --git a/man/intersection.igraph.Rd b/man/intersection.igraph.Rd index 6a07aae79f7..2a4de25d3e7 100644 --- a/man/intersection.igraph.Rd +++ b/man/intersection.igraph.Rd @@ -17,52 +17,42 @@ \arguments{ \item{\dots}{Graph objects or lists of graph objects.} -\item{byname}{A Logical, or the character scalar \code{auto}. Whether -to perform the operation based on symbolic vertex names. If it is -\code{auto}, that means \code{TRUE} if all graphs are named and \code{FALSE} -otherwise. A warning is generated if \code{auto} and some (but not all) -graphs are named.} +\item{byname}{A Logical, or the character scalar \code{auto}. +Whether to perform the operation based on symbolic vertex names. +If it is \code{auto}, that means \code{TRUE} if all graphs are named and \code{FALSE} otherwise. +A warning is generated if \code{auto} and some (but not all) graphs are named.} -\item{keep.all.vertices}{Logical, whether to keep vertices that only -appear in a subset of the input graphs.} +\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 -\code{\link[=igraph_options]{igraph_options()}}). See \link{igraph-attribute-combination} for the available -combiners.} +\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 \code{\link[=igraph_options]{igraph_options()}}). +See \link{igraph-attribute-combination} for the available combiners.} } \value{ A new graph object. } \description{ -The intersection of two or more graphs are created. The graphs may have -identical or overlapping vertex sets. +The intersection of two or more graphs are created. +The graphs may have identical or overlapping vertex sets. } \details{ -\code{intersection()} creates the intersection of two or more graphs: -only edges present in all graphs will be included. The corresponding -operator is \verb{\%s\%}. +\code{intersection()} creates the intersection of two or more graphs: only edges present in all graphs will be included. +The corresponding operator is \verb{\%s\%}. -If the \code{byname} argument is \code{TRUE} (or \code{auto} and all graphs -are named), then the operation is performed on symbolic vertex names instead -of the internal numeric vertex IDs. +If the \code{byname} argument is \code{TRUE} (or \code{auto} and all graphs are named), +then the operation is performed on symbolic vertex names instead of the internal numeric vertex IDs. -\code{intersection()} 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 instead; see \link{igraph-attribute-combination} for the -available combiners. +\code{intersection()} 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 instead; +see \link{igraph-attribute-combination} for the available combiners. -The \code{name} vertex attribute is treated specially if the operation is -performed based on symbolic vertex names. In this case \code{name} must be -present in all graphs, and it is not renamed in the result graph. +The \code{name} vertex attribute is treated specially if the operation is performed based on symbolic vertex names. +In this case \code{name} must be present in all graphs, and it is not renamed in the result graph. -An error is generated if some input graphs are directed and others are -undirected. +An error is generated if some input graphs are directed and others are undirected. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Isomorphism.html#igraph_permute_vertices}{\code{permute_vertices()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/intersection.igraph.es.Rd b/man/intersection.igraph.es.Rd index ae99af00040..a6a5dacebc5 100644 --- a/man/intersection.igraph.es.Rd +++ b/man/intersection.igraph.es.Rd @@ -10,16 +10,14 @@ \item{...}{The edge sequences to take the intersection of.} } \value{ -An edge sequence that contains edges that appear in all -given sequences, each edge exactly once. +An edge sequence that contains edges that appear in all given sequences, each edge exactly once. } \description{ Intersection of edge sequences } \details{ -They must belong to the same graph. Note that this function has -\sQuote{set} semantics and the multiplicity of edges is lost in the -result. +They must belong to the same graph. +Note that this function has \sQuote{set} semantics and the multiplicity of edges is lost in the result. } \examples{ g <- make_(ring(10), with_vertex_(name = LETTERS[1:10])) diff --git a/man/intersection.igraph.vs.Rd b/man/intersection.igraph.vs.Rd index ead0c4974ae..7fde62b682a 100644 --- a/man/intersection.igraph.vs.Rd +++ b/man/intersection.igraph.vs.Rd @@ -10,16 +10,14 @@ \item{...}{The vertex sequences to take the intersection of.} } \value{ -A vertex sequence that contains vertices that appear in all -given sequences, each vertex exactly once. +A vertex sequence that contains vertices that appear in all given sequences, each vertex exactly once. } \description{ Intersection of vertex sequences } \details{ -They must belong to the same graph. Note that this function has -\sQuote{set} semantics and the multiplicity of vertices is lost in the -result. +They must belong to the same graph. +Note that this function has \sQuote{set} semantics and the multiplicity of vertices is lost in the result. } \examples{ g <- make_(ring(10), with_vertex_(name = LETTERS[1:10])) diff --git a/man/invalidate_cache.Rd b/man/invalidate_cache.Rd index 23a368a6bd4..be5a2abd4af 100644 --- a/man/invalidate_cache.Rd +++ b/man/invalidate_cache.Rd @@ -10,21 +10,17 @@ invalidate_cache(graph) \item{graph}{The graph whose cache is to be invalidated.} } \value{ -The graph with its cache invalidated. Since the graph is modified -in place in R as well, you can also ignore the return value. +The graph with its cache invalidated. +Since the graph is modified in place in R as well, you can also ignore the return value. } \description{ -igraph graphs cache some basic properties (such as whether the graph is a -DAG or whether it is simple) in an internal data structure for faster -repeated queries. This function invalidates the cache, forcing a -recalculation of the cached properties the next time they are needed. +igraph graphs cache some basic properties (such as whether the graph is a DAG or whether it is simple) in an internal data structure for faster repeated queries. +This function invalidates the cache, forcing a recalculation of the cached properties the next time they are needed. } \details{ -You should not need to call this function during normal usage; however, it -may be useful for debugging cache-related issues. A tell-tale sign of an -invalid cache entry is when the result of a cached function (such as -\code{\link{is_dag}()} or \code{\link{is_simple}()}) changes after calling -this function. +You should not need to call this function during normal usage; however, it may be useful for debugging cache-related issues. +A tell-tale sign of an invalid cache entry is +when the result of a cached function (such as \code{\link{is_dag}()} or \code{\link{is_simple}()}) changes after calling this function. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_invalidate_cache}{\code{invalidate_cache()}} diff --git a/man/is.bipartite.Rd b/man/is.bipartite.Rd index 0c94eb26696..c82c1c73df1 100644 --- a/man/is.bipartite.Rd +++ b/man/is.bipartite.Rd @@ -12,8 +12,7 @@ is.bipartite(graph) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{is.bipartite()} was renamed to \code{\link[=is_bipartite]{is_bipartite()}} to create a more -consistent API. +\code{is.bipartite()} was renamed to \code{\link[=is_bipartite]{is_bipartite()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/is.chordal.Rd b/man/is.chordal.Rd index 5217977bbb9..cc5618a4bdd 100644 --- a/man/is.chordal.Rd +++ b/man/is.chordal.Rd @@ -13,17 +13,14 @@ is.chordal( ) } \arguments{ -\item{graph}{The input graph. It may be directed, but edge directions are -ignored, as the algorithm is defined for undirected graphs.} +\item{graph}{The input graph. +It may be directed, but edge directions are ignored, as the algorithm is defined for undirected graphs.} -\item{alpha}{Numeric vector, the maximal chardinality ordering of the -vertices. If it is \code{NULL}, then it is automatically calculated by -calling \code{\link[=max_cardinality]{max_cardinality()}}, or from \code{alpham1} if -that is given..} +\item{alpha}{Numeric vector, the maximal chardinality ordering of the vertices. +If it is \code{NULL}, then it is automatically calculated by calling \code{\link[=max_cardinality]{max_cardinality()}}, or from \code{alpham1} if that is given..} -\item{alpham1}{Numeric vector, the inverse of \code{alpha}. If it is -\code{NULL}, then it is automatically calculated by calling -\code{\link[=max_cardinality]{max_cardinality()}}, or from \code{alpha}.} +\item{alpham1}{Numeric vector, the inverse of \code{alpha}. +If it is \code{NULL}, then it is automatically calculated by calling \code{\link[=max_cardinality]{max_cardinality()}}, or from \code{alpha}.} \item{fillin}{Logical, whether to calculate the fill-in edges.} @@ -32,7 +29,6 @@ that is given..} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{is.chordal()} was renamed to \code{\link[=is_chordal]{is_chordal()}} to create a more -consistent API. +\code{is.chordal()} was renamed to \code{\link[=is_chordal]{is_chordal()}} to create a more consistent API. } \keyword{internal} diff --git a/man/is.connected.Rd b/man/is.connected.Rd index 3450acb5dbb..46f1754b691 100644 --- a/man/is.connected.Rd +++ b/man/is.connected.Rd @@ -9,15 +9,15 @@ is.connected(graph, mode = c("weak", "strong")) \arguments{ \item{graph}{The graph to analyze.} -\item{mode}{Character string, either \dQuote{weak} or \dQuote{strong}. For -directed graphs \dQuote{weak} implies weakly, \dQuote{strong} strongly -connected components to search. It is ignored for undirected graphs.} +\item{mode}{Character string, either \dQuote{weak} or \dQuote{strong}. +For directed graphs \dQuote{weak} implies weakly, +\dQuote{strong} strongly connected components to search. +It is ignored for undirected graphs.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{is.connected()} was renamed to \code{\link[=is_connected]{is_connected()}} to create a more -consistent API. +\code{is.connected()} was renamed to \code{\link[=is_connected]{is_connected()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_connected}{\code{is_connected()}} diff --git a/man/is.dag.Rd b/man/is.dag.Rd index 9d93f1bf013..d30b1161fe6 100644 --- a/man/is.dag.Rd +++ b/man/is.dag.Rd @@ -7,14 +7,13 @@ is.dag(graph) } \arguments{ -\item{graph}{The input graph. It may be undirected, in which case -\code{FALSE} is reported.} +\item{graph}{The input graph. +It may be undirected, in which case \code{FALSE} is reported.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{is.dag()} was renamed to \code{\link[=is_dag]{is_dag()}} to create a more -consistent API. +\code{is.dag()} was renamed to \code{\link[=is_dag]{is_dag()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_dag}{\code{is_dag()}} diff --git a/man/is.degree.sequence.Rd b/man/is.degree.sequence.Rd index 2d240fcdc0e..d2a543fa0ec 100644 --- a/man/is.degree.sequence.Rd +++ b/man/is.degree.sequence.Rd @@ -7,17 +7,16 @@ is.degree.sequence(out.deg, in.deg = NULL) } \arguments{ -\item{out.deg}{Integer vector, the degree sequence for undirected graphs, or -the out-degree sequence for directed graphs.} +\item{out.deg}{Integer vector, the degree sequence for undirected graphs, or the out-degree sequence for directed graphs.} -\item{in.deg}{\code{NULL} or an integer vector. For undirected graphs, it -should be \code{NULL}. For directed graphs it specifies the in-degrees.} +\item{in.deg}{\code{NULL} or an integer vector. +For undirected graphs, it should be \code{NULL}. +For directed graphs it specifies the in-degrees.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{is.degree.sequence()} was renamed to \code{\link[=is_degseq]{is_degseq()}} to create a more -consistent API. +\code{is.degree.sequence()} was renamed to \code{\link[=is_degseq]{is_degseq()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_graphical}{\code{is_graphical()}} diff --git a/man/is.directed.Rd b/man/is.directed.Rd index f33093a86e3..1d4ba4d2ce7 100644 --- a/man/is.directed.Rd +++ b/man/is.directed.Rd @@ -12,8 +12,7 @@ is.directed(graph) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{is.directed()} was renamed to \code{\link[=is_directed]{is_directed()}} to create a more -consistent API. +\code{is.directed()} was renamed to \code{\link[=is_directed]{is_directed()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_is_directed}{\code{is_directed()}} diff --git a/man/is.graphical.degree.sequence.Rd b/man/is.graphical.degree.sequence.Rd index 99f3a6dc875..89f13670cb1 100644 --- a/man/is.graphical.degree.sequence.Rd +++ b/man/is.graphical.degree.sequence.Rd @@ -11,24 +11,22 @@ is.graphical.degree.sequence( ) } \arguments{ -\item{out.deg}{Integer vector, the degree sequence for undirected graphs, or -the out-degree sequence for directed graphs.} +\item{out.deg}{Integer vector, the degree sequence for undirected graphs, or the out-degree sequence for directed graphs.} -\item{in.deg}{\code{NULL} or an integer vector. For undirected graphs, it -should be \code{NULL}. For directed graphs it specifies the in-degrees.} +\item{in.deg}{\code{NULL} or an integer vector. +For undirected graphs, it should be \code{NULL}. +For directed graphs it specifies the in-degrees.} -\item{allowed.edge.types}{The allowed edge types in the graph. \sQuote{simple} -means that neither loop nor multiple edges are allowed (i.e. the graph must be -simple). \sQuote{loops} means that loop edges are allowed but mutiple edges -are not. \sQuote{multi} means that multiple edges are allowed but loop edges -are not. \sQuote{all} means that both loop edges and multiple edges are -allowed.} +\item{allowed.edge.types}{The allowed edge types in the graph. +\sQuote{simple} means that neither loop nor multiple edges are allowed (i.e. the graph must be simple). +\sQuote{loops} means that loop edges are allowed but mutiple edges are not. +\sQuote{multi} means that multiple edges are allowed but loop edges are not. +\sQuote{all} means that both loop edges and multiple edges are allowed.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{is.graphical.degree.sequence()} was renamed to \code{\link[=is_graphical]{is_graphical()}} to create a more -consistent API. +\code{is.graphical.degree.sequence()} was renamed to \code{\link[=is_graphical]{is_graphical()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_graphical}{\code{is_graphical()}} diff --git a/man/is.hierarchical.Rd b/man/is.hierarchical.Rd index 0df3d516d37..5adc676bcf0 100644 --- a/man/is.hierarchical.Rd +++ b/man/is.hierarchical.Rd @@ -9,7 +9,6 @@ is.hierarchical(communities) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{is.hierarchical()} was renamed to \code{\link[=is_hierarchical]{is_hierarchical()}} to create a more -consistent API. +\code{is.hierarchical()} was renamed to \code{\link[=is_hierarchical]{is_hierarchical()}} to create a more consistent API. } \keyword{internal} diff --git a/man/is.igraph.Rd b/man/is.igraph.Rd index 7baebadadb9..47b21428393 100644 --- a/man/is.igraph.Rd +++ b/man/is.igraph.Rd @@ -12,7 +12,6 @@ is.igraph(graph) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{is.igraph()} was renamed to \code{\link[=is_igraph]{is_igraph()}} to create a more -consistent API. +\code{is.igraph()} was renamed to \code{\link[=is_igraph]{is_igraph()}} to create a more consistent API. } \keyword{internal} diff --git a/man/is.loop.Rd b/man/is.loop.Rd index ce99c889463..51396c91b34 100644 --- a/man/is.loop.Rd +++ b/man/is.loop.Rd @@ -9,14 +9,13 @@ is.loop(graph, eids = E(graph)) \arguments{ \item{graph}{The input graph.} -\item{eids}{The edges to which the query is restricted. The default -\code{NULL} selects all edges.} +\item{eids}{The edges to which the query is restricted. +The default \code{NULL} selects all edges.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{is.loop()} was renamed to \code{\link[=which_loop]{which_loop()}} to create a more -consistent API. +\code{is.loop()} was renamed to \code{\link[=which_loop]{which_loop()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_loop}{\code{is_loop()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/is.matching.Rd b/man/is.matching.Rd index 56ac7bbb9f8..0eddf3e52cf 100644 --- a/man/is.matching.Rd +++ b/man/is.matching.Rd @@ -7,21 +7,20 @@ is.matching(graph, matching, types = NULL) } \arguments{ -\item{graph}{The input graph. It might be directed, but edge directions will -be ignored.} +\item{graph}{The input graph. +It might be directed, but edge directions will be ignored.} -\item{matching}{A potential matching. An integer vector that gives the -pair in the matching for each vertex. For vertices without a pair, -supply \code{NA} here.} +\item{matching}{A potential matching. +An integer vector that gives the pair in the matching for each vertex. +For vertices without a pair, supply \code{NA} here.} -\item{types}{Vertex types, if the graph is bipartite. By default they -are taken from the \sQuote{\code{type}} vertex attribute, if present.} +\item{types}{Vertex types, if the graph is bipartite. +By default they are taken from the \sQuote{\code{type}} vertex attribute, if present.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{is.matching()} was renamed to \code{\link[=is_matching]{is_matching()}} to create a more -consistent API. +\code{is.matching()} was renamed to \code{\link[=is_matching]{is_matching()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_matching}{\code{is_matching()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/is.maximal.matching.Rd b/man/is.maximal.matching.Rd index f798591241c..14c5b54e2e4 100644 --- a/man/is.maximal.matching.Rd +++ b/man/is.maximal.matching.Rd @@ -7,21 +7,20 @@ is.maximal.matching(graph, matching, types = NULL) } \arguments{ -\item{graph}{The input graph. It might be directed, but edge directions will -be ignored.} +\item{graph}{The input graph. +It might be directed, but edge directions will be ignored.} -\item{matching}{A potential matching. An integer vector that gives the -pair in the matching for each vertex. For vertices without a pair, -supply \code{NA} here.} +\item{matching}{A potential matching. +An integer vector that gives the pair in the matching for each vertex. +For vertices without a pair, supply \code{NA} here.} -\item{types}{Vertex types, if the graph is bipartite. By default they -are taken from the \sQuote{\code{type}} vertex attribute, if present.} +\item{types}{Vertex types, if the graph is bipartite. +By default they are taken from the \sQuote{\code{type}} vertex attribute, if present.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{is.maximal.matching()} was renamed to \code{\link[=is_max_matching]{is_max_matching()}} to create a more -consistent API. +\code{is.maximal.matching()} was renamed to \code{\link[=is_max_matching]{is_max_matching()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_maximal_matching}{\code{is_maximal_matching()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/is.minimal.separator.Rd b/man/is.minimal.separator.Rd index 9702c118328..be2701ab971 100644 --- a/man/is.minimal.separator.Rd +++ b/man/is.minimal.separator.Rd @@ -7,17 +7,15 @@ is.minimal.separator(graph, candidate) } \arguments{ -\item{graph}{The input graph. It may be directed, but edge directions are -ignored.} +\item{graph}{The input graph. +It may be directed, but edge directions are ignored.} -\item{candidate}{A numeric vector giving the vertex IDs of the candidate -separator.} +\item{candidate}{A numeric vector giving the vertex IDs of the candidate separator.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{is.minimal.separator()} was renamed to \code{\link[=is_min_separator]{is_min_separator()}} to create a more -consistent API. +\code{is.minimal.separator()} was renamed to \code{\link[=is_min_separator]{is_min_separator()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Separators.html#igraph_is_minimal_separator}{\code{is_minimal_separator()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/is.multiple.Rd b/man/is.multiple.Rd index 8ea9bd2d762..c1198d14cf9 100644 --- a/man/is.multiple.Rd +++ b/man/is.multiple.Rd @@ -9,14 +9,13 @@ is.multiple(graph, eids = E(graph)) \arguments{ \item{graph}{The input graph.} -\item{eids}{The edges to which the query is restricted. The default -\code{NULL} selects all edges.} +\item{eids}{The edges to which the query is restricted. +The default \code{NULL} selects all edges.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{is.multiple()} was renamed to \code{\link[=which_multiple]{which_multiple()}} to create a more -consistent API. +\code{is.multiple()} was renamed to \code{\link[=which_multiple]{which_multiple()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_multiple}{\code{is_multiple()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/is.mutual.Rd b/man/is.mutual.Rd index 321108ac67d..a93fd9a9a7b 100644 --- a/man/is.mutual.Rd +++ b/man/is.mutual.Rd @@ -9,16 +9,15 @@ is.mutual(graph, eids = E(graph), loops = TRUE) \arguments{ \item{graph}{The input graph.} -\item{eids}{Edge sequence, the edges that will be probed. The default -\code{NULL} includes all edges in the order of their IDs.} +\item{eids}{Edge sequence, the edges that will be probed. +The default \code{NULL} includes all edges in the order of their IDs.} \item{loops}{Logical, whether to consider directed self-loops to be mutual.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{is.mutual()} was renamed to \code{\link[=which_mutual]{which_mutual()}} to create a more -consistent API. +\code{is.mutual()} was renamed to \code{\link[=which_mutual]{which_mutual()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_mutual}{\code{is_mutual()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/is.named.Rd b/man/is.named.Rd index f55f452ab7f..32cedc70d4e 100644 --- a/man/is.named.Rd +++ b/man/is.named.Rd @@ -12,7 +12,6 @@ is.named(graph) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{is.named()} was renamed to \code{\link[=is_named]{is_named()}} to create a more -consistent API. +\code{is.named()} was renamed to \code{\link[=is_named]{is_named()}} to create a more consistent API. } \keyword{internal} diff --git a/man/is.separator.Rd b/man/is.separator.Rd index 4fcae7adfd9..6e6c884df9e 100644 --- a/man/is.separator.Rd +++ b/man/is.separator.Rd @@ -7,17 +7,15 @@ is.separator(graph, candidate) } \arguments{ -\item{graph}{The input graph. It may be directed, but edge directions are -ignored.} +\item{graph}{The input graph. +It may be directed, but edge directions are ignored.} -\item{candidate}{A numeric vector giving the vertex IDs of the candidate -separator.} +\item{candidate}{A numeric vector giving the vertex IDs of the candidate separator.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{is.separator()} was renamed to \code{\link[=is_separator]{is_separator()}} to create a more -consistent API. +\code{is.separator()} was renamed to \code{\link[=is_separator]{is_separator()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Separators.html#igraph_is_separator}{\code{is_separator()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/is.simple.Rd b/man/is.simple.Rd index 5bd42e09c41..c060915eb05 100644 --- a/man/is.simple.Rd +++ b/man/is.simple.Rd @@ -12,8 +12,7 @@ is.simple(graph) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{is.simple()} was renamed to \code{\link[=is_simple]{is_simple()}} to create a more -consistent API. +\code{is.simple()} was renamed to \code{\link[=is_simple]{is_simple()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_simple}{\code{is_simple()}} diff --git a/man/is.weighted.Rd b/man/is.weighted.Rd index d1263895bc6..873b85156f2 100644 --- a/man/is.weighted.Rd +++ b/man/is.weighted.Rd @@ -12,7 +12,6 @@ is.weighted(graph) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{is.weighted()} was renamed to \code{\link[=is_weighted]{is_weighted()}} to create a more -consistent API. +\code{is.weighted()} was renamed to \code{\link[=is_weighted]{is_weighted()}} to create a more consistent API. } \keyword{internal} diff --git a/man/is_acyclic.Rd b/man/is_acyclic.Rd index daa3ec97514..494e6695a80 100644 --- a/man/is_acyclic.Rd +++ b/man/is_acyclic.Rd @@ -16,8 +16,8 @@ A logical vector of length one. This function tests whether the given graph is free of cycles. } \details{ -This function looks for directed cycles in directed graphs and undirected -cycles in undirected graphs. Use \code{\link[=find_cycle]{find_cycle()}} to return a specific cycle. +This function looks for directed cycles in directed graphs and undirected cycles in undirected graphs. +Use \code{\link[=find_cycle]{find_cycle()}} to return a specific cycle. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Cycles.html#igraph_is_acyclic}{\code{is_acyclic()}} @@ -30,8 +30,7 @@ is_acyclic(g) is_acyclic(as_undirected(g)) } \seealso{ -\code{\link[=is_forest]{is_forest()}} and \code{\link[=is_dag]{is_dag()}} for functions specific to undirected -and directed graphs. +\code{\link[=is_forest]{is_forest()}} and \code{\link[=is_dag]{is_dag()}} for functions specific to undirected and directed graphs. Graph cycles: \code{\link[=feedback_arc_set]{feedback_arc_set()}}, diff --git a/man/is_biconnected.Rd b/man/is_biconnected.Rd index fd5ecc33d8f..de34160ed38 100644 --- a/man/is_biconnected.Rd +++ b/man/is_biconnected.Rd @@ -7,7 +7,8 @@ is_biconnected(graph) } \arguments{ -\item{graph}{The input graph. Edge directions are ignored.} +\item{graph}{The input graph. +Edge directions are ignored.} } \value{ Logical, \code{TRUE} if the graph is biconnected. @@ -18,13 +19,11 @@ Logical, \code{TRUE} if the graph is biconnected. Tests whether a graph is biconnected. } \details{ -A graph is biconnected if the removal of any single vertex (and its adjacent -edges) does not disconnect it. +A graph is biconnected if the removal of any single vertex (and its adjacent edges) does not disconnect it. igraph does not consider single-vertex graphs biconnected. -Note that some authors do not consider the graph consisting of -two connected vertices as biconnected, however, igraph does. +Note that some authors do not consider the graph consisting of two connected vertices as biconnected, however, igraph does. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_biconnected}{\code{is_biconnected()}} diff --git a/man/is_bipartite.Rd b/man/is_bipartite.Rd index b9aeb4bc622..3da675212be 100644 --- a/man/is_bipartite.Rd +++ b/man/is_bipartite.Rd @@ -10,8 +10,8 @@ is_bipartite(graph) \item{graph}{The input graph} } \description{ -It does not check whether the graph is bipartite in the -mathematical sense. Use \code{\link[=bipartite_mapping]{bipartite_mapping()}} for that. +It does not check whether the graph is bipartite in the mathematical sense. +Use \code{\link[=bipartite_mapping]{bipartite_mapping()}} for that. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/is_chordal.Rd b/man/is_chordal.Rd index 8b2f878306b..c2bf3ecb854 100644 --- a/man/is_chordal.Rd +++ b/man/is_chordal.Rd @@ -14,19 +14,16 @@ is_chordal( ) } \arguments{ -\item{graph}{The input graph. It may be directed, but edge directions are -ignored, as the algorithm is defined for undirected graphs.} +\item{graph}{The input graph. +It may be directed, but edge directions are ignored, as the algorithm is defined for undirected graphs.} \item{...}{These dots are for future extensions and must be empty.} -\item{alpha}{Numeric vector, the maximal chardinality ordering of the -vertices. If it is \code{NULL}, then it is automatically calculated by -calling \code{\link[=max_cardinality]{max_cardinality()}}, or from \code{alpham1} if -that is given..} +\item{alpha}{Numeric vector, the maximal chardinality ordering of the vertices. +If it is \code{NULL}, then it is automatically calculated by calling \code{\link[=max_cardinality]{max_cardinality()}}, or from \code{alpham1} if that is given..} -\item{alpham1}{Numeric vector, the inverse of \code{alpha}. If it is -\code{NULL}, then it is automatically calculated by calling -\code{\link[=max_cardinality]{max_cardinality()}}, or from \code{alpha}.} +\item{alpham1}{Numeric vector, the inverse of \code{alpha}. +If it is \code{NULL}, then it is automatically calculated by calling \code{\link[=max_cardinality]{max_cardinality()}}, or from \code{alpha}.} \item{fillin}{Logical, whether to calculate the fill-in edges.} @@ -47,15 +44,13 @@ If requested, then the triangulated graph, an \code{igraph} object. \code{NULL} } } \description{ -A graph is chordal (or triangulated) if each of its cycles of four or more -nodes has a chord, which is an edge joining two nodes that are not adjacent -in the cycle. An equivalent definition is that any chordless cycles have at -most three nodes. +A graph is chordal (or triangulated) if each of its cycles of four or more nodes has a chord, +which is an edge joining two nodes that are not adjacent in the cycle. +An equivalent definition is that any chordless cycles have at most three nodes. } \details{ -The chordality of the graph is decided by first performing maximum -cardinality search on it (if the \code{alpha} and \code{alpham1} arguments -are \code{NULL}), and then calculating the set of fill-in edges. +The chordality of the graph is decided by first performing maximum cardinality search on it (if the \code{alpha} and \code{alpham1} arguments are \code{NULL}), +and then calculating the set of fill-in edges. The set of fill-in edges is empty if and only if the graph is chordal. diff --git a/man/is_complete.Rd b/man/is_complete.Rd index 332352c44b7..73bd962d904 100644 --- a/man/is_complete.Rd +++ b/man/is_complete.Rd @@ -13,9 +13,8 @@ is_complete(graph) True if the graph is complete. } \description{ -A graph is considered complete if there is an edge between all distinct -directed pairs of vertices. igraph considers both the singleton graph -and the null graph complete. +A graph is considered complete +if there is an edge between all distinct directed pairs of vertices. igraph considers both the singleton graph and the null graph complete. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Cliques.html#igraph_is_complete}{\code{is_complete()}} diff --git a/man/is_dag.Rd b/man/is_dag.Rd index b88ce05cb14..c113d7db772 100644 --- a/man/is_dag.Rd +++ b/man/is_dag.Rd @@ -7,19 +7,18 @@ is_dag(graph) } \arguments{ -\item{graph}{The input graph. It may be undirected, in which case -\code{FALSE} is reported.} +\item{graph}{The input graph. +It may be undirected, in which case \code{FALSE} is reported.} } \value{ A logical vector of length one. } \description{ -This function tests whether the given graph is a DAG, a directed acyclic -graph. +This function tests whether the given graph is a DAG, a directed acyclic graph. } \details{ -\code{is_dag()} checks whether there is a directed cycle in the graph. If not, -the graph is a DAG. +\code{is_dag()} checks whether there is a directed cycle in the graph. +If not, the graph is a DAG. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_dag}{\code{is_dag()}} diff --git a/man/is_degseq.Rd b/man/is_degseq.Rd index acad480b09d..3636780e21c 100644 --- a/man/is_degseq.Rd +++ b/man/is_degseq.Rd @@ -7,23 +7,21 @@ is_degseq(out.deg, in.deg = NULL) } \arguments{ -\item{out.deg}{Integer vector, the degree sequence for undirected graphs, or -the out-degree sequence for directed graphs.} +\item{out.deg}{Integer vector, the degree sequence for undirected graphs, or the out-degree sequence for directed graphs.} -\item{in.deg}{\code{NULL} or an integer vector. For undirected graphs, it -should be \code{NULL}. For directed graphs it specifies the in-degrees.} +\item{in.deg}{\code{NULL} or an integer vector. +For undirected graphs, it should be \code{NULL}. +For directed graphs it specifies the in-degrees.} } \value{ A logical scalar. } \description{ -\code{is_degseq()} checks whether the given vertex degrees (in- and -out-degrees for directed graphs) can be realized by a graph. Note that the -graph does not have to be simple, it may contain loop and multiple edges. +\code{is_degseq()} checks whether the given vertex degrees (in- and out-degrees for directed graphs) can be realized by a graph. +Note that the graph does not have to be simple, it may contain loop and multiple edges. For undirected graphs, it also checks whether the sum of degrees is even. -For directed graphs, the function checks whether the lengths of the two -degree vectors are equal and whether their sums are also equal. These are -known sufficient and necessary conditions for a degree sequence to be valid. +For directed graphs, the function checks whether the lengths of the two degree vectors are equal and whether their sums are also equal. +These are known sufficient and necessary conditions for a degree sequence to be valid. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_graphical}{\code{is_graphical()}} diff --git a/man/is_forest.Rd b/man/is_forest.Rd index 2db5a6780a8..f8de1d23a48 100644 --- a/man/is_forest.Rd +++ b/man/is_forest.Rd @@ -12,17 +12,14 @@ is_forest(graph, ..., mode = c("out", "in", "all", "total"), details = FALSE) \item{...}{These dots are for future extensions and must be empty.} \item{mode}{Whether to consider edge directions in a directed graph. -\sQuote{all} ignores edge directions; \sQuote{out} requires edges to be -oriented outwards from the root, \sQuote{in} requires edges to be oriented -towards the root.} +\sQuote{all} ignores edge directions; \sQuote{out} requires edges to be oriented outwards from the root, +\sQuote{in} requires edges to be oriented towards the root.} -\item{details}{Whether to return only whether the graph is a tree (\code{FALSE}) -or also a possible root (\code{TRUE})} +\item{details}{Whether to return only whether the graph is a tree (\code{FALSE}) or also a possible root (\code{TRUE})} } \value{ -When \code{details} is \code{FALSE}, a logical value that indicates -whether the graph is a tree. When \code{details} is \code{TRUE}, a named -list with two entries: +When \code{details} is \code{FALSE}, a logical value that indicates whether the graph is a tree. +When \code{details} is \code{TRUE}, a named list with two entries: \describe{ \item{res}{ Logical value that indicates whether the graph is a tree. @@ -33,18 +30,15 @@ The root vertex of the tree; undefined if the graph is not a tree. } } \description{ -\code{is_forest()} decides whether a graph is a forest, and optionally returns a -set of possible root vertices for its components. +\code{is_forest()} decides whether a graph is a forest, and optionally returns a set of possible root vertices for its components. } \details{ -An undirected graph is a forest if it has no cycles. In the directed case, -a possible additional requirement is that edges in each tree are oriented -away from the root (out-trees or arborescences) or all edges are oriented -towards the root (in-trees or anti-arborescences). This test can be -controlled using the mode parameter. +An undirected graph is a forest if it has no cycles. +In the directed case, +a possible additional requirement is that edges in each tree are oriented away from the root (out-trees or arborescences) or all edges are oriented towards the root (in-trees or anti-arborescences). +This test can be controlled using the mode parameter. -By convention, the null graph (i.e. the graph with no vertices) is considered -to be a forest. +By convention, the null graph (i.e. the graph with no vertices) is considered to be a forest. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_forest}{\code{is_forest()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/is_graphical.Rd b/man/is_graphical.Rd index b9050392166..5664258162f 100644 --- a/man/is_graphical.Rd +++ b/man/is_graphical.Rd @@ -12,32 +12,29 @@ is_graphical( ) } \arguments{ -\item{out.deg}{Integer vector, the degree sequence for undirected graphs, or -the out-degree sequence for directed graphs.} +\item{out.deg}{Integer vector, the degree sequence for undirected graphs, or the out-degree sequence for directed graphs.} -\item{in.deg}{\code{NULL} or an integer vector. For undirected graphs, it -should be \code{NULL}. For directed graphs it specifies the in-degrees.} +\item{in.deg}{\code{NULL} or an integer vector. +For undirected graphs, it should be \code{NULL}. +For directed graphs it specifies the in-degrees.} \item{...}{These dots are for future extensions and must be empty.} -\item{allowed.edge.types}{The allowed edge types in the graph. \sQuote{simple} -means that neither loop nor multiple edges are allowed (i.e. the graph must be -simple). \sQuote{loops} means that loop edges are allowed but mutiple edges -are not. \sQuote{multi} means that multiple edges are allowed but loop edges -are not. \sQuote{all} means that both loop edges and multiple edges are -allowed.} +\item{allowed.edge.types}{The allowed edge types in the graph. +\sQuote{simple} means that neither loop nor multiple edges are allowed (i.e. the graph must be simple). +\sQuote{loops} means that loop edges are allowed but mutiple edges are not. +\sQuote{multi} means that multiple edges are allowed but loop edges are not. +\sQuote{all} means that both loop edges and multiple edges are allowed.} } \value{ A logical scalar. } \description{ -Determine whether the given vertex degrees (in- and out-degrees for -directed graphs) can be realized by a graph. +Determine whether the given vertex degrees (in- and out-degrees for directed graphs) can be realized by a graph. } \details{ -The classical concept of graphicality assumes simple graphs. This function -can perform the check also when self-loops, multi-edges, or both are allowed -in the graph. +The classical concept of graphicality assumes simple graphs. +This function can perform the check also when self-loops, multi-edges, or both are allowed in the graph. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_graphical}{\code{is_graphical()}} diff --git a/man/is_igraph.Rd b/man/is_igraph.Rd index 798a29ab267..627175e72f6 100644 --- a/man/is_igraph.Rd +++ b/man/is_igraph.Rd @@ -10,8 +10,7 @@ is_igraph(graph) \item{graph}{An R object.} } \value{ -A logical constant, \code{TRUE} if argument \code{graph} is a graph -object. +A logical constant, \code{TRUE} if argument \code{graph} is a graph object. } \description{ Is this object an igraph graph? diff --git a/man/is_min_separator.Rd b/man/is_min_separator.Rd index 7dc7fb1e483..29470d6ed97 100644 --- a/man/is_min_separator.Rd +++ b/man/is_min_separator.Rd @@ -7,23 +7,20 @@ is_min_separator(graph, candidate) } \arguments{ -\item{graph}{The input graph. It may be directed, but edge directions are -ignored.} +\item{graph}{The input graph. +It may be directed, but edge directions are ignored.} -\item{candidate}{A numeric vector giving the vertex IDs of the candidate -separator.} +\item{candidate}{A numeric vector giving the vertex IDs of the candidate separator.} } \value{ -A Logical, whether the supplied vertex set is a (minimal) -vertex separator or not. +A Logical, whether the supplied vertex set is a (minimal) vertex separator or not. } \description{ Check whether a given set of vertices is a minimal vertex separator. } \details{ -\code{is_min_separator()} decides whether the supplied vertex set is a minimal -vertex separator. A minimal vertex separator is a vertex separator, such -that none of its proper subsets are a vertex separator. +\code{is_min_separator()} decides whether the supplied vertex set is a minimal vertex separator. +A minimal vertex separator is a vertex separator, such that none of its proper subsets are a vertex separator. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Separators.html#igraph_is_minimal_separator}{\code{is_minimal_separator()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/is_named.Rd b/man/is_named.Rd index 7e87fc00c07..e015a35e3e6 100644 --- a/man/is_named.Rd +++ b/man/is_named.Rd @@ -13,21 +13,16 @@ is_named(graph) A logical scalar. } \description{ -An igraph graph is named, if there is a symbolic name associated with its -vertices. +An igraph graph is named, if there is a symbolic name associated with its vertices. } \details{ -In igraph vertices can always be identified and specified via their numeric -vertex IDs. This is, however, not always convenient, and in many cases there -exist symbolic IDs that correspond to the vertices. To allow this more -flexible identification of vertices, one can assign a vertex attribute -called \sQuote{name} to an igraph graph. After doing this, the symbolic -vertex names can be used in all igraph functions, instead of the numeric -IDs. +In igraph vertices can always be identified and specified via their numeric vertex IDs. +This is, however, not always convenient, and in many cases there exist symbolic IDs that correspond to the vertices. +To allow this more flexible identification of vertices, one can assign a vertex attribute called \sQuote{name} to an igraph graph. +After doing this, the symbolic vertex names can be used in all igraph functions, instead of the numeric IDs. -Note that the uniqueness of vertex names are currently not enforced in -igraph, you have to check that for yourself, when assigning the vertex -names. +Note that the uniqueness of vertex names are currently not enforced in igraph, you have to check that for yourself, +when assigning the vertex names. } \examples{ diff --git a/man/is_separator.Rd b/man/is_separator.Rd index f9df1711a41..479f767472f 100644 --- a/man/is_separator.Rd +++ b/man/is_separator.Rd @@ -7,23 +7,18 @@ is_separator(graph, candidate) } \arguments{ -\item{graph}{The input graph. It may be directed, but edge directions are -ignored.} +\item{graph}{The input graph. +It may be directed, but edge directions are ignored.} -\item{candidate}{A numeric vector giving the vertex IDs of the candidate -separator.} +\item{candidate}{A numeric vector giving the vertex IDs of the candidate separator.} } \value{ -A Logical, whether the supplied vertex set is a (minimal) -vertex separator or not. -lists all vertex separator of minimum size. +A Logical, whether the supplied vertex set is a (minimal) vertex separator or not. lists all vertex separator of minimum size. } \description{ -\code{is_separator()} determines whether the supplied vertex set is a vertex -separator: -A vertex set \eqn{S} is a separator if there are vertices \eqn{u} and \eqn{v} -in the graph such that all paths between \eqn{u} and \eqn{v} pass -through some vertices in \eqn{S}. +\code{is_separator()} determines whether the supplied vertex set is a vertex separator: +A vertex set \eqn{S} is a separator +if there are vertices \eqn{u} and \eqn{v} in the graph such that all paths between \eqn{u} and \eqn{v} pass through some vertices in \eqn{S}. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Separators.html#igraph_is_separator}{\code{is_separator()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/is_tree.Rd b/man/is_tree.Rd index 86e89206f24..3c8c7e3b1da 100644 --- a/man/is_tree.Rd +++ b/man/is_tree.Rd @@ -12,17 +12,14 @@ is_tree(graph, ..., mode = c("out", "in", "all", "total"), details = FALSE) \item{...}{These dots are for future extensions and must be empty.} \item{mode}{Whether to consider edge directions in a directed graph. -\sQuote{all} ignores edge directions; \sQuote{out} requires edges to be -oriented outwards from the root, \sQuote{in} requires edges to be oriented -towards the root.} +\sQuote{all} ignores edge directions; \sQuote{out} requires edges to be oriented outwards from the root, +\sQuote{in} requires edges to be oriented towards the root.} -\item{details}{Whether to return only whether the graph is a tree (\code{FALSE}) -or also a possible root (\code{TRUE})} +\item{details}{Whether to return only whether the graph is a tree (\code{FALSE}) or also a possible root (\code{TRUE})} } \value{ -When \code{details} is \code{FALSE}, a logical value that indicates -whether the graph is a tree. When \code{details} is \code{TRUE}, a named -list with two entries: +When \code{details} is \code{FALSE}, a logical value that indicates whether the graph is a tree. +When \code{details} is \code{TRUE}, a named list with two entries: \describe{ \item{res}{ Logical value that indicates whether the graph is a tree. @@ -33,18 +30,15 @@ The root vertex of the tree; undefined if the graph is not a tree. } } \description{ -\code{is_tree()} decides whether a graph is a tree, and optionally returns a -possible root vertex if the graph is a tree. +\code{is_tree()} decides whether a graph is a tree, and optionally returns a possible root vertex if the graph is a tree. } \details{ An undirected graph is a tree if it is connected and has no cycles. -In the directed case, a possible additional requirement is that all edges -are oriented away from a root (out-tree or arborescence) or all edges are -oriented towards a root (in-tree or anti-arborescence). This test can be -controlled using the mode parameter. +In the directed case, +a possible additional requirement is that all edges are oriented away from a root (out-tree or arborescence) or all edges are oriented towards a root (in-tree or anti-arborescence). +This test can be controlled using the mode parameter. -By convention, the null graph (i.e. the graph with no vertices) is considered -not to be a tree. +By convention, the null graph (i.e. the graph with no vertices) is considered not to be a tree. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_tree}{\code{is_tree()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/is_weighted.Rd b/man/is_weighted.Rd index 3f35b29936f..95edfe3836b 100644 --- a/man/is_weighted.Rd +++ b/man/is_weighted.Rd @@ -13,20 +13,17 @@ is_weighted(graph) A logical scalar. } \description{ -In weighted graphs, a real number is assigned to each (directed or -undirected) edge. +In weighted graphs, a real number is assigned to each (directed or undirected) edge. } \details{ -In igraph edge weights are represented via an edge attribute, called -\sQuote{weight}. The \code{is_weighted()} function only checks that such an -attribute exists. (It does not even checks that it is a numeric edge -attribute.) +In igraph edge weights are represented via an edge attribute, called \sQuote{weight}. +The \code{is_weighted()} function only checks that such an attribute exists. +(It does not even checks that it is a numeric edge attribute.) Edge weights are used for different purposes by the different functions. -E.g. shortest path functions use it as the cost of the path; community -finding methods use it as the strength of the relationship between two -vertices, etc. Check the manual pages of the functions working with weighted -graphs for details. +E.g. shortest path functions use it as the cost of the path; +community finding methods use it as the strength of the relationship between two vertices, +etc. Check the manual pages of the functions working with weighted graphs for details. } \examples{ diff --git a/man/isomorphic.Rd b/man/isomorphic.Rd index 1aee5f8c1ec..92acb7413e5 100644 --- a/man/isomorphic.Rd +++ b/man/isomorphic.Rd @@ -23,9 +23,9 @@ is_isomorphic_to( \item{graph2}{The second graph.} -\item{method}{The method to use. Possible values: \sQuote{auto}, -\sQuote{direct}, \sQuote{vf2}, \sQuote{bliss}. See their details -below.} +\item{method}{The method to use. +Possible values: \sQuote{auto}, \sQuote{direct}, \sQuote{vf2}, \sQuote{bliss}. +See their details below.} \item{...}{Additional arguments, passed to the various methods.} } @@ -52,16 +52,14 @@ used. \section{\sQuote{direct} method}{ -This method only works on graphs with three or four vertices, -and it is based on a pre-calculated and stored table. It does not -have any extra arguments. +This method only works on graphs with three or four vertices, and it is based on a pre-calculated and stored table. +It does not have any extra arguments. } \section{\sQuote{vf2} method}{ -This method uses the VF2 algorithm by Cordella, Foggia et al., see -references below. It supports vertex and edge colors and have the -following extra arguments: +This method uses the VF2 algorithm by Cordella, Foggia et al., see references below. +It supports vertex and edge colors and have the following extra arguments: \describe{ \item{vertex.color1, vertex.color2}{ Optional integer vectors giving the colors of the vertices for colored graph isomorphism. @@ -79,11 +77,9 @@ If you want to ignore these attributes, then supply \code{NULL} for both of thes \section{\sQuote{bliss} method}{ -Uses the BLISS algorithm by Junttila and Kaski, and it works for -undirected graphs. For both graphs the -\code{\link[=canonical_permutation]{canonical_permutation()}} and then the \code{\link[=permute]{permute()}} -function is called to transfer them into canonical form; finally the -canonical forms are compared. +Uses the BLISS algorithm by Junttila and Kaski, and it works for undirected graphs. +For both graphs the \code{\link[=canonical_permutation]{canonical_permutation()}} and then the \code{\link[=permute]{permute()}} function is called to transfer them into canonical form; +finally the canonical forms are compared. Extra arguments: \describe{ \item{sh}{ diff --git a/man/isomorphism_class.Rd b/man/isomorphism_class.Rd index 86bc8544fa3..c6396c4202d 100644 --- a/man/isomorphism_class.Rd +++ b/man/isomorphism_class.Rd @@ -11,18 +11,16 @@ isomorphism_class(graph, v) \arguments{ \item{graph}{The input graph.} -\item{v}{Optionally a vertex sequence. If not missing, then an induced -subgraph of the input graph, consisting of this vertices, is used.} +\item{v}{Optionally a vertex sequence. +If not missing, then an induced subgraph of the input graph, consisting of this vertices, is used.} } \value{ An integer number. } \description{ The isomorphism class is a non-negative integer number. -Graphs (with the same number of vertices) having the same isomorphism -class are isomorphic and isomorphic graphs always have the same -isomorphism class. Currently it can handle directed graphs with 3 or 4 -vertices and undirected graphs with 3 to 6 vertices. +Graphs (with the same number of vertices) having the same isomorphism class are isomorphic and isomorphic graphs always have the same isomorphism class. +Currently it can handle directed graphs with 3 or 4 vertices and undirected graphs with 3 to 6 vertices. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Isomorphism.html#igraph_isoclass_subgraph}{\code{isoclass_subgraph()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Isomorphism.html#igraph_isoclass}{\code{isoclass()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/isomorphisms.Rd b/man/isomorphisms.Rd index 569181f2632..72a80eddacd 100644 --- a/man/isomorphisms.Rd +++ b/man/isomorphisms.Rd @@ -12,29 +12,25 @@ isomorphisms(graph1, graph2, method = "vf2", ..., callback = NULL) \item{graph2}{The second graph.} -\item{method}{Currently only \sQuote{vf2} is supported, see -\code{\link[=isomorphic]{isomorphic()}} for details about it and extra arguments.} +\item{method}{Currently only \sQuote{vf2} is supported, see \code{\link[=isomorphic]{isomorphic()}} for details about it and extra arguments.} \item{...}{Extra arguments, passed to the various methods.} \item{callback}{Optional callback function to call for each isomorphism found. -If provided, the function should accept two arguments: \code{map12} (integer vector -mapping vertex IDs from graph1 to graph2, 1-based indexing) and \code{map21} -(integer vector mapping vertex IDs from graph2 to graph1, 1-based indexing). +If provided, the function should accept two arguments: +\code{map12} (integer vector mapping vertex IDs from graph1 to graph2, 1-based indexing) and \code{map21} (integer vector mapping vertex IDs from graph2 to graph1, 1-based indexing). The function should return \code{FALSE} to continue the search or \code{TRUE} to stop it. If \code{NULL} (the default), all isomorphisms are collected and returned as a list. Only supported for \code{method = "vf2"}. -\strong{Important limitation:} Callback functions must NOT call any igraph -functions (including simple queries like \code{vcount()} or \code{ecount()}). Doing -so will cause R to crash due to reentrancy issues. Extract -any needed graph information before calling the function with a callback, or -use collector mode (the default) and process results afterward.} +\strong{Important limitation:} Callback functions must NOT call any igraph functions (including simple queries like \code{vcount()} or \code{ecount()}). +Doing so will cause R to crash due to reentrancy issues. +Extract any needed graph information before calling the function with a callback, +or use collector mode (the default) and process results afterward.} } \value{ -If \code{callback} is \code{NULL}, returns a list of vertex sequences, corresponding -to all mappings from the first graph to the second. If \code{callback} is provided, -returns \code{NULL} invisibly. +If \code{callback} is \code{NULL}, returns a list of vertex sequences, corresponding to all mappings from the first graph to the second. +If \code{callback} is provided, returns \code{NULL} invisibly. } \description{ Calculate all isomorphic mappings between the vertices of two graphs diff --git a/man/ivs.Rd b/man/ivs.Rd index ff6d9beea0d..e7c2e8f2ff1 100644 --- a/man/ivs.Rd +++ b/man/ivs.Rd @@ -24,51 +24,41 @@ is_ivs(graph, candidate) \arguments{ \item{graph}{The input graph.} -\item{min}{Numeric constant, limit for the minimum size of the independent -vertex sets to find. \code{NULL} means no limit.} +\item{min}{Numeric constant, limit for the minimum size of the independent vertex sets to find. +\code{NULL} means no limit.} -\item{max}{Numeric constant, limit for the maximum size of the independent -vertex sets to find. \code{NULL} means no limit.} +\item{max}{Numeric constant, limit for the maximum size of the independent vertex sets to find. +\code{NULL} means no limit.} \item{candidate}{The vertex set to test for being an independent set.} } \value{ -\code{ivs()}, -\code{largest_ivs()} and -\code{max_ivs()} return a list containing numeric -vertex IDs, each list element is an independent vertex set. +\code{ivs()}, \code{largest_ivs()} and \code{max_ivs()} return a list containing numeric vertex IDs, +each list element is an independent vertex set. \code{ivs_size()} returns an integer constant. -\code{is_ivs()} returns \code{TRUE} if the candidate vertex set forms an -independent set. +\code{is_ivs()} returns \code{TRUE} if the candidate vertex set forms an independent set. } \description{ -A vertex set is called independent if there no edges between any two -vertices in it. These functions find independent vertex sets in undirected -graphs +A vertex set is called independent if there no edges between any two vertices in it. +These functions find independent vertex sets in undirected graphs } \details{ -\code{ivs()} finds all independent vertex sets in the -network, obeying the size limitations given in the \code{min} and \code{max} -arguments. +\code{ivs()} finds all independent vertex sets in the network, obeying the size limitations given in the \code{min} and \code{max} arguments. -\code{largest_ivs()} finds the largest independent vertex -sets in the graph. An independent vertex set is largest if there is no -independent vertex set with more vertices. +\code{largest_ivs()} finds the largest independent vertex sets in the graph. +An independent vertex set is largest if there is no independent vertex set with more vertices. -\code{max_ivs()} finds the maximal independent vertex -sets in the graph. An independent vertex set is maximal if it cannot be -extended to a larger independent vertex set. The largest independent vertex -sets are maximal, but the opposite is not always true. +\code{max_ivs()} finds the maximal independent vertex sets in the graph. +An independent vertex set is maximal if it cannot be extended to a larger independent vertex set. +The largest independent vertex sets are maximal, but the opposite is not always true. -\code{ivs_size()} calculate the size of the largest independent -vertex set(s). +\code{ivs_size()} calculate the size of the largest independent vertex set(s). \code{independence_number()} is an alias for \code{ivs_size()}. -These functions use the algorithm described by Tsukiyama et al., see -reference below. +These functions use the algorithm described by Tsukiyama et al., see reference below. \code{is_ivs()} tests if no pairs within a vertex set are connected. } diff --git a/man/k.regular.game.Rd b/man/k.regular.game.Rd index c69be583a5e..7da47ecdbb2 100644 --- a/man/k.regular.game.Rd +++ b/man/k.regular.game.Rd @@ -7,11 +7,9 @@ k.regular.game(no.of.nodes, k, directed = FALSE, multiple = FALSE) } \arguments{ -\item{no.of.nodes}{Integer scalar, the number of vertices in the generated -graph.} +\item{no.of.nodes}{Integer scalar, the number of vertices in the generated graph.} -\item{k}{Integer scalar, the degree of each vertex in the graph, or the -out-degree and in-degree in a directed graph.} +\item{k}{Integer scalar, the degree of each vertex in the graph, or the out-degree and in-degree in a directed graph.} \item{directed}{Logical, whether to create a directed graph.} @@ -20,8 +18,7 @@ out-degree and in-degree in a directed graph.} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{k.regular.game()} was renamed to \code{\link[=sample_k_regular]{sample_k_regular()}} to create a more -consistent API. +\code{k.regular.game()} was renamed to \code{\link[=sample_k_regular]{sample_k_regular()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_k_regular_game}{\code{k_regular_game()}} diff --git a/man/k_shortest_paths.Rd b/man/k_shortest_paths.Rd index 1dfe09896ef..d7932afa9dd 100644 --- a/man/k_shortest_paths.Rd +++ b/man/k_shortest_paths.Rd @@ -21,23 +21,21 @@ k_shortest_paths( \item{to}{The target vertex of the shortest paths.} -\item{k}{The number of paths to find. They will be returned in order of -increasing length.} +\item{k}{The number of paths to find. +They will be returned in order of increasing length.} \item{...}{These dots are for future extensions and must be empty.} -\item{weights}{Possibly a numeric vector giving edge weights. If this is -\code{NULL} and the graph has a \code{weight} edge attribute, then the -attribute is used. If this is \code{NA} then no weights are used (even if -the graph has a \code{weight} attribute). In a weighted graph, the length -of a path is the sum of the weights of its constituent edges.} +\item{weights}{Possibly a numeric vector giving edge weights. +If this is \code{NULL} and the graph has a \code{weight} edge attribute, then the attribute is used. +If this is \code{NA} then no weights are used (even if the graph has a \code{weight} attribute). +In a weighted graph, the length of a path is the sum of the weights of its constituent edges.} -\item{mode}{Character constant, gives whether the shortest paths to or from -the given vertices should be calculated for directed graphs. If \code{out} -then the shortest paths \emph{from} the vertex, if \verb{in} then \emph{to} -it will be considered. If \code{all}, the default, then the graph is treated -as undirected, i.e. edge directions are not taken into account. This -argument is ignored for undirected graphs.} +\item{mode}{Character constant, +gives whether the shortest paths to or from the given vertices should be calculated for directed graphs. +If \code{out} then the shortest paths \emph{from} the vertex, if \verb{in} then \emph{to} it will be considered. +If \code{all}, the default, then the graph is treated as undirected, i.e. edge directions are not taken into account. +This argument is ignored for undirected graphs.} } \value{ A named list with two components is returned: @@ -51,9 +49,8 @@ The list of \eqn{k} shortest paths in terms of edges } } \description{ -Finds the \eqn{k} shortest paths between the given source and target -vertex in order of increasing length. Currently this function uses -Yen's algorithm. +Finds the \eqn{k} shortest paths between the given source and target vertex in order of increasing length. +Currently this function uses Yen's algorithm. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_k_shortest_paths}{\code{get_k_shortest_paths()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/keeping_degseq.Rd b/man/keeping_degseq.Rd index 225e14316df..e4024e8f3cc 100644 --- a/man/keeping_degseq.Rd +++ b/man/keeping_degseq.Rd @@ -12,15 +12,13 @@ keeping_degseq(loops = FALSE, niter = 100) \item{niter}{Number of rewiring trials to perform.} } \description{ -This function can be used together with \code{\link[=rewire]{rewire()}} to -randomly rewire the edges while preserving the original graph's degree -distribution. +This function can be used together with \code{\link[=rewire]{rewire()}} to randomly rewire the edges +while preserving the original graph's degree distribution. } \details{ -The rewiring algorithm chooses two arbitrary edges in each step ((a,b) -and (c,d)) and substitutes them with (a,d) and (c,b), if they not -already exists in the graph. The algorithm does not create multiple -edges. +The rewiring algorithm chooses two arbitrary edges in each step ((a,b) and (c,d)) and substitutes them with (a,d) and (c,b), +if they not already exists in the graph. +The algorithm does not create multiple edges. } \examples{ g <- make_ring(10) diff --git a/man/knn.Rd b/man/knn.Rd index 96ba5158ecf..cc51e5db074 100644 --- a/man/knn.Rd +++ b/man/knn.Rd @@ -14,30 +14,27 @@ knn( ) } \arguments{ -\item{graph}{The input graph. It may be directed.} +\item{graph}{The input graph. +It may be directed.} \item{vids}{The vertices for which the calculation is performed. -The default \code{NULL} includes all vertices. Note, that if not all vertices are given here, then -both \sQuote{\code{knn}} and \sQuote{\code{knnk}} will be calculated based -on the given vertices only.} +The default \code{NULL} includes all vertices. +Note, that if not all vertices are given here, +then both \sQuote{\code{knn}} and \sQuote{\code{knnk}} will be calculated based on the given vertices only.} \item{...}{These dots are for future extensions and must be empty.} -\item{mode}{Character constant to indicate the type of neighbors to consider -in directed graphs. \code{out} considers out-neighbors, \verb{in} considers -in-neighbors and \code{all} ignores edge directions.} +\item{mode}{Character constant to indicate the type of neighbors to consider in directed graphs. +\code{out} considers out-neighbors, \verb{in} considers in-neighbors and \code{all} ignores edge directions.} \item{neighbor.degree.mode}{The type of degree to average in directed graphs. -\code{out} averages out-degrees, \verb{in} averages in-degrees and \code{all} -ignores edge directions for the degree calculation.} +\code{out} averages out-degrees, \verb{in} averages in-degrees and \code{all} ignores edge directions for the degree calculation.} -\item{weights}{Weight vector. If the graph has a \code{weight} edge -attribute, then this is used by default. If this argument is given, then -vertex strength (see \code{\link[=strength]{strength()}}) is used instead of vertex -degree. But note that \code{knnk} is still given in the function of the -normal vertex degree. -Weights are are used to calculate a weighted degree (also called -\code{\link[=strength]{strength()}}) instead of the degree.} +\item{weights}{Weight vector. +If the graph has a \code{weight} edge attribute, then this is used by default. +If this argument is given, then vertex strength (see \code{\link[=strength]{strength()}}) is used instead of vertex degree. +But note that \code{knnk} is still given in the function of the normal vertex degree. +Weights are are used to calculate a weighted degree (also called \code{\link[=strength]{strength()}}) instead of the degree.} } \value{ A list with two members: @@ -52,23 +49,20 @@ The first element is the average nearest neighbor degree of vertices with degree } } \description{ -Calculate the average nearest neighbor degree of the given vertices and the -same quantity in the function of vertex degree +Calculate the average nearest neighbor degree of the given vertices and the same quantity in the function of vertex degree } \details{ -Note that for zero degree vertices the answer in \sQuote{\code{knn}} is -\code{NaN} (zero divided by zero), the same is true for \sQuote{\code{knnk}} -if a given degree never appears in the network. +Note that for zero degree vertices the answer in \sQuote{\code{knn}} is \code{NaN} (zero divided by zero), +the same is true for \sQuote{\code{knnk}} if a given degree never appears in the network. The weighted version computes a weighted average of the neighbor degrees as \deqn{k_{nn,u} = \frac{1}{s_u} \sum_v w_{uv} k_v,}{k_nn_u = 1/s_u sum_v w_uv k_v,} -where \eqn{s_u = \sum_v w_{uv}}{s_u = sum_v w_uv} is the sum of the incident -edge weights of vertex \code{u}, i.e. its strength. -The sum runs over the neighbors \code{v} of vertex \code{u} -as indicated by \code{mode}. \eqn{w_{uv}}{w_uv} denotes the weighted adjacency matrix -and \eqn{k_v}{k_v} is the neighbors' degree, specified by \code{neighbor_degree_mode}. +where \eqn{s_u = \sum_v w_{uv}}{s_u = sum_v w_uv} is the sum of the incident edge weights of vertex \code{u}, i.e. its strength. +The sum runs over the neighbors \code{v} of vertex \code{u} as indicated by \code{mode}. +\eqn{w_{uv}}{w_uv} denotes the weighted adjacency matrix and \eqn{k_v}{k_v} is the neighbors' degree, +specified by \code{neighbor_degree_mode}. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_avg_nearest_neighbor_degree}{\code{avg_nearest_neighbor_degree()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/label.propagation.community.Rd b/man/label.propagation.community.Rd index f1c9f64e7d6..d3074d644b7 100644 --- a/man/label.propagation.community.Rd +++ b/man/label.propagation.community.Rd @@ -14,41 +14,39 @@ label.propagation.community( ) } \arguments{ -\item{graph}{The input graph. Note that the algorithm was originally -defined for undirected graphs. You are advised to set \sQuote{mode} to -\code{all} if you pass a directed graph here to treat it as -undirected.} +\item{graph}{The input graph. +Note that the algorithm was originally defined for undirected graphs. +You are advised to set \sQuote{mode} to \code{all} if you pass a directed graph here to treat it as undirected.} -\item{weights}{The weights of the edges. It must be a positive numeric vector, -\code{NULL} or \code{NA}. If it is \code{NULL} and the input graph has a -\sQuote{weight} edge attribute, then that attribute will be used. If -\code{NULL} and no such attribute is present, then the edges will have equal -weights. Set this to \code{NA} if the graph was a \sQuote{weight} edge -attribute, but you don't want to use it for community detection. A larger -edge weight means a stronger connection for this function.} +\item{weights}{The weights of the edges. +It must be a positive numeric vector, \code{NULL} or \code{NA}. +If it is \code{NULL} and the input graph has a \sQuote{weight} edge attribute, then that attribute will be used. +If \code{NULL} and no such attribute is present, then the edges will have equal weights. +Set this to \code{NA} if the graph was a \sQuote{weight} edge attribute, but you don't want to use it for community detection. +A larger edge weight means a stronger connection for this function.} \item{...}{These dots are for future extensions and must be empty.} -\item{mode}{Logical, whether to consider edge directions for the label propagation, -and if so, in which direction the labels should propagate. Ignored for undirected graphs. +\item{mode}{Logical, whether to consider edge directions for the label propagation, and if so, +in which direction the labels should propagate. +Ignored for undirected graphs. "all" means to ignore edge directions (even in directed graphs). "out" means to propagate labels along the natural direction of the edges. "in" means to propagate labels backwards (i.e. from head to tail).} -\item{initial}{The initial state. If \code{NULL}, every vertex will have a -different label at the beginning. Otherwise it must be a vector with an -entry for each vertex. Non-negative values denote different labels, negative -entries denote vertices without labels.} +\item{initial}{The initial state. +If \code{NULL}, every vertex will have a different label at the beginning. +Otherwise it must be a vector with an entry for each vertex. +Non-negative values denote different labels, negative entries denote vertices without labels.} -\item{fixed}{Logical vector denoting which labels are fixed. Of course this -makes sense only if you provided an initial state, otherwise this element -will be ignored. Also note that vertices without labels cannot be fixed.} +\item{fixed}{Logical vector denoting which labels are fixed. +Of course this makes sense only if you provided an initial state, otherwise this element will be ignored. +Also note that vertices without labels cannot be fixed.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{label.propagation.community()} was renamed to \code{\link[=cluster_label_prop]{cluster_label_prop()}} to create a more -consistent API. +\code{label.propagation.community()} was renamed to \code{\link[=cluster_label_prop]{cluster_label_prop()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Community.html#igraph_community_label_propagation}{\code{community_label_propagation()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/laplacian_matrix.Rd b/man/laplacian_matrix.Rd index 93aae57f231..ed285c78269 100644 --- a/man/laplacian_matrix.Rd +++ b/man/laplacian_matrix.Rd @@ -15,17 +15,15 @@ laplacian_matrix( \arguments{ \item{graph}{The input graph.} -\item{weights}{An optional vector giving edge weights for weighted Laplacian -matrix. If this is \code{NULL} and the graph has an edge attribute called -\code{weight}, then it will be used automatically. Set this to \code{NA} if -you want the unweighted Laplacian on a graph that has a \code{weight} edge -attribute.} +\item{weights}{An optional vector giving edge weights for weighted Laplacian matrix. +If this is \code{NULL} and the graph has an edge attribute called \code{weight}, then it will be used automatically. +Set this to \code{NA} if you want the unweighted Laplacian on a graph that has a \code{weight} edge attribute.} -\item{sparse}{Logical, whether to return the result as a sparse -matrix. The \code{Matrix} package is required for sparse matrices.} +\item{sparse}{Logical, whether to return the result as a sparse matrix. +The \code{Matrix} package is required for sparse matrices.} -\item{normalization}{The normalization method to use when calculating the -Laplacian matrix. See the "Normalization methods" section on this page.} +\item{normalization}{The normalization method to use when calculating the Laplacian matrix. +See the "Normalization methods" section on this page.} \item{normalized}{Deprecated, use \code{normalization} instead.} } @@ -36,26 +34,21 @@ A numeric matrix. The Laplacian of a graph. } \details{ -The Laplacian Matrix of a graph is a symmetric matrix having the same number -of rows and columns as the number of vertices in the graph and element (i,j) -is d[i], the degree of vertex i if if i==j, -1 if i!=j and there is an edge -between vertices i and j and 0 otherwise. +The Laplacian Matrix of a graph is a symmetric matrix having the same number of rows and columns as the number of vertices in the graph and element (i,j) is d[i], +the degree of vertex i if if i==j, -1 if i!=j and there is an edge between vertices i and j and 0 otherwise. -The Laplacian matrix can also be normalized, with several -conventional normalization methods. +The Laplacian matrix can also be normalized, with several conventional normalization methods. See the "Normalization methods" section on this page. -The weighted version of the Laplacian simply works with the weighted degree -instead of the plain degree. I.e. (i,j) is d[i], the weighted degree of -vertex i if if i==j, -w if i!=j and there is an edge between vertices i and -j with weight w, and 0 otherwise. The weighted degree of a vertex is the sum -of the weights of its adjacent edges. +The weighted version of the Laplacian simply works with the weighted degree instead of the plain degree. +I.e. (i,j) is d[i], the weighted degree of vertex i if if i==j, -w if i!=j and there is an edge between vertices i and j with weight w, +and 0 otherwise. +The weighted degree of a vertex is the sum of the weights of its adjacent edges. } \section{Normalization methods}{ -The Laplacian matrix \eqn{L} is defined in terms of the adjacency matrix -\eqn{A} and a diagonal matrix \eqn{D} containing the degrees as follows: +The Laplacian matrix \eqn{L} is defined in terms of the adjacency matrix \eqn{A} and a diagonal matrix \eqn{D} containing the degrees as follows: \itemize{ \item "unnormalized": Unnormalized Laplacian, \eqn{L = D - A}. \item "symmetric": Symmetrically normalized Laplacian, diff --git a/man/largest.cliques.Rd b/man/largest.cliques.Rd index bd5f6f9644c..e432451546d 100644 --- a/man/largest.cliques.Rd +++ b/man/largest.cliques.Rd @@ -12,8 +12,7 @@ largest.cliques(graph) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{largest.cliques()} was renamed to \code{\link[=largest_cliques]{largest_cliques()}} to create a more -consistent API. +\code{largest.cliques()} was renamed to \code{\link[=largest_cliques]{largest_cliques()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Cliques.html#igraph_largest_cliques}{\code{largest_cliques()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/largest.independent.vertex.sets.Rd b/man/largest.independent.vertex.sets.Rd index 8287b1a7dbb..bedf94501fa 100644 --- a/man/largest.independent.vertex.sets.Rd +++ b/man/largest.independent.vertex.sets.Rd @@ -12,8 +12,7 @@ largest.independent.vertex.sets(graph) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{largest.independent.vertex.sets()} was renamed to \code{\link[=largest_ivs]{largest_ivs()}} to create a more -consistent API. +\code{largest.independent.vertex.sets()} was renamed to \code{\link[=largest_ivs]{largest_ivs()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Cliques.html#igraph_largest_independent_vertex_sets}{\code{largest_independent_vertex_sets()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/lastcit.game.Rd b/man/lastcit.game.Rd index 538998802c3..96330b64dca 100644 --- a/man/lastcit.game.Rd +++ b/man/lastcit.game.Rd @@ -17,21 +17,18 @@ lastcit.game( \item{edges}{Number of edges per step.} -\item{agebins}{Number of aging bins. The default \code{NULL} uses \code{n / 7100}.} +\item{agebins}{Number of aging bins. +The default \code{NULL} uses \code{n / 7100}.} -\item{pref}{Vector (\code{sample_last_cit()} and \code{sample_cit_types()} or -matrix (\code{sample_cit_cit_types()}) giving the (unnormalized) citation -probabilities for the different vertex types. The default \code{NULL} uses -\code{(1:(agebins + 1))^-3} for \code{sample_last_cit()} and all-one probabilities -for the other two.} +\item{pref}{Vector (\code{sample_last_cit()} and \code{sample_cit_types()} or matrix (\code{sample_cit_cit_types()}) giving the (unnormalized) citation probabilities for the different vertex types. +The default \code{NULL} uses \code{(1:(agebins + 1))^-3} for \code{sample_last_cit()} and all-one probabilities for the other two.} \item{directed}{Logical, whether to generate directed networks.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{lastcit.game()} was renamed to \code{\link[=sample_last_cit]{sample_last_cit()}} to create a more -consistent API. +\code{lastcit.game()} was renamed to \code{\link[=sample_last_cit]{sample_last_cit()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_lastcit_game}{\code{lastcit_game()}} diff --git a/man/layout.auto.Rd b/man/layout.auto.Rd index 0278f8f3d9b..ee7e038dfb4 100644 --- a/man/layout.auto.Rd +++ b/man/layout.auto.Rd @@ -11,14 +11,12 @@ layout.auto(graph, dim = 2, ...) \item{dim}{Dimensions, should be 2 or 3.} -\item{...}{Extra arguments are passed to the real layout function that -\code{layout_nicely()} ends up calling.} +\item{...}{Extra arguments are passed to the real layout function that \code{layout_nicely()} ends up calling.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{layout.auto()} was renamed to \code{\link[=layout_nicely]{layout_nicely()}} to create a more -consistent API. +\code{layout.auto()} was renamed to \code{\link[=layout_nicely]{layout_nicely()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Layout.html#igraph_layout_align}{\code{layout_align()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_forest}{\code{is_forest()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/layout.bipartite.Rd b/man/layout.bipartite.Rd index a1d9c50972e..ebd840b09d1 100644 --- a/man/layout.bipartite.Rd +++ b/man/layout.bipartite.Rd @@ -7,28 +7,23 @@ layout.bipartite(graph, types = NULL, hgap = 1, vgap = 1, maxiter = 100) } \arguments{ -\item{graph}{The bipartite input graph. It should have a logical -\sQuote{\code{type}} vertex attribute, or the \code{types} argument must be -given.} +\item{graph}{The bipartite input graph. +It should have a logical \sQuote{\code{type}} vertex attribute, or the \code{types} argument must be given.} -\item{types}{A logical vector, the vertex types. If this argument is -\code{NULL} (the default), then the \sQuote{\code{type}} vertex attribute is -used.} +\item{types}{A logical vector, the vertex types. +If this argument is \code{NULL} (the default), then the \sQuote{\code{type}} vertex attribute is used.} -\item{hgap}{Real scalar, the minimum horizontal gap between vertices in the -same layer.} +\item{hgap}{Real scalar, the minimum horizontal gap between vertices in the same layer.} \item{vgap}{Real scalar, the distance between the two layers.} -\item{maxiter}{Integer scalar, the maximum number of iterations in the -crossing minimization stage. 100 is a reasonable default; if you feel that -you have too many edge crossings, increase this.} +\item{maxiter}{Integer scalar, the maximum number of iterations in the crossing minimization stage. +100 is a reasonable default; if you feel that you have too many edge crossings, increase this.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{layout.bipartite()} was renamed to \code{\link[=layout_as_bipartite]{layout_as_bipartite()}} to create a more -consistent API. +\code{layout.bipartite()} was renamed to \code{\link[=layout_as_bipartite]{layout_as_bipartite()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Layout.html#igraph_layout_bipartite}{\code{layout_bipartite()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/layout.circle.Rd b/man/layout.circle.Rd index 411b4eedb28..0adaa3f6971 100644 --- a/man/layout.circle.Rd +++ b/man/layout.circle.Rd @@ -14,7 +14,6 @@ layout.circle(..., params = list()) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{layout.circle()} was renamed to \code{\link[=layout_in_circle]{layout_in_circle()}} to create a more -consistent API. +\code{layout.circle()} was renamed to \code{\link[=layout_in_circle]{layout_in_circle()}} to create a more consistent API. } \keyword{internal} diff --git a/man/layout.davidson.harel.Rd b/man/layout.davidson.harel.Rd index 2df57ce4609..f99d8c88bb8 100644 --- a/man/layout.davidson.harel.Rd +++ b/man/layout.davidson.harel.Rd @@ -18,42 +18,37 @@ layout.davidson.harel( ) } \arguments{ -\item{graph}{The graph to lay out. Edge directions are ignored.} +\item{graph}{The graph to lay out. +Edge directions are ignored.} -\item{coords}{Optional starting positions for the vertices. If this argument -is not \code{NULL} then it should be an appropriate matrix of starting -coordinates.} +\item{coords}{Optional starting positions for the vertices. +If this argument is not \code{NULL} then it should be an appropriate matrix of starting coordinates.} \item{maxiter}{Number of iterations to perform in the first phase.} -\item{fineiter}{Number of iterations in the fine tuning phase. The -default \code{NULL} uses \code{max(10, log2(vcount(graph)))}.} +\item{fineiter}{Number of iterations in the fine tuning phase. +The default \code{NULL} uses \code{max(10, log2(vcount(graph)))}.} \item{cool.fact}{Cooling factor.} -\item{weight.node.dist}{Weight for the node-node distances component of the -energy function.} +\item{weight.node.dist}{Weight for the node-node distances component of the energy function.} -\item{weight.border}{Weight for the distance from the border component of -the energy function. It can be set to zero, if vertices are allowed to sit -on the border.} +\item{weight.border}{Weight for the distance from the border component of the energy function. +It can be set to zero, if vertices are allowed to sit on the border.} -\item{weight.edge.lengths}{Weight for the edge length component of the -energy function. The default \code{NULL} uses \code{edge_density(graph) / 10}.} +\item{weight.edge.lengths}{Weight for the edge length component of the energy function. +The default \code{NULL} uses \code{edge_density(graph) / 10}.} -\item{weight.edge.crossings}{Weight for the edge crossing component of the -energy function. The default \code{NULL} uses -\code{1 - sqrt(edge_density(graph))}.} +\item{weight.edge.crossings}{Weight for the edge crossing component of the energy function. +The default \code{NULL} uses \code{1 - sqrt(edge_density(graph))}.} -\item{weight.node.edge.dist}{Weight for the node-edge distance component of -the energy function. The default \code{NULL} uses -\code{0.2 * (1 - edge_density(graph))}.} +\item{weight.node.edge.dist}{Weight for the node-edge distance component of the energy function. +The default \code{NULL} uses \code{0.2 * (1 - edge_density(graph))}.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{layout.davidson.harel()} was renamed to \code{\link[=layout_with_dh]{layout_with_dh()}} to create a more -consistent API. +\code{layout.davidson.harel()} was renamed to \code{\link[=layout_with_dh]{layout_with_dh()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Layout.html#igraph_layout_davidson_harel}{\code{layout_davidson_harel()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_density}{\code{density()}} diff --git a/man/layout.drl.Rd b/man/layout.drl.Rd index 2a6be6f177a..b79757f04a1 100644 --- a/man/layout.drl.Rd +++ b/man/layout.drl.Rd @@ -16,34 +16,30 @@ layout.drl( \arguments{ \item{graph}{The input graph, in can be directed or undirected.} -\item{use.seed}{Logical, whether to use the coordinates given in the -\code{seed} argument as a starting point.} +\item{use.seed}{Logical, whether to use the coordinates given in the \code{seed} argument as a starting point.} -\item{seed}{A matrix with two columns, the starting coordinates for the -vertices is \code{use.seed} is \code{TRUE}. It is ignored otherwise. The default -\code{NULL} draws uniformly random starting coordinates.} +\item{seed}{A matrix with two columns, the starting coordinates for the vertices is \code{use.seed} is \code{TRUE}. +It is ignored otherwise. +The default \code{NULL} draws uniformly random starting coordinates.} -\item{options}{Options for the layout generator, a named list. See details -below. The default \code{NULL} uses \code{drl_defaults$default}.} +\item{options}{Options for the layout generator, a named list. +See details below. +The default \code{NULL} uses \code{drl_defaults$default}.} -\item{weights}{The weights of the edges. It must be a positive numeric vector, -\code{NULL} or \code{NA}. If it is \code{NULL} and the input graph has a -\sQuote{weight} edge attribute, then that attribute will be used. If -\code{NULL} and no such attribute is present, then the edges will have equal -weights. Set this to \code{NA} if the graph was a \sQuote{weight} edge -attribute, but you don't want to use it for the layout. Larger edge weights -correspond to stronger connections.} +\item{weights}{The weights of the edges. +It must be a positive numeric vector, \code{NULL} or \code{NA}. +If it is \code{NULL} and the input graph has a \sQuote{weight} edge attribute, then that attribute will be used. +If \code{NULL} and no such attribute is present, then the edges will have equal weights. +Set this to \code{NA} if the graph was a \sQuote{weight} edge attribute, but you don't want to use it for the layout. +Larger edge weights correspond to stronger connections.} -\item{dim}{Either \sQuote{2} or \sQuote{3}, it specifies whether we want a -two dimensional or a three dimensional layout. Note that because of the -nature of the DrL algorithm, the three dimensional layout takes -significantly longer to compute.} +\item{dim}{Either \sQuote{2} or \sQuote{3}, it specifies whether we want a two dimensional or a three dimensional layout. +Note that because of the nature of the DrL algorithm, the three dimensional layout takes significantly longer to compute.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{layout.drl()} was renamed to \code{\link[=layout_with_drl]{layout_with_drl()}} to create a more -consistent API. +\code{layout.drl()} was renamed to \code{\link[=layout_with_drl]{layout_with_drl()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/layout.fruchterman.reingold.Rd b/man/layout.fruchterman.reingold.Rd index 960e60adb39..543dc040388 100644 --- a/man/layout.fruchterman.reingold.Rd +++ b/man/layout.fruchterman.reingold.Rd @@ -14,7 +14,6 @@ layout.fruchterman.reingold(..., params = list()) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{layout.fruchterman.reingold()} was renamed to \code{\link[=layout_with_fr]{layout_with_fr()}} to create a more -consistent API. +\code{layout.fruchterman.reingold()} was renamed to \code{\link[=layout_with_fr]{layout_with_fr()}} to create a more consistent API. } \keyword{internal} diff --git a/man/layout.gem.Rd b/man/layout.gem.Rd index 9046cfc733f..9d214936e8d 100644 --- a/man/layout.gem.Rd +++ b/man/layout.gem.Rd @@ -14,32 +14,31 @@ layout.gem( ) } \arguments{ -\item{graph}{The input graph. Edge directions are ignored.} +\item{graph}{The input graph. +Edge directions are ignored.} \item{coords}{Starting coordinates in a two or three column matrix, depending on the \code{dim} argument. Default: \code{NULL}.} -\item{maxiter}{The maximum number of iterations to perform. Updating a -single vertex counts as an iteration. The default \code{NULL} uses 40 * n * n, -where n is the number of vertices. The original paper suggests 4 * n * n, -but this usually only works if the other parameters are set up carefully.} +\item{maxiter}{The maximum number of iterations to perform. +Updating a single vertex counts as an iteration. +The default \code{NULL} uses 40 * n * n, where n is the number of vertices. +The original paper suggests 4 * n * n, but this usually only works if the other parameters are set up carefully.} -\item{temp.max}{The maximum allowed local temperature. The default \code{NULL} -uses the number of vertices.} +\item{temp.max}{The maximum allowed local temperature. +The default \code{NULL} uses the number of vertices.} -\item{temp.min}{The global temperature at which the algorithm terminates -(even before reaching \code{maxiter} iterations). A reasonable default is -1/10.} +\item{temp.min}{The global temperature at which the algorithm terminates (even before reaching \code{maxiter} iterations). +A reasonable default is 1/10.} -\item{temp.init}{Initial local temperature of all vertices. The default -\code{NULL} uses the square root of the number of vertices.} +\item{temp.init}{Initial local temperature of all vertices. +The default \code{NULL} uses the square root of the number of vertices.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{layout.gem()} was renamed to \code{\link[=layout_with_gem]{layout_with_gem()}} to create a more -consistent API. +\code{layout.gem()} was renamed to \code{\link[=layout_with_gem]{layout_with_gem()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Layout.html#igraph_layout_gem}{\code{layout_gem()}} diff --git a/man/layout.graphopt.Rd b/man/layout.graphopt.Rd index 6ae8c116bd7..ea86d7757f1 100644 --- a/man/layout.graphopt.Rd +++ b/man/layout.graphopt.Rd @@ -18,35 +18,33 @@ layout.graphopt( \arguments{ \item{graph}{The input graph.} -\item{start}{If given, then it should be a matrix with two columns and one -line for each vertex. This matrix will be used as starting positions for the -algorithm. If not given, then a random starting matrix is used.} +\item{start}{If given, then it should be a matrix with two columns and one line for each vertex. +This matrix will be used as starting positions for the algorithm. +If not given, then a random starting matrix is used.} -\item{niter}{Integer scalar, the number of iterations to perform. Should be -a couple of hundred in general. If you have a large graph then you might -want to only do a few iterations and then check the result. If it is not -good enough you can feed it in again in the \code{start} argument. The -default value is 500.} +\item{niter}{Integer scalar, the number of iterations to perform. +Should be a couple of hundred in general. +If you have a large graph then you might want to only do a few iterations and then check the result. +If it is not good enough you can feed it in again in the \code{start} argument. +The default value is 500.} -\item{charge}{The charge of the vertices, used to calculate electric -repulsion. The default is 0.001.} +\item{charge}{The charge of the vertices, used to calculate electric repulsion. +The default is 0.001.} -\item{mass}{The mass of the vertices, used for the spring forces. The -default is 30.} +\item{mass}{The mass of the vertices, used for the spring forces. +The default is 30.} -\item{spring.length}{The length of the springs, an integer number. The -default value is zero.} +\item{spring.length}{The length of the springs, an integer number. +The default value is zero.} \item{spring.constant}{The spring constant, the default value is one.} -\item{max.sa.movement}{Real constant, it gives the maximum amount of -movement allowed in a single step along a single axis. The default value is -5.} +\item{max.sa.movement}{Real constant, it gives the maximum amount of movement allowed in a single step along a single axis. +The default value is 5.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{layout.graphopt()} was renamed to \code{\link[=layout_with_graphopt]{layout_with_graphopt()}} to create a more -consistent API. +\code{layout.graphopt()} was renamed to \code{\link[=layout_with_graphopt]{layout_with_graphopt()}} to create a more consistent API. } \keyword{internal} diff --git a/man/layout.grid.Rd b/man/layout.grid.Rd index 573f3632ff2..b5b32ca9b88 100644 --- a/man/layout.grid.Rd +++ b/man/layout.grid.Rd @@ -9,22 +9,21 @@ layout.grid(graph, width = 0, height = 0, dim = 2) \arguments{ \item{graph}{The input graph.} -\item{width}{The number of vertices in a single row of the grid. If this is -zero or negative, then for 2d layouts the width of the grid will be the -square root of the number of vertices in the graph, rounded up to the next -integer. Similarly, it will be the cube root for 3d layouts.} +\item{width}{The number of vertices in a single row of the grid. +If this is zero or negative, then for 2d layouts the width of the grid will be the square root of the number of vertices in the graph, +rounded up to the next integer. +Similarly, it will be the cube root for 3d layouts.} -\item{height}{The number of vertices in a single column of the grid, for -three dimensional layouts. If this is zero or negative, then it is -determinted automatically.} +\item{height}{The number of vertices in a single column of the grid, for three dimensional layouts. +If this is zero or negative, then it is determinted automatically.} -\item{dim}{Two or three. Whether to make 2d or a 3d layout.} +\item{dim}{Two or three. +Whether to make 2d or a 3d layout.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{layout.grid()} was renamed to \code{\link[=layout_on_grid]{layout_on_grid()}} to create a more -consistent API. +\code{layout.grid()} was renamed to \code{\link[=layout_on_grid]{layout_on_grid()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Layout.html#igraph_layout_grid_3d}{\code{layout_grid_3d()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Layout.html#igraph_layout_grid}{\code{layout_grid()}} diff --git a/man/layout.kamada.kawai.Rd b/man/layout.kamada.kawai.Rd index 5b7652d09a4..6311d57ca5c 100644 --- a/man/layout.kamada.kawai.Rd +++ b/man/layout.kamada.kawai.Rd @@ -14,7 +14,6 @@ layout.kamada.kawai(..., params = list()) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{layout.kamada.kawai()} was renamed to \code{\link[=layout_with_kk]{layout_with_kk()}} to create a more -consistent API. +\code{layout.kamada.kawai()} was renamed to \code{\link[=layout_with_kk]{layout_with_kk()}} to create a more consistent API. } \keyword{internal} diff --git a/man/layout.lgl.Rd b/man/layout.lgl.Rd index b641b81a5b2..4572621b6e6 100644 --- a/man/layout.lgl.Rd +++ b/man/layout.lgl.Rd @@ -14,7 +14,6 @@ layout.lgl(..., params = list()) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{layout.lgl()} was renamed to \code{\link[=layout_with_lgl]{layout_with_lgl()}} to create a more -consistent API. +\code{layout.lgl()} was renamed to \code{\link[=layout_with_lgl]{layout_with_lgl()}} to create a more consistent API. } \keyword{internal} diff --git a/man/layout.mds.Rd b/man/layout.mds.Rd index 46448d69a0d..b2e10322397 100644 --- a/man/layout.mds.Rd +++ b/man/layout.mds.Rd @@ -9,23 +9,21 @@ layout.mds(graph, dist = NULL, dim = 2, options = arpack_defaults()) \arguments{ \item{graph}{The input graph.} -\item{dist}{The distance matrix for the multidimensional scaling. If -\code{NULL} (the default), then the unweighted shortest path matrix is used.} +\item{dist}{The distance matrix for the multidimensional scaling. +If \code{NULL} (the default), +then the unweighted shortest path matrix is used.} -\item{dim}{\code{layout_with_mds()} supports dimensions up to the number of nodes -minus one, but only if the graph is connected; for unconnected graphs, the -only possible value is 2. This is because \code{merge_coords()} only works in -2D.} +\item{dim}{\code{layout_with_mds()} supports dimensions up to the number of nodes minus one, but only if the graph is connected; +for unconnected graphs, the only possible value is 2. This is because \code{merge_coords()} only works in 2D.} -\item{options}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} This argument is not -supported from igraph version 1.6.0, as ARPACK is not used any more for -solving the eigenproblem. Supplying it raises an error.} +\item{options}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} This argument is not supported from igraph version 1.6.0, +as ARPACK is not used any more for solving the eigenproblem. +Supplying it raises an error.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{layout.mds()} was renamed to \code{\link[=layout_with_mds]{layout_with_mds()}} to create a more -consistent API. +\code{layout.mds()} was renamed to \code{\link[=layout_with_mds]{layout_with_mds()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Layout.html#igraph_layout_mds}{\code{layout_mds()}} diff --git a/man/layout.merge.Rd b/man/layout.merge.Rd index 14307918324..e98c89858a5 100644 --- a/man/layout.merge.Rd +++ b/man/layout.merge.Rd @@ -11,13 +11,12 @@ layout.merge(graphs, layouts, method = "dla") \item{layouts}{A list of two-column matrices.} -\item{method}{Character constant giving the method to use. Right now only -\code{dla} is implemented.} +\item{method}{Character constant giving the method to use. +Right now only \code{dla} is implemented.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{layout.merge()} was renamed to \code{\link[=merge_coords]{merge_coords()}} to create a more -consistent API. +\code{layout.merge()} was renamed to \code{\link[=merge_coords]{merge_coords()}} to create a more consistent API. } \keyword{internal} diff --git a/man/layout.norm.Rd b/man/layout.norm.Rd index 4e67feccf5c..6a504aa67ed 100644 --- a/man/layout.norm.Rd +++ b/man/layout.norm.Rd @@ -17,20 +17,18 @@ layout.norm( \arguments{ \item{layout}{A matrix with two or three columns, the layout to normalize.} -\item{xmin, xmax}{The limits for the first coordinate, if one of them or both -are \code{NULL} then no normalization is performed along this direction.} +\item{xmin, xmax}{The limits for the first coordinate, +if one of them or both are \code{NULL} then no normalization is performed along this direction.} -\item{ymin, ymax}{The limits for the second coordinate, if one of them or -both are \code{NULL} then no normalization is performed along this -direction.} +\item{ymin, ymax}{The limits for the second coordinate, +if one of them or both are \code{NULL} then no normalization is performed along this direction.} -\item{zmin, zmax}{The limits for the third coordinate, if one of them or both -are \code{NULL} then no normalization is performed along this direction.} +\item{zmin, zmax}{The limits for the third coordinate, +if one of them or both are \code{NULL} then no normalization is performed along this direction.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{layout.norm()} was renamed to \code{\link[=norm_coords]{norm_coords()}} to create a more -consistent API. +\code{layout.norm()} was renamed to \code{\link[=norm_coords]{norm_coords()}} to create a more consistent API. } \keyword{internal} diff --git a/man/layout.random.Rd b/man/layout.random.Rd index d7564f6484e..946803c3533 100644 --- a/man/layout.random.Rd +++ b/man/layout.random.Rd @@ -14,7 +14,6 @@ layout.random(..., params = list()) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{layout.random()} was renamed to \code{\link[=layout_randomly]{layout_randomly()}} to create a more -consistent API. +\code{layout.random()} was renamed to \code{\link[=layout_randomly]{layout_randomly()}} to create a more consistent API. } \keyword{internal} diff --git a/man/layout.reingold.tilford.Rd b/man/layout.reingold.tilford.Rd index 45e9a22fa8d..1a6fd974d87 100644 --- a/man/layout.reingold.tilford.Rd +++ b/man/layout.reingold.tilford.Rd @@ -14,7 +14,6 @@ layout.reingold.tilford(..., params = list()) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{layout.reingold.tilford()} was renamed to \code{\link[=layout_as_tree]{layout_as_tree()}} to create a more -consistent API. +\code{layout.reingold.tilford()} was renamed to \code{\link[=layout_as_tree]{layout_as_tree()}} to create a more consistent API. } \keyword{internal} diff --git a/man/layout.sphere.Rd b/man/layout.sphere.Rd index cf542f4419d..5cd7035c3af 100644 --- a/man/layout.sphere.Rd +++ b/man/layout.sphere.Rd @@ -14,7 +14,6 @@ layout.sphere(..., params = list()) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{layout.sphere()} was renamed to \code{\link[=layout_on_sphere]{layout_on_sphere()}} to create a more -consistent API. +\code{layout.sphere()} was renamed to \code{\link[=layout_on_sphere]{layout_on_sphere()}} to create a more consistent API. } \keyword{internal} diff --git a/man/layout.star.Rd b/man/layout.star.Rd index 7cb3fbf768f..adee115aa05 100644 --- a/man/layout.star.Rd +++ b/man/layout.star.Rd @@ -9,8 +9,8 @@ layout.star(graph, center = V(graph)[1], order = NULL) \arguments{ \item{graph}{The graph to layout.} -\item{center}{The ID of the vertex to put in the center. The default -\code{NULL} uses the first vertex.} +\item{center}{The ID of the vertex to put in the center. +The default \code{NULL} uses the first vertex.} \item{order}{Numeric vector, the order of the vertices along the perimeter. The default ordering is given by the vertex IDs.} @@ -18,8 +18,7 @@ The default ordering is given by the vertex IDs.} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{layout.star()} was renamed to \code{\link[=layout_as_star]{layout_as_star()}} to create a more -consistent API. +\code{layout.star()} was renamed to \code{\link[=layout_as_star]{layout_as_star()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Layout.html#igraph_layout_star}{\code{layout_star()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Layout.html#igraph_layout_circle}{\code{layout_circle()}} diff --git a/man/layout.sugiyama.Rd b/man/layout.sugiyama.Rd index 3bf2aa46b08..eedbee60251 100644 --- a/man/layout.sugiyama.Rd +++ b/man/layout.sugiyama.Rd @@ -21,33 +21,27 @@ layout.sugiyama( Layers are numbered from one. Default: \code{NULL}, igraph calculates the layers automatically.} -\item{hgap}{Real scalar, the minimum horizontal gap between vertices in the -same layer.} +\item{hgap}{Real scalar, the minimum horizontal gap between vertices in the same layer.} \item{vgap}{Real scalar, the distance between layers.} -\item{maxiter}{Integer scalar, the maximum number of iterations in the -crossing minimization stage. 100 is a reasonable default; if you feel that -you have too many edge crossings, increase this.} - -\item{weights}{Optional edge weight vector. If \code{NULL}, then the -'weight' edge attribute is used, if there is one. Supply \code{NA} here and -igraph ignores the edge weights. These are used only if the graph -contains cycles; igraph will tend to reverse edges with smaller weights -when breaking the cycles.} - -\item{attributes}{Which graph/vertex/edge attributes to keep in the extended -graph. \sQuote{default} keeps the \sQuote{size}, \sQuote{size2}, -\sQuote{shape}, \sQuote{label} and \sQuote{color} vertex attributes and the -\sQuote{arrow.mode} and \sQuote{arrow.size} edge attributes. \sQuote{all} -keep all graph, vertex and edge attributes, \sQuote{none} keeps none of -them.} +\item{maxiter}{Integer scalar, the maximum number of iterations in the crossing minimization stage. +100 is a reasonable default; if you feel that you have too many edge crossings, increase this.} + +\item{weights}{Optional edge weight vector. +If \code{NULL}, then the 'weight' edge attribute is used, if there is one. +Supply \code{NA} here and igraph ignores the edge weights. +These are used only if the graph contains cycles; igraph will tend to reverse edges with smaller weights when breaking the cycles.} + +\item{attributes}{Which graph/vertex/edge attributes to keep in the extended graph. +\sQuote{default} keeps the \sQuote{size}, \sQuote{size2}, \sQuote{shape}, +\sQuote{label} and \sQuote{color} vertex attributes and the \sQuote{arrow.mode} and \sQuote{arrow.size} edge attributes. +\sQuote{all} keep all graph, vertex and edge attributes, \sQuote{none} keeps none of them.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{layout.sugiyama()} was renamed to \code{\link[=layout_with_sugiyama]{layout_with_sugiyama()}} to create a more -consistent API. +\code{layout.sugiyama()} was renamed to \code{\link[=layout_with_sugiyama]{layout_with_sugiyama()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Layout.html#igraph_layout_sugiyama}{\code{layout_sugiyama()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_edgelist}{\code{get_edgelist()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_is_directed}{\code{is_directed()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/layout_.Rd b/man/layout_.Rd index 756059b5064..86b6ee49a93 100644 --- a/man/layout_.Rd +++ b/man/layout_.Rd @@ -16,8 +16,8 @@ layout_(graph, layout, ...) \arguments{ \item{graph}{The input graph.} -\item{layout}{The layout specification. It must be a call -to a layout specification function.} +\item{layout}{The layout specification. +It must be a call to a layout specification function.} \item{...}{Further modifiers, see a complete list below. For the \code{\link[=print]{print()}} methods, it is ignored.} @@ -25,35 +25,29 @@ For the \code{\link[=print]{print()}} methods, it is ignored.} \item{x}{The layout specification} } \value{ -The return value of the layout function, usually a -two column matrix. For 3D layouts a three column matrix. +The return value of the layout function, usually a two column matrix. +For 3D layouts a three column matrix. } \description{ -This is a generic function to apply a layout function to -a graph. +This is a generic function to apply a layout function to a graph. } \details{ There are two ways to calculate graph layouts in igraph. -The first way is to call a layout function (they all have -prefix \code{layout_()} on a graph, to get the vertex coordinates. +The first way is to call a layout function (they all have prefix \code{layout_()} on a graph, to get the vertex coordinates. -The second way (new in igraph 0.8.0), has two steps, and it -is more flexible. First you call a layout specification -function (the one without the \code{layout_()} prefix, and -then \code{layout_()} (or \code{\link[=add_layout_]{add_layout_()}}) to -perform the layouting. +The second way (new in igraph 0.8.0), has two steps, and it is more flexible. +First you call a layout specification function (the one without the \code{layout_()} prefix, +and then \code{layout_()} (or \code{\link[=add_layout_]{add_layout_()}}) to perform the layouting. -The second way is preferred, as it is more flexible. It allows -operations before and after the layouting. E.g. using the -\code{component_wise()} argument, the layout can be calculated -separately for each component, and then merged to get the -final results. +The second way is preferred, as it is more flexible. +It allows operations before and after the layouting. +E.g. using the \code{component_wise()} argument, the layout can be calculated separately for each component, +and then merged to get the final results. } \section{Modifiers}{ Modifiers modify how a layout calculation is performed. -Modifiers are applied in the order they are specified as arguments to -\code{layout_()}. +Modifiers are applied in the order they are specified as arguments to \code{layout_()}. There are two types of modifiers: \itemize{ @@ -108,8 +102,7 @@ coords <- layout_(make_ring(10), in_circle(), scale_by(3)) plot(make_ring(10), layout = coords) } \seealso{ -\code{\link[=add_layout_]{add_layout_()}} to add the layout to the -graph as an attribute. +\code{\link[=add_layout_]{add_layout_()}} to add the layout to the graph as an attribute. Other graph layouts: \code{\link[=add_layout_]{add_layout_()}}, diff --git a/man/layout_as_bipartite.Rd b/man/layout_as_bipartite.Rd index 83158b03597..d19123652b8 100644 --- a/man/layout_as_bipartite.Rd +++ b/man/layout_as_bipartite.Rd @@ -14,38 +14,30 @@ layout_as_bipartite( ) } \arguments{ -\item{graph}{The bipartite input graph. It should have a logical -\sQuote{\code{type}} vertex attribute, or the \code{types} argument must be -given.} +\item{graph}{The bipartite input graph. +It should have a logical \sQuote{\code{type}} vertex attribute, or the \code{types} argument must be given.} -\item{types}{A logical vector, the vertex types. If this argument is -\code{NULL} (the default), then the \sQuote{\code{type}} vertex attribute is -used.} +\item{types}{A logical vector, the vertex types. +If this argument is \code{NULL} (the default), then the \sQuote{\code{type}} vertex attribute is used.} \item{...}{These dots are for future extensions and must be empty.} -\item{hgap}{Real scalar, the minimum horizontal gap between vertices in the -same layer.} +\item{hgap}{Real scalar, the minimum horizontal gap between vertices in the same layer.} \item{vgap}{Real scalar, the distance between the two layers.} -\item{maxiter}{Integer scalar, the maximum number of iterations in the -crossing minimization stage. 100 is a reasonable default; if you feel that -you have too many edge crossings, increase this.} +\item{maxiter}{Integer scalar, the maximum number of iterations in the crossing minimization stage. +100 is a reasonable default; if you feel that you have too many edge crossings, increase this.} } \value{ -A matrix with two columns and as many rows as the number of vertices -in the input graph. +A matrix with two columns and as many rows as the number of vertices in the input graph. } \description{ -Minimize edge-crossings in a simple two-row (or column) layout for bipartite -graphs. +Minimize edge-crossings in a simple two-row (or column) layout for bipartite graphs. } \details{ -The layout is created by first placing the vertices in two rows, according -to their types. Then the positions within the rows are optimized to minimize -edge crossings, using the Sugiyama algorithm (see -\code{\link[=layout_with_sugiyama]{layout_with_sugiyama()}}). +The layout is created by first placing the vertices in two rows, according to their types. +Then the positions within the rows are optimized to minimize edge crossings, using the Sugiyama algorithm (see \code{\link[=layout_with_sugiyama]{layout_with_sugiyama()}}). } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Layout.html#igraph_layout_bipartite}{\code{layout_bipartite()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} @@ -66,8 +58,8 @@ g \%>\% plot() } \seealso{ -\code{\link[=layout_with_sugiyama]{layout_with_sugiyama()}}. See \code{\link[=as_bipartite]{as_bipartite()}} to build a lazy -layout specification for \code{\link[=add_layout_]{add_layout_()}}. +\code{\link[=layout_with_sugiyama]{layout_with_sugiyama()}}. +See \code{\link[=as_bipartite]{as_bipartite()}} to build a lazy layout specification for \code{\link[=add_layout_]{add_layout_()}}. Other graph layouts: \code{\link[=add_layout_]{add_layout_()}}, diff --git a/man/layout_as_star.Rd b/man/layout_as_star.Rd index 7c0dcb06d58..c8922cab6c9 100644 --- a/man/layout_as_star.Rd +++ b/man/layout_as_star.Rd @@ -11,23 +11,20 @@ layout_as_star(graph, ..., center = NULL, order = NULL) \item{...}{These dots are for future extensions and must be empty.} -\item{center}{The ID of the vertex to put in the center. The default -\code{NULL} uses the first vertex.} +\item{center}{The ID of the vertex to put in the center. +The default \code{NULL} uses the first vertex.} \item{order}{Numeric vector, the order of the vertices along the perimeter. The default ordering is given by the vertex IDs.} } \value{ -A matrix with two columns and as many rows as the number of vertices -in the input graph. +A matrix with two columns and as many rows as the number of vertices in the input graph. } \description{ -A simple layout generator, that places one vertex in the center of a circle -and the rest of the vertices equidistantly on the perimeter. +A simple layout generator, that places one vertex in the center of a circle and the rest of the vertices equidistantly on the perimeter. } \details{ -It is possible to choose the vertex that will be in the center, and the -order of the vertices can be also given. +It is possible to choose the vertex that will be in the center, and the order of the vertices can be also given. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Layout.html#igraph_layout_star}{\code{layout_star()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Layout.html#igraph_layout_circle}{\code{layout_circle()}} @@ -42,10 +39,9 @@ layout_as_star(g) layout_(g, as_star()) } \seealso{ -\code{\link[=layout]{layout()}} and \code{\link[=layout_with_drl]{layout_with_drl()}} for other layout -algorithms, \code{\link[=plot.igraph]{plot.igraph()}} and \code{\link[=tkplot]{tkplot()}} on how to -plot graphs and \code{\link[=star]{star()}} on how to create ring graphs. See \code{\link[=as_star]{as_star()}} to -build a lazy layout specification for \code{\link[=add_layout_]{add_layout_()}}. +\code{\link[=layout]{layout()}} and \code{\link[=layout_with_drl]{layout_with_drl()}} for other layout algorithms, +\code{\link[=plot.igraph]{plot.igraph()}} and \code{\link[=tkplot]{tkplot()}} on how to plot graphs and \code{\link[=star]{star()}} on how to create ring graphs. +See \code{\link[=as_star]{as_star()}} to build a lazy layout specification for \code{\link[=add_layout_]{add_layout_()}}. Other graph layouts: \code{\link[=add_layout_]{add_layout_()}}, diff --git a/man/layout_as_tree.Rd b/man/layout_as_tree.Rd index e5251f93f2a..aacb428913f 100644 --- a/man/layout_as_tree.Rd +++ b/man/layout_as_tree.Rd @@ -19,29 +19,28 @@ layout_as_tree( \item{...}{These dots are for future extensions and must be empty.} -\item{root}{The index of the root vertex or root vertices. If this is a -non-empty vector then the supplied vertex IDs are used as the roots of the -trees (or a single tree if the graph is connected). If it is an empty -vector, then the root vertices are automatically calculated based on -topological sorting, performed with the opposite mode than the \code{mode} -argument. After the vertices have been sorted, one is selected from each -component.} +\item{root}{The index of the root vertex or root vertices. +If this is a non-empty vector then the supplied vertex IDs are used as the roots of the trees +(or a single tree if the graph is connected). +If it is an empty vector, +then the root vertices are automatically calculated based on topological sorting, +performed with the opposite mode than the \code{mode} argument. +After the vertices have been sorted, one is selected from each component.} -\item{circular}{Logical, whether to plot the tree in a circular -fashion. Defaults to \code{FALSE}, so the tree branches are going bottom-up -(or top-down, see the \code{flip.y} argument.} +\item{circular}{Logical, whether to plot the tree in a circular fashion. +Defaults to \code{FALSE}, so the tree branches are going bottom-up (or top-down, see the \code{flip.y} argument.} -\item{rootlevel}{This argument can be useful when drawing forests which are -not trees (i.e. they are unconnected and have tree components). It specifies -the level of the root vertices for every tree in the forest. It is only -considered if the \code{roots} argument is not an empty vector.} +\item{rootlevel}{This argument can be useful when drawing forests +which are not trees (i.e. they are unconnected and have tree components). +It specifies the level of the root vertices for every tree in the forest. +It is only considered if the \code{roots} argument is not an empty vector.} -\item{mode}{Specifies which edges to consider when building the tree. If it -is \sQuote{out}, then only the outgoing, if it is \sQuote{in}, then only the -incoming edges of a parent are considered. If it is \sQuote{all} then all -edges are used (this was the behavior in igraph 0.5 and before). This -parameter also influences how the root vertices are calculated, if they are -not given. See the \code{roots} parameter.} +\item{mode}{Specifies which edges to consider when building the tree. +If it is \sQuote{out}, then only the outgoing, +if it is \sQuote{in}, then only the incoming edges of a parent are considered. +If it is \sQuote{all} then all edges are used (this was the behavior in igraph 0.5 and before). +This parameter also influences how the root vertices are calculated, if they are not given. +See the \code{roots} parameter.} \item{flip.y}{Logical, whether to flip the \sQuote{y} coordinates. The default is flipping because that puts the root vertex on the top.} @@ -50,16 +49,14 @@ The default is flipping because that puts the root vertex on the top.} A numeric matrix with two columns, and one row for each vertex. } \description{ -A tree-like layout, it is perfect for trees, acceptable for graphs with not -too many cycles. +A tree-like layout, it is perfect for trees, acceptable for graphs with not too many cycles. } \details{ -Arranges the nodes in a tree where the given node is used as the root. The -tree is directed downwards and the parents are centered above its children. +Arranges the nodes in a tree where the given node is used as the root. +The tree is directed downwards and the parents are centered above its children. For the exact algorithm, the reference below. -If the given graph is not a tree, a breadth-first search is executed first -to obtain a possible spanning tree. +If the given graph is not a tree, a breadth-first search is executed first to obtain a possible spanning tree. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} @@ -84,8 +81,7 @@ Reingold, E and Tilford, J (1981). Tidier drawing of trees. \emph{IEEE Trans. on Softw. Eng.}, SE-7(2):223--228. } \seealso{ -\code{\link[=as_tree]{as_tree()}} to build a lazy layout specification for -\code{\link[=add_layout_]{add_layout_()}}. +\code{\link[=as_tree]{as_tree()}} to build a lazy layout specification for \code{\link[=add_layout_]{add_layout_()}}. Other graph layouts: \code{\link[=add_layout_]{add_layout_()}}, diff --git a/man/layout_in_circle.Rd b/man/layout_in_circle.Rd index 0a6326ce01d..c892fabc0e1 100644 --- a/man/layout_in_circle.Rd +++ b/man/layout_in_circle.Rd @@ -9,10 +9,9 @@ layout_in_circle(graph, order = NULL) \arguments{ \item{graph}{The input graph.} -\item{order}{The vertices to place on the circle, in the order of their -desired placement. Vertices that are not included here will be placed at -(0,0). The default \code{NULL} selects all vertices, in the order of their -IDs.} +\item{order}{The vertices to place on the circle, in the order of their desired placement. +Vertices that are not included here will be placed at (0,0). +The default \code{NULL} selects all vertices, in the order of their IDs.} } \value{ A numeric matrix with two columns, and one row for each vertex. @@ -21,8 +20,7 @@ A numeric matrix with two columns, and one row for each vertex. Place vertices on a circle, in the order of their vertex IDs. } \details{ -If you want to order the vertices differently, then permute them using the -\code{\link[=permute]{permute()}} function. +If you want to order the vertices differently, then permute them using the \code{\link[=permute]{permute()}} function. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Layout.html#igraph_layout_circle}{\code{layout_circle()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} @@ -47,8 +45,7 @@ plot(karate, layout = coords) \dontshow{\}) # examplesIf} } \seealso{ -\code{\link[=in_circle]{in_circle()}} to build a lazy layout specification for -\code{\link[=add_layout_]{add_layout_()}}. +\code{\link[=in_circle]{in_circle()}} to build a lazy layout specification for \code{\link[=add_layout_]{add_layout_()}}. Other graph layouts: \code{\link[=add_layout_]{add_layout_()}}, diff --git a/man/layout_modifier.Rd b/man/layout_modifier.Rd index f77c80d5b96..b108e847aff 100644 --- a/man/layout_modifier.Rd +++ b/man/layout_modifier.Rd @@ -7,7 +7,8 @@ layout_modifier(...) } \arguments{ -\item{...}{Named arguments that define the modifier. Must include: +\item{...}{Named arguments that define the modifier. +Must include: \describe{ \item{ID}{A unique identifier string for the modifier} \item{type}{Either \code{"pre"} for pre-layout or \code{"post"} for post-layout} @@ -21,8 +22,7 @@ An object of class \code{igraph_layout_modifier}. } \description{ This is a constructor function for creating custom layout modifiers. -Layout modifiers can be used with \code{\link[=layout_]{layout_()}} to modify how layouts -are calculated or to transform the resulting coordinates. +Layout modifiers can be used with \code{\link[=layout_]{layout_()}} to modify how layouts are calculated or to transform the resulting coordinates. } \examples{ # Create a custom post-layout modifier that scales coordinates @@ -43,8 +43,7 @@ coords <- layout_(g, in_circle(), scale_by(2)) plot(g, layout = coords) } \seealso{ -\code{\link[=layout_]{layout_()}} for using modifiers, \code{\link[=component_wise]{component_wise()}}, \code{\link[=normalize]{normalize()}} -for examples of built-in modifiers. +\code{\link[=layout_]{layout_()}} for using modifiers, \code{\link[=component_wise]{component_wise()}}, \code{\link[=normalize]{normalize()}} for examples of built-in modifiers. Other layout modifiers: \code{\link[=component_wise]{component_wise()}}, diff --git a/man/layout_nicely.Rd b/man/layout_nicely.Rd index 47a723f87ed..41e1b4c008e 100644 --- a/man/layout_nicely.Rd +++ b/man/layout_nicely.Rd @@ -11,20 +11,18 @@ layout_nicely(graph, dim = 2, ...) \item{dim}{Dimensions, should be 2 or 3.} -\item{\dots}{Extra arguments are passed to the real layout function that -\code{layout_nicely()} ends up calling.} +\item{\dots}{Extra arguments are passed to the real layout function that \code{layout_nicely()} ends up calling.} } \value{ A numeric matrix with two or three columns. } \description{ -This function tries to choose an appropriate graph layout algorithm for the -graph, automatically, based on a simple algorithm. See details below. +This function tries to choose an appropriate graph layout algorithm for the graph, automatically, based on a simple algorithm. +See details below. } \details{ -\code{layout_nicely()} tries to choose an appropriate layout function for the -supplied graph, and uses that to generate the layout. The current -implementation works like this: +\code{layout_nicely()} tries to choose an appropriate layout function for the supplied graph, and uses that to generate the layout. +The current implementation works like this: \enumerate{ \item If the graph has a graph attribute called \sQuote{layout}, then this is used. If this attribute is an R function, then it is called, with the graph and any other extra arguments. @@ -40,27 +38,25 @@ if the graph is connected and has less than 1000 vertices, the Fruchterman-Reingold layout is used, by calling \code{layout_with_fr()}. \item Otherwise the DrL layout is used, \code{layout_with_drl()} is called. } -In layout algorithm implementations, an argument named \sQuote{weights} is -typically used to specify the weights of the edges if the layout algorithm -supports them. In this case, omitting \sQuote{weights} or setting it to -\code{NULL} will make igraph use the 'weight' edge attribute from the graph -if it is present. However, most layout algorithms do not support non-positive -weights, so \code{layout_nicely()} would fail if you simply called it on -your graph without specifying explicit weights and the weights happened to -include non-positive numbers. We strive to ensure that \code{layout_nicely()} -works out-of-the-box for most graphs, so the rule is that if you omit -\sQuote{weights} or set it to \code{NULL} and \code{layout_nicely()} would -end up calling \code{layout_with_fr()} or \code{layout_with_drl()}, we do not -forward the weights to these functions and issue a warning about this. You -can use \code{weights = NA} to silence the warning. +In layout algorithm implementations, +an argument named \sQuote{weights} is typically used to specify the weights of the edges if the layout algorithm supports them. +In this case, +omitting \sQuote{weights} or setting it to \code{NULL} will make igraph use the 'weight' edge attribute from the graph if it is present. +However, most layout algorithms do not support non-positive weights, +so \code{layout_nicely()} would fail +if you simply called it on your graph without specifying explicit weights and the weights happened to include non-positive numbers. +We strive to ensure that \code{layout_nicely()} works out-of-the-box for most graphs, +so the rule is that if you omit \sQuote{weights} or set it to \code{NULL} and \code{layout_nicely()} would end up calling \code{layout_with_fr()} or \code{layout_with_drl()}, +we do not forward the weights to these functions and issue a warning about this. +You can use \code{weights = NA} to silence the warning. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Layout.html#igraph_layout_align}{\code{layout_align()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_forest}{\code{is_forest()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} } \seealso{ -\code{\link[=plot.igraph]{plot.igraph()}}. See \code{\link[=nicely]{nicely()}} to build a lazy layout -specification for \code{\link[=add_layout_]{add_layout_()}}. +\code{\link[=plot.igraph]{plot.igraph()}}. +See \code{\link[=nicely]{nicely()}} to build a lazy layout specification for \code{\link[=add_layout_]{add_layout_()}}. Other graph layouts: \code{\link[=add_layout_]{add_layout_()}}, diff --git a/man/layout_on_grid.Rd b/man/layout_on_grid.Rd index cb1d7705aee..ba705c52fab 100644 --- a/man/layout_on_grid.Rd +++ b/man/layout_on_grid.Rd @@ -11,28 +11,26 @@ layout_on_grid(graph, ..., width = 0, height = 0, dim = 2) \item{...}{These dots are for future extensions and must be empty.} -\item{width}{The number of vertices in a single row of the grid. If this is -zero or negative, then for 2d layouts the width of the grid will be the -square root of the number of vertices in the graph, rounded up to the next -integer. Similarly, it will be the cube root for 3d layouts.} +\item{width}{The number of vertices in a single row of the grid. +If this is zero or negative, then for 2d layouts the width of the grid will be the square root of the number of vertices in the graph, +rounded up to the next integer. +Similarly, it will be the cube root for 3d layouts.} -\item{height}{The number of vertices in a single column of the grid, for -three dimensional layouts. If this is zero or negative, then it is -determinted automatically.} +\item{height}{The number of vertices in a single column of the grid, for three dimensional layouts. +If this is zero or negative, then it is determinted automatically.} -\item{dim}{Two or three. Whether to make 2d or a 3d layout.} +\item{dim}{Two or three. +Whether to make 2d or a 3d layout.} } \value{ A two-column or three-column matrix. } \description{ -This layout places vertices on a rectangular grid, in two or three -dimensions. +This layout places vertices on a rectangular grid, in two or three dimensions. } \details{ -The function places the vertices on a simple rectangular grid, one after the -other. If you want to change the order of the vertices, then see the -\code{\link[=permute]{permute()}} function. +The function places the vertices on a simple rectangular grid, one after the other. +If you want to change the order of the vertices, then see the \code{\link[=permute]{permute()}} function. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Layout.html#igraph_layout_grid_3d}{\code{layout_grid_3d()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Layout.html#igraph_layout_grid}{\code{layout_grid()}} @@ -52,8 +50,8 @@ if (interactive() && requireNamespace("rgl", quietly = TRUE)) { } } \seealso{ -\code{\link[=layout]{layout()}} for other layout generators. See \code{\link[=on_grid]{on_grid()}} to build -a lazy layout specification for \code{\link[=add_layout_]{add_layout_()}}. +\code{\link[=layout]{layout()}} for other layout generators. +See \code{\link[=on_grid]{on_grid()}} to build a lazy layout specification for \code{\link[=add_layout_]{add_layout_()}}. Other graph layouts: \code{\link[=add_layout_]{add_layout_()}}, diff --git a/man/layout_on_sphere.Rd b/man/layout_on_sphere.Rd index bcb61d7d3f0..e6ed319b018 100644 --- a/man/layout_on_sphere.Rd +++ b/man/layout_on_sphere.Rd @@ -13,24 +13,20 @@ layout_on_sphere(graph) A numeric matrix with three columns, and one row for each vertex. } \description{ -Place vertices on a sphere, approximately uniformly, in the order of their -vertex IDs. +Place vertices on a sphere, approximately uniformly, in the order of their vertex IDs. } \details{ -\code{layout_on_sphere()} places the vertices (approximately) uniformly on the -surface of a sphere, this is thus a 3d layout. It is not clear however what -\dQuote{uniformly on a sphere} means. +\code{layout_on_sphere()} places the vertices (approximately) uniformly on the surface of a sphere, this is thus a 3d layout. +It is not clear however what \dQuote{uniformly on a sphere} means. -If you want to order the vertices differently, then permute them using the -\code{\link[=permute]{permute()}} function. +If you want to order the vertices differently, then permute them using the \code{\link[=permute]{permute()}} function. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Layout.html#igraph_layout_sphere}{\code{layout_sphere()}} } \seealso{ -\code{\link[=on_sphere]{on_sphere()}} to build a lazy layout specification for -\code{\link[=add_layout_]{add_layout_()}}. +\code{\link[=on_sphere]{on_sphere()}} to build a lazy layout specification for \code{\link[=add_layout_]{add_layout_()}}. Other graph layouts: \code{\link[=add_layout_]{add_layout_()}}, diff --git a/man/layout_randomly.Rd b/man/layout_randomly.Rd index d7f4593f959..d632e4deb6f 100644 --- a/man/layout_randomly.Rd +++ b/man/layout_randomly.Rd @@ -11,28 +11,25 @@ layout_randomly(graph, ..., dim = c(2, 3)) \item{...}{These dots are for future extensions and must be empty.} -\item{dim}{Integer scalar, the dimension of the space to use. It must be 2 -or 3.} +\item{dim}{Integer scalar, the dimension of the space to use. +It must be 2 or 3.} } \value{ A numeric matrix with two or three columns. } \description{ -This function uniformly randomly places the vertices of the graph in two or -three dimensions. +This function uniformly randomly places the vertices of the graph in two or three dimensions. } \details{ -Randomly places vertices on a [-1,1] square (in 2d) or in a cube (in 3d). It -is probably a useless layout, but it can use as a starting point for other -layout generators. +Randomly places vertices on a [-1,1] square (in 2d) or in a cube (in 3d). +It is probably a useless layout, but it can use as a starting point for other layout generators. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Layout.html#igraph_layout_random_3d}{\code{layout_random_3d()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Layout.html#igraph_layout_random}{\code{layout_random()}} } \seealso{ -\code{\link[=randomly]{randomly()}} to build a lazy layout specification for -\code{\link[=add_layout_]{add_layout_()}}. +\code{\link[=randomly]{randomly()}} to build a lazy layout specification for \code{\link[=add_layout_]{add_layout_()}}. Other graph layouts: \code{\link[=add_layout_]{add_layout_()}}, diff --git a/man/layout_spec.Rd b/man/layout_spec.Rd index 0b31839626f..5d9a08b9ab4 100644 --- a/man/layout_spec.Rd +++ b/man/layout_spec.Rd @@ -61,22 +61,16 @@ with_drl(...) An object of class \code{igraph_layout_spec}. } \description{ -Each of these functions builds a lazy layout specification for the given -layout function, to be used with \code{\link[=layout_]{layout_()}} or \code{\link[=add_layout_]{add_layout_()}}. The -specification is only evaluated when the layout is actually computed, so it -can be combined with layout modifiers such as \code{\link[=component_wise]{component_wise()}} or -\code{\link[=normalize]{normalize()}}. - -\code{as_bipartite()}, \code{as_star()} and \code{as_tree()} wrap \code{\link[=layout_as_bipartite]{layout_as_bipartite()}}, -\code{\link[=layout_as_star]{layout_as_star()}} and \code{\link[=layout_as_tree]{layout_as_tree()}} respectively. \code{in_circle()}, -\code{nicely()}, \code{on_grid()}, \code{on_sphere()} and \code{randomly()} wrap -\code{\link[=layout_in_circle]{layout_in_circle()}}, \code{\link[=layout_nicely]{layout_nicely()}}, \code{\link[=layout_on_grid]{layout_on_grid()}}, -\code{\link[=layout_on_sphere]{layout_on_sphere()}} and \code{\link[=layout_randomly]{layout_randomly()}}. \code{with_dh()}, \code{with_fr()}, -\code{with_gem()}, \code{with_graphopt()}, \code{with_kk()}, \code{with_lgl()}, \code{with_mds()}, -\code{with_sugiyama()} and \code{with_drl()} wrap \code{\link[=layout_with_dh]{layout_with_dh()}}, -\code{\link[=layout_with_fr]{layout_with_fr()}}, \code{\link[=layout_with_gem]{layout_with_gem()}}, \code{\link[=layout_with_graphopt]{layout_with_graphopt()}}, -\code{\link[=layout_with_kk]{layout_with_kk()}}, \code{\link[=layout_with_lgl]{layout_with_lgl()}}, \code{\link[=layout_with_mds]{layout_with_mds()}}, -\code{\link[=layout_with_sugiyama]{layout_with_sugiyama()}} and \code{\link[=layout_with_drl]{layout_with_drl()}}. +Each of these functions builds a lazy layout specification for the given layout function, to be used with \code{\link[=layout_]{layout_()}} or \code{\link[=add_layout_]{add_layout_()}}. +The specification is only evaluated when the layout is actually computed, +so it can be combined with layout modifiers such as \code{\link[=component_wise]{component_wise()}} or \code{\link[=normalize]{normalize()}}. + +\code{as_bipartite()}, \code{as_star()} and \code{as_tree()} wrap \code{\link[=layout_as_bipartite]{layout_as_bipartite()}}, \code{\link[=layout_as_star]{layout_as_star()}} and \code{\link[=layout_as_tree]{layout_as_tree()}} respectively. +\code{in_circle()}, \code{nicely()}, \code{on_grid()}, \code{on_sphere()} and \code{randomly()} wrap \code{\link[=layout_in_circle]{layout_in_circle()}}, \code{\link[=layout_nicely]{layout_nicely()}}, \code{\link[=layout_on_grid]{layout_on_grid()}}, +\code{\link[=layout_on_sphere]{layout_on_sphere()}} and \code{\link[=layout_randomly]{layout_randomly()}}. +\code{with_dh()}, \code{with_fr()}, \code{with_gem()}, \code{with_graphopt()}, \code{with_kk()}, \code{with_lgl()}, \code{with_mds()}, +\code{with_sugiyama()} and \code{with_drl()} wrap \code{\link[=layout_with_dh]{layout_with_dh()}}, \code{\link[=layout_with_fr]{layout_with_fr()}}, \code{\link[=layout_with_gem]{layout_with_gem()}}, \code{\link[=layout_with_graphopt]{layout_with_graphopt()}}, +\code{\link[=layout_with_kk]{layout_with_kk()}}, \code{\link[=layout_with_lgl]{layout_with_lgl()}}, \code{\link[=layout_with_mds]{layout_with_mds()}}, \code{\link[=layout_with_sugiyama]{layout_with_sugiyama()}} and \code{\link[=layout_with_drl]{layout_with_drl()}}. } \examples{ g <- make_ring(10) @@ -95,8 +89,7 @@ layout_(make_star(10), as_star(center = 5)) layout_(make_ring(10) + make_ring(5), with_fr(), component_wise()) } \seealso{ -\code{\link[=layout_]{layout_()}} and \code{\link[=add_layout_]{add_layout_()}} to apply a layout specification -to a graph. +\code{\link[=layout_]{layout_()}} and \code{\link[=add_layout_]{add_layout_()}} to apply a layout specification to a graph. } \concept{layout specifications} \keyword{graphs} diff --git a/man/layout_with_dh.Rd b/man/layout_with_dh.Rd index 3b7f56da3ce..7217876157a 100644 --- a/man/layout_with_dh.Rd +++ b/man/layout_with_dh.Rd @@ -19,42 +19,37 @@ layout_with_dh( ) } \arguments{ -\item{graph}{The graph to lay out. Edge directions are ignored.} +\item{graph}{The graph to lay out. +Edge directions are ignored.} \item{...}{These dots are for future extensions and must be empty.} -\item{coords}{Optional starting positions for the vertices. If this argument -is not \code{NULL} then it should be an appropriate matrix of starting -coordinates.} +\item{coords}{Optional starting positions for the vertices. +If this argument is not \code{NULL} then it should be an appropriate matrix of starting coordinates.} \item{maxiter}{Number of iterations to perform in the first phase.} -\item{fineiter}{Number of iterations in the fine tuning phase. The -default \code{NULL} uses \code{max(10, log2(vcount(graph)))}.} +\item{fineiter}{Number of iterations in the fine tuning phase. +The default \code{NULL} uses \code{max(10, log2(vcount(graph)))}.} \item{cool.fact}{Cooling factor.} -\item{weight.node.dist}{Weight for the node-node distances component of the -energy function.} +\item{weight.node.dist}{Weight for the node-node distances component of the energy function.} -\item{weight.border}{Weight for the distance from the border component of -the energy function. It can be set to zero, if vertices are allowed to sit -on the border.} +\item{weight.border}{Weight for the distance from the border component of the energy function. +It can be set to zero, if vertices are allowed to sit on the border.} -\item{weight.edge.lengths}{Weight for the edge length component of the -energy function. The default \code{NULL} uses \code{edge_density(graph) / 10}.} +\item{weight.edge.lengths}{Weight for the edge length component of the energy function. +The default \code{NULL} uses \code{edge_density(graph) / 10}.} -\item{weight.edge.crossings}{Weight for the edge crossing component of the -energy function. The default \code{NULL} uses -\code{1 - sqrt(edge_density(graph))}.} +\item{weight.edge.crossings}{Weight for the edge crossing component of the energy function. +The default \code{NULL} uses \code{1 - sqrt(edge_density(graph))}.} -\item{weight.node.edge.dist}{Weight for the node-edge distance component of -the energy function. The default \code{NULL} uses -\code{0.2 * (1 - edge_density(graph))}.} +\item{weight.node.edge.dist}{Weight for the node-edge distance component of the energy function. +The default \code{NULL} uses \code{0.2 * (1 - edge_density(graph))}.} } \value{ -A matrix with two columns, containing the x and y coordinates -of the vertices: +A matrix with two columns, containing the x and y coordinates of the vertices: \describe{ \item{x}{ The x-coordinate of the vertex. @@ -65,25 +60,22 @@ The y-coordinate of the vertex. } } \description{ -Place vertices of a graph on the plane, according to the simulated annealing -algorithm by Davidson and Harel. +Place vertices of a graph on the plane, according to the simulated annealing algorithm by Davidson and Harel. } \details{ -This function implements the algorithm by Davidson and Harel, see Ron -Davidson, David Harel: Drawing Graphs Nicely Using Simulated Annealing. ACM -Transactions on Graphics 15(4), pp. 301-331, 1996. +This function implements the algorithm by Davidson and Harel, see Ron Davidson, David Harel: +Drawing Graphs Nicely Using Simulated Annealing. +ACM Transactions on Graphics 15(4), pp. 301-331, 1996. The algorithm uses simulated annealing and a sophisticated energy function, -which is unfortunately hard to parameterize for different graphs. The -original publication did not disclose any parameter values, and the ones -below were determined by experimentation. +which is unfortunately hard to parameterize for different graphs. +The original publication did not disclose any parameter values, and the ones below were determined by experimentation. -The algorithm consists of two phases, an annealing phase, and a fine-tuning -phase. There is no simulated annealing in the second phase. +The algorithm consists of two phases, an annealing phase, and a fine-tuning phase. +There is no simulated annealing in the second phase. -Our implementation tries to follow the original publication, as much as -possible. The only major difference is that coordinates are explicitly kept -within the bounds of the rectangle of the layout. +Our implementation tries to follow the original publication, as much as possible. +The only major difference is that coordinates are explicitly kept within the bounds of the rectangle of the layout. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Layout.html#igraph_layout_davidson_harel}{\code{layout_davidson_harel()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_density}{\code{density()}} @@ -149,9 +141,8 @@ Ron Davidson, David Harel: Drawing Graphs Nicely Using Simulated Annealing. \emph{ACM Transactions on Graphics} 15(4), pp. 301-331, 1996. } \seealso{ -\code{\link[=layout_with_fr]{layout_with_fr()}}, -\code{\link[=layout_with_kk]{layout_with_kk()}} for other layout algorithms. See \code{\link[=with_dh]{with_dh()}} to build a -lazy layout specification for \code{\link[=add_layout_]{add_layout_()}}. +\code{\link[=layout_with_fr]{layout_with_fr()}}, \code{\link[=layout_with_kk]{layout_with_kk()}} for other layout algorithms. +See \code{\link[=with_dh]{with_dh()}} to build a lazy layout specification for \code{\link[=add_layout_]{add_layout_()}}. Other graph layouts: \code{\link[=add_layout_]{add_layout_()}}, diff --git a/man/layout_with_drl.Rd b/man/layout_with_drl.Rd index 4bac53d7f2c..66db0c5bf57 100644 --- a/man/layout_with_drl.Rd +++ b/man/layout_with_drl.Rd @@ -25,36 +25,32 @@ layout_with_drl( \item{...}{These dots are for future extensions and must be empty.} -\item{use.seed}{Logical, whether to use the coordinates given in the -\code{seed} argument as a starting point.} +\item{use.seed}{Logical, whether to use the coordinates given in the \code{seed} argument as a starting point.} -\item{seed}{A matrix with two columns, the starting coordinates for the -vertices is \code{use.seed} is \code{TRUE}. It is ignored otherwise. The default -\code{NULL} draws uniformly random starting coordinates.} +\item{seed}{A matrix with two columns, the starting coordinates for the vertices is \code{use.seed} is \code{TRUE}. +It is ignored otherwise. +The default \code{NULL} draws uniformly random starting coordinates.} -\item{options}{Options for the layout generator, a named list. See details -below. The default \code{NULL} uses \code{drl_defaults$default}.} +\item{options}{Options for the layout generator, a named list. +See details below. +The default \code{NULL} uses \code{drl_defaults$default}.} -\item{weights}{The weights of the edges. It must be a positive numeric vector, -\code{NULL} or \code{NA}. If it is \code{NULL} and the input graph has a -\sQuote{weight} edge attribute, then that attribute will be used. If -\code{NULL} and no such attribute is present, then the edges will have equal -weights. Set this to \code{NA} if the graph was a \sQuote{weight} edge -attribute, but you don't want to use it for the layout. Larger edge weights -correspond to stronger connections.} +\item{weights}{The weights of the edges. +It must be a positive numeric vector, \code{NULL} or \code{NA}. +If it is \code{NULL} and the input graph has a \sQuote{weight} edge attribute, then that attribute will be used. +If \code{NULL} and no such attribute is present, then the edges will have equal weights. +Set this to \code{NA} if the graph was a \sQuote{weight} edge attribute, but you don't want to use it for the layout. +Larger edge weights correspond to stronger connections.} -\item{dim}{Either \sQuote{2} or \sQuote{3}, it specifies whether we want a -two dimensional or a three dimensional layout. Note that because of the -nature of the DrL algorithm, the three dimensional layout takes -significantly longer to compute.} +\item{dim}{Either \sQuote{2} or \sQuote{3}, it specifies whether we want a two dimensional or a three dimensional layout. +Note that because of the nature of the DrL algorithm, the three dimensional layout takes significantly longer to compute.} } \value{ A numeric matrix with two columns. } \description{ -DrL is a force-directed graph layout toolbox focused on real-world -large-scale graphs, developed by Shawn Martin and colleagues at Sandia -National Laboratories. +DrL is a force-directed graph layout toolbox focused on real-world large-scale graphs, +developed by Shawn Martin and colleagues at Sandia National Laboratories. } \details{ This function implements the force-directed DrL layout generator. @@ -62,7 +58,9 @@ This function implements the force-directed DrL layout generator. The generator has the following parameters: \describe{ \item{edge.cut}{ -Edge cutting is done in the late stages of the algorithm in order to achieve less dense layouts. Edges are cut if there is a lot of stress on them (a large value in the objective function sum). The edge cutting parameter is a value between 0 and 1 with 0 representing no edge cutting and 1 representing maximal edge cutting. +Edge cutting is done in the late stages of the algorithm in order to achieve less dense layouts. +Edges are cut if there is a lot of stress on them (a large value in the objective function sum). +The edge cutting parameter is a value between 0 and 1 with 0 representing no edge cutting and 1 representing maximal edge cutting. } \item{init.iterations}{ Number of iterations in the first phase. @@ -138,10 +136,8 @@ Damping, simmer phase. } } -There are five pre-defined parameter settings as well, these are called -\code{drl_defaults$default}, \code{drl_defaults$coarsen}, -\code{drl_defaults$coarsest}, \code{drl_defaults$refine} and -\code{drl_defaults$final}. +There are five pre-defined parameter settings as well, these are called \code{drl_defaults$default}, \code{drl_defaults$coarsen}, +\code{drl_defaults$coarsest}, \code{drl_defaults$refine} and \code{drl_defaults$final}. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} @@ -160,8 +156,8 @@ Klavans, R., Boyack, K.W., DrL: Distributed Recursive (Graph) Layout. SAND Reports, 2008. 2936: p. 1-10. } \seealso{ -\code{\link[=layout]{layout()}} for other layout generators. See \code{\link[=with_drl]{with_drl()}} to -build a lazy layout specification for \code{\link[=add_layout_]{add_layout_()}}. +\code{\link[=layout]{layout()}} for other layout generators. +See \code{\link[=with_drl]{with_drl()}} to build a lazy layout specification for \code{\link[=add_layout_]{add_layout_()}}. } \author{ Shawn Martin (\url{https://www.cs.otago.ac.nz/homepages/smartin/}) diff --git a/man/layout_with_fr.Rd b/man/layout_with_fr.Rd index 9484491cf35..5ea21d89697 100644 --- a/man/layout_with_fr.Rd +++ b/man/layout_with_fr.Rd @@ -27,68 +27,57 @@ layout_with_fr( ) } \arguments{ -\item{graph}{The graph to lay out. Edge directions are ignored.} +\item{graph}{The graph to lay out. +Edge directions are ignored.} \item{...}{These dots are for future extensions and must be empty.} -\item{coords}{Optional starting positions for the vertices. If this argument -is not \code{NULL} then it should be an appropriate matrix of starting -coordinates.} +\item{coords}{Optional starting positions for the vertices. +If this argument is not \code{NULL} then it should be an appropriate matrix of starting coordinates.} -\item{dim}{Integer scalar, 2 or 3, the dimension of the layout. Two -dimensional layouts are places on a plane, three dimensional ones in the 3d -space.} +\item{dim}{Integer scalar, 2 or 3, the dimension of the layout. +Two dimensional layouts are places on a plane, +three dimensional ones in the 3d space.} \item{niter}{Integer scalar, the number of iterations to perform.} -\item{start.temp}{Real scalar, the start temperature. This is the maximum -amount of movement alloved along one axis, within one step, for a vertex. -Currently it is decreased linearly to zero during the iteration. The -default \code{NULL} uses \code{sqrt(vcount(graph))}.} +\item{start.temp}{Real scalar, the start temperature. +This is the maximum amount of movement alloved along one axis, within one step, for a vertex. +Currently it is decreased linearly to zero during the iteration. +The default \code{NULL} uses \code{sqrt(vcount(graph))}.} -\item{grid}{Character scalar, whether to use the faster, but less accurate -grid based implementation of the algorithm. By default (\dQuote{auto}), the -grid-based implementation is used if the graph has more than one thousand -vertices.} +\item{grid}{Character scalar, whether to use the faster, but less accurate grid based implementation of the algorithm. +By default (\dQuote{auto}), the grid-based implementation is used if the graph has more than one thousand vertices.} -\item{weights}{A vector giving edge weights. The \code{weight} edge -attribute is used by default, if present. If weights are given, then the -attraction along the edges will be multiplied by the given edge weights. -This places vertices connected with a highly weighted edge closer to -each other. Weights must be positive.} +\item{weights}{A vector giving edge weights. +The \code{weight} edge attribute is used by default, if present. +If weights are given, then the attraction along the edges will be multiplied by the given edge weights. +This places vertices connected with a highly weighted edge closer to each other. +Weights must be positive.} -\item{minx}{Numeric vector that gives lower boundaries -for the \sQuote{x} coordinates of the vertices. +\item{minx}{Numeric vector that gives lower boundaries for the \sQuote{x} coordinates of the vertices. The length of the vector must match the number of vertices in the graph. Default: \code{NULL}.} \item{maxx}{Similar to \code{minx}, but gives the upper boundaries.} -\item{miny}{Similar to \code{minx}, but gives the lower boundaries of the -\sQuote{y} coordinates.} +\item{miny}{Similar to \code{minx}, but gives the lower boundaries of the \sQuote{y} coordinates.} -\item{maxy}{Similar to \code{minx}, but gives the upper boundaries of the -\sQuote{y} coordinates.} +\item{maxy}{Similar to \code{minx}, but gives the upper boundaries of the \sQuote{y} coordinates.} -\item{minz}{Similar to \code{minx}, but gives the lower boundaries of the -\sQuote{z} coordinates.} +\item{minz}{Similar to \code{minx}, but gives the lower boundaries of the \sQuote{z} coordinates.} -\item{maxz}{Similar to \code{minx}, but gives the upper boundaries of the -\sQuote{z} coordinates.} +\item{maxz}{Similar to \code{minx}, but gives the upper boundaries of the \sQuote{z} coordinates.} -\item{coolexp, maxdelta, area, repulserad}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} These -arguments are not supported from igraph version 0.8.0 and are ignored -(with a warning).} +\item{coolexp, maxdelta, area, repulserad}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} These arguments are not supported from igraph version 0.8.0 and are ignored (with a warning).} \item{maxiter}{A deprecated synonym of \code{niter}, for compatibility.} } \value{ -A two- or three-column matrix, each row giving the coordinates of a -vertex, according to the IDs of the vertex IDs. +A two- or three-column matrix, each row giving the coordinates of a vertex, according to the IDs of the vertex IDs. } \description{ -Place vertices on the plane using the force-directed layout algorithm by -Fruchterman and Reingold. +Place vertices on the plane using the force-directed layout algorithm by Fruchterman and Reingold. } \details{ See the referenced paper below for the details of the algorithm. @@ -127,9 +116,8 @@ Force-directed Placement. \emph{Software - Practice and Experience}, 21(11):1129-1164. } \seealso{ -\code{\link[=layout_with_drl]{layout_with_drl()}}, \code{\link[=layout_with_kk]{layout_with_kk()}} for -other layout algorithms. See \code{\link[=with_fr]{with_fr()}} to build a lazy layout -specification for \code{\link[=add_layout_]{add_layout_()}}. +\code{\link[=layout_with_drl]{layout_with_drl()}}, \code{\link[=layout_with_kk]{layout_with_kk()}} for other layout algorithms. +See \code{\link[=with_fr]{with_fr()}} to build a lazy layout specification for \code{\link[=add_layout_]{add_layout_()}}. Other graph layouts: \code{\link[=add_layout_]{add_layout_()}}, diff --git a/man/layout_with_gem.Rd b/man/layout_with_gem.Rd index 9fb74e2a0fd..f59b74e60b5 100644 --- a/man/layout_with_gem.Rd +++ b/man/layout_with_gem.Rd @@ -15,7 +15,8 @@ layout_with_gem( ) } \arguments{ -\item{graph}{The input graph. Edge directions are ignored.} +\item{graph}{The input graph. +Edge directions are ignored.} \item{...}{These dots are for future extensions and must be empty.} @@ -23,24 +24,22 @@ layout_with_gem( depending on the \code{dim} argument. Default: \code{NULL}.} -\item{maxiter}{The maximum number of iterations to perform. Updating a -single vertex counts as an iteration. The default \code{NULL} uses 40 * n * n, -where n is the number of vertices. The original paper suggests 4 * n * n, -but this usually only works if the other parameters are set up carefully.} +\item{maxiter}{The maximum number of iterations to perform. +Updating a single vertex counts as an iteration. +The default \code{NULL} uses 40 * n * n, where n is the number of vertices. +The original paper suggests 4 * n * n, but this usually only works if the other parameters are set up carefully.} -\item{temp.max}{The maximum allowed local temperature. The default \code{NULL} -uses the number of vertices.} +\item{temp.max}{The maximum allowed local temperature. +The default \code{NULL} uses the number of vertices.} -\item{temp.min}{The global temperature at which the algorithm terminates -(even before reaching \code{maxiter} iterations). A reasonable default is -1/10.} +\item{temp.min}{The global temperature at which the algorithm terminates (even before reaching \code{maxiter} iterations). +A reasonable default is 1/10.} -\item{temp.init}{Initial local temperature of all vertices. The default -\code{NULL} uses the square root of the number of vertices.} +\item{temp.init}{Initial local temperature of all vertices. +The default \code{NULL} uses the square root of the number of vertices.} } \value{ -A numeric matrix with two columns, and as many rows as the number of -vertices. +A numeric matrix with two columns, and as many rows as the number of vertices. } \description{ Place vertices on the plane using the GEM force-directed layout algorithm. @@ -65,9 +64,8 @@ Layout Algorithm for Undirected Graphs, \emph{Proc. Graph Drawing 1994}, LNCS 894, pp. 388-403, 1995. } \seealso{ -\code{\link[=layout_with_fr]{layout_with_fr()}}, -\code{\link[=plot.igraph]{plot.igraph()}}, \code{\link[=tkplot]{tkplot()}}. See \code{\link[=with_gem]{with_gem()}} to build a lazy layout -specification for \code{\link[=add_layout_]{add_layout_()}}. +\code{\link[=layout_with_fr]{layout_with_fr()}}, \code{\link[=plot.igraph]{plot.igraph()}}, \code{\link[=tkplot]{tkplot()}}. +See \code{\link[=with_gem]{with_gem()}} to build a lazy layout specification for \code{\link[=add_layout_]{add_layout_()}}. Other graph layouts: \code{\link[=add_layout_]{add_layout_()}}, diff --git a/man/layout_with_graphopt.Rd b/man/layout_with_graphopt.Rd index 0d56e5ff1f5..b4ed5201080 100644 --- a/man/layout_with_graphopt.Rd +++ b/man/layout_with_graphopt.Rd @@ -21,52 +21,44 @@ layout_with_graphopt( \item{...}{These dots are for future extensions and must be empty.} -\item{start}{If given, then it should be a matrix with two columns and one -line for each vertex. This matrix will be used as starting positions for the -algorithm. If not given, then a random starting matrix is used.} +\item{start}{If given, then it should be a matrix with two columns and one line for each vertex. +This matrix will be used as starting positions for the algorithm. +If not given, then a random starting matrix is used.} -\item{niter}{Integer scalar, the number of iterations to perform. Should be -a couple of hundred in general. If you have a large graph then you might -want to only do a few iterations and then check the result. If it is not -good enough you can feed it in again in the \code{start} argument. The -default value is 500.} +\item{niter}{Integer scalar, the number of iterations to perform. +Should be a couple of hundred in general. +If you have a large graph then you might want to only do a few iterations and then check the result. +If it is not good enough you can feed it in again in the \code{start} argument. +The default value is 500.} -\item{charge}{The charge of the vertices, used to calculate electric -repulsion. The default is 0.001.} +\item{charge}{The charge of the vertices, used to calculate electric repulsion. +The default is 0.001.} -\item{mass}{The mass of the vertices, used for the spring forces. The -default is 30.} +\item{mass}{The mass of the vertices, used for the spring forces. +The default is 30.} -\item{spring.length}{The length of the springs, an integer number. The -default value is zero.} +\item{spring.length}{The length of the springs, an integer number. +The default value is zero.} \item{spring.constant}{The spring constant, the default value is one.} -\item{max.sa.movement}{Real constant, it gives the maximum amount of -movement allowed in a single step along a single axis. The default value is -5.} +\item{max.sa.movement}{Real constant, it gives the maximum amount of movement allowed in a single step along a single axis. +The default value is 5.} } \value{ A numeric matrix with two columns, and a row for each vertex. } \description{ -A force-directed layout algorithm, that scales relatively well to large -graphs. +A force-directed layout algorithm, that scales relatively well to large graphs. } \details{ -\code{layout_with_graphopt()} is a port of the graphopt layout algorithm by Michael -Schmuhl. graphopt version 0.4.1 was rewritten in C and the support for -layers was removed (might be added later) and a code was a bit reorganized -to avoid some unnecessary steps is the node charge (see below) is zero. +\code{layout_with_graphopt()} is a port of the graphopt layout algorithm by Michael Schmuhl. graphopt version 0.4.1 was rewritten in C and the support for layers was removed (might be added later) and a code was a bit reorganized to avoid some unnecessary steps is the node charge (see below) is zero. -graphopt uses physical analogies for defining attracting and repelling -forces among the vertices and then the physical system is simulated until it -reaches an equilibrium. (There is no simulated annealing or anything like -that, so a stable fixed point is not guaranteed.) +graphopt uses physical analogies for defining attracting and repelling forces among the vertices and then the physical system is simulated until it reaches an equilibrium. +(There is no simulated annealing or anything like that, so a stable fixed point is not guaranteed.) } \seealso{ -\code{\link[=with_graphopt]{with_graphopt()}} to build a lazy layout specification for -\code{\link[=add_layout_]{add_layout_()}}. +\code{\link[=with_graphopt]{with_graphopt()}} to build a lazy layout specification for \code{\link[=add_layout_]{add_layout_()}}. Other graph layouts: \code{\link[=add_layout_]{add_layout_()}}, diff --git a/man/layout_with_kk.Rd b/man/layout_with_kk.Rd index 55ad91753e5..a947cedbbb7 100644 --- a/man/layout_with_kk.Rd +++ b/man/layout_with_kk.Rd @@ -27,7 +27,8 @@ layout_with_kk( ) } \arguments{ -\item{graph}{The input graph. Edge directions are ignored.} +\item{graph}{The input graph. +Edge directions are ignored.} \item{...}{These dots are for future extensions and must be empty.} @@ -35,64 +36,53 @@ layout_with_kk( depending on the \code{dim} argument. Default: \code{NULL}.} -\item{dim}{Integer scalar, 2 or 3, the dimension of the layout. Two -dimensional layouts are places on a plane, three dimensional ones in the 3d -space.} +\item{dim}{Integer scalar, 2 or 3, the dimension of the layout. +Two dimensional layouts are places on a plane, +three dimensional ones in the 3d space.} -\item{maxiter}{The maximum number of iterations to perform. The algorithm -might terminate earlier, see the \code{epsilon} argument. The default \code{NULL} -uses \code{50 * vcount(graph)}.} +\item{maxiter}{The maximum number of iterations to perform. +The algorithm might terminate earlier, see the \code{epsilon} argument. +The default \code{NULL} uses \code{50 * vcount(graph)}.} -\item{epsilon}{Numeric scalar, the algorithm terminates, if the maximal -delta is less than this. (See the reference below for what delta means.) If -you set this to zero, then the function always performs \code{maxiter} -iterations.} +\item{epsilon}{Numeric scalar, the algorithm terminates, if the maximal delta is less than this. +(See the reference below for what delta means.) If you set this to zero, then the function always performs \code{maxiter} iterations.} \item{kkconst}{Numeric scalar, the Kamada-Kawai vertex attraction constant. The default \code{NULL} uses the number of vertices.} \item{weights}{Edge weights, larger values will result in longer edges. -Note that this is the opposite of \code{\link[=layout_with_fr]{layout_with_fr()}}, which produces -shorter edges for larger weights. Weights must be positive.} +Note that this is the opposite of \code{\link[=layout_with_fr]{layout_with_fr()}}, which produces shorter edges for larger weights. +Weights must be positive.} -\item{minx}{Numeric vector that gives lower boundaries -for the \sQuote{x} coordinates of the vertices. +\item{minx}{Numeric vector that gives lower boundaries for the \sQuote{x} coordinates of the vertices. The length of the vector must match the number of vertices in the graph. Default: \code{NULL}.} \item{maxx}{Similar to \code{minx}, but gives the upper boundaries.} -\item{miny}{Similar to \code{minx}, but gives the lower boundaries of the -\sQuote{y} coordinates.} +\item{miny}{Similar to \code{minx}, but gives the lower boundaries of the \sQuote{y} coordinates.} -\item{maxy}{Similar to \code{minx}, but gives the upper boundaries of the -\sQuote{y} coordinates.} +\item{maxy}{Similar to \code{minx}, but gives the upper boundaries of the \sQuote{y} coordinates.} -\item{minz}{Similar to \code{minx}, but gives the lower boundaries of the -\sQuote{z} coordinates.} +\item{minz}{Similar to \code{minx}, but gives the lower boundaries of the \sQuote{z} coordinates.} -\item{maxz}{Similar to \code{minx}, but gives the upper boundaries of the -\sQuote{z} coordinates.} +\item{maxz}{Similar to \code{minx}, but gives the upper boundaries of the \sQuote{z} coordinates.} -\item{niter, sigma, initemp, coolexp}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} These -arguments are not supported from igraph version 0.8.0 and are ignored (with a warning).} +\item{niter, sigma, initemp, coolexp}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} These arguments are not supported from igraph version 0.8.0 and are ignored (with a warning).} \item{start}{Deprecated synonym for \code{coords}, for compatibility.} } \value{ -A numeric matrix with two (dim=2) or three (dim=3) columns, and as -many rows as the number of vertices, the x, y and potentially z coordinates -of the vertices. +A numeric matrix with two (dim=2) or three (dim=3) columns, and as many rows as the number of vertices, the x, +y and potentially z coordinates of the vertices. } \description{ -Place the vertices on the plane, or in 3D space, based on a physical -model of springs. +Place the vertices on the plane, or in 3D space, based on a physical model of springs. } \details{ See the referenced paper below for the details of the algorithm. -This function was rewritten from scratch in igraph version 0.8.0 and it -follows truthfully the original publication by Kamada and Kawai now. +This function was rewritten from scratch in igraph version 0.8.0 and it follows truthfully the original publication by Kamada and Kawai now. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} @@ -110,9 +100,8 @@ Kamada, T. and Kawai, S.: An Algorithm for Drawing General Undirected Graphs. \emph{Information Processing Letters}, 31/1, 7--15, 1989. } \seealso{ -\code{\link[=layout_with_drl]{layout_with_drl()}}, \code{\link[=plot.igraph]{plot.igraph()}}, -\code{\link[=tkplot]{tkplot()}}. See \code{\link[=with_kk]{with_kk()}} to build a lazy layout specification for -\code{\link[=add_layout_]{add_layout_()}}. +\code{\link[=layout_with_drl]{layout_with_drl()}}, \code{\link[=plot.igraph]{plot.igraph()}}, \code{\link[=tkplot]{tkplot()}}. +See \code{\link[=with_kk]{with_kk()}} to build a lazy layout specification for \code{\link[=add_layout_]{add_layout_()}}. Other graph layouts: \code{\link[=add_layout_]{add_layout_()}}, diff --git a/man/layout_with_lgl.Rd b/man/layout_with_lgl.Rd index 3a41057a0e2..28316e50934 100644 --- a/man/layout_with_lgl.Rd +++ b/man/layout_with_lgl.Rd @@ -23,24 +23,23 @@ layout_with_lgl( \item{maxiter}{The maximum number of iterations to perform (150).} -\item{maxdelta}{The maximum change for a vertex during an iteration. The -default \code{NULL} uses the number of vertices.} +\item{maxdelta}{The maximum change for a vertex during an iteration. +The default \code{NULL} uses the number of vertices.} -\item{area}{The area of the surface on which the vertices are placed. The -default \code{NULL} uses the square of the number of vertices.} +\item{area}{The area of the surface on which the vertices are placed. +The default \code{NULL} uses the square of the number of vertices.} \item{coolexp}{The cooling exponent of the simulated annealing (1.5).} -\item{repulserad}{Cancellation radius for the repulsion. The default -\code{NULL} uses the \code{area} times the number of vertices.} +\item{repulserad}{Cancellation radius for the repulsion. +The default \code{NULL} uses the \code{area} times the number of vertices.} -\item{cellsize}{The size of the cells for the grid. When calculating the -repulsion forces between vertices only vertices in the same or neighboring -grid cells are taken into account. The default \code{NULL} uses the square -root of the square root of the \code{area}.} +\item{cellsize}{The size of the cells for the grid. +When calculating the repulsion forces between vertices only vertices in the same or neighboring grid cells are taken into account. +The default \code{NULL} uses the square root of the square root of the \code{area}.} -\item{root}{The ID of the vertex to place at the middle of the layout. The -default value is -1 which means that a random vertex is selected.} +\item{root}{The ID of the vertex to place at the middle of the layout. +The default value is -1 which means that a random vertex is selected.} } \value{ A numeric matrix with two columns and as many rows as vertices. @@ -49,17 +48,15 @@ A numeric matrix with two columns and as many rows as vertices. A layout generator for larger graphs. } \details{ -\code{layout_with_lgl()} is for large connected graphs, it is similar to the layout -generator of the Large Graph Layout software -(\url{https://lgl.sourceforge.net/}). +\code{layout_with_lgl()} is for large connected graphs, +it is similar to the layout generator of the Large Graph Layout software (\url{https://lgl.sourceforge.net/}). } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} } \seealso{ -\code{\link[=with_lgl]{with_lgl()}} to build a lazy layout specification for -\code{\link[=add_layout_]{add_layout_()}}. +\code{\link[=with_lgl]{with_lgl()}} to build a lazy layout specification for \code{\link[=add_layout_]{add_layout_()}}. Other graph layouts: \code{\link[=add_layout_]{add_layout_()}}, diff --git a/man/layout_with_mds.Rd b/man/layout_with_mds.Rd index 749ccb160d6..2c471523210 100644 --- a/man/layout_with_mds.Rd +++ b/man/layout_with_mds.Rd @@ -9,40 +9,35 @@ layout_with_mds(graph, dist = NULL, dim = 2, options = deprecated()) \arguments{ \item{graph}{The input graph.} -\item{dist}{The distance matrix for the multidimensional scaling. If -\code{NULL} (the default), then the unweighted shortest path matrix is used.} +\item{dist}{The distance matrix for the multidimensional scaling. +If \code{NULL} (the default), +then the unweighted shortest path matrix is used.} -\item{dim}{\code{layout_with_mds()} supports dimensions up to the number of nodes -minus one, but only if the graph is connected; for unconnected graphs, the -only possible value is 2. This is because \code{merge_coords()} only works in -2D.} +\item{dim}{\code{layout_with_mds()} supports dimensions up to the number of nodes minus one, but only if the graph is connected; +for unconnected graphs, the only possible value is 2. This is because \code{merge_coords()} only works in 2D.} -\item{options}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} This argument is not -supported from igraph version 1.6.0, as ARPACK is not used any more for -solving the eigenproblem. Supplying it raises an error.} +\item{options}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} This argument is not supported from igraph version 1.6.0, +as ARPACK is not used any more for solving the eigenproblem. +Supplying it raises an error.} } \value{ A numeric matrix with \code{dim} columns. } \description{ -Multidimensional scaling of some distance matrix defined on the vertices of -a graph. +Multidimensional scaling of some distance matrix defined on the vertices of a graph. } \details{ -\code{layout_with_mds()} uses classical multidimensional scaling (Torgerson scaling) -for generating the coordinates. Multidimensional scaling aims to place points -from a higher dimensional space in a (typically) 2 dimensional plane, so that -the distances between the points are kept as much as this is possible. +\code{layout_with_mds()} uses classical multidimensional scaling (Torgerson scaling) for generating the coordinates. +Multidimensional scaling aims to place points from a higher dimensional space in a (typically) 2 dimensional plane, +so that the distances between the points are kept as much as this is possible. -By default igraph uses the shortest path matrix as the distances between the -nodes, but the user can override this via the \code{dist} argument. +By default igraph uses the shortest path matrix as the distances between the nodes, +but the user can override this via the \code{dist} argument. -Warning: If the graph is symmetric to the exchange of two vertices (as is the -case with leaves of a tree connecting to the same parent), classical -multidimensional scaling may assign the same coordinates to these vertices. +Warning: If the graph is symmetric to the exchange of two vertices (as is the case with leaves of a tree connecting to the same parent), +classical multidimensional scaling may assign the same coordinates to these vertices. -This function generates the layout separately for each graph component and -then merges them via \code{\link[=merge_coords]{merge_coords()}}. +This function generates the layout separately for each graph component and then merges them via \code{\link[=merge_coords]{merge_coords()}}. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Layout.html#igraph_layout_mds}{\code{layout_mds()}} @@ -59,8 +54,8 @@ Cox, T. F. and Cox, M. A. A. (2001) \emph{Multidimensional Scaling}. Second edition. Chapman and Hall. } \seealso{ -\code{\link[=layout]{layout()}}, \code{\link[=plot.igraph]{plot.igraph()}}. See \code{\link[=with_mds]{with_mds()}} to build a lazy -layout specification for \code{\link[=add_layout_]{add_layout_()}}. +\code{\link[=layout]{layout()}}, \code{\link[=plot.igraph]{plot.igraph()}}. +See \code{\link[=with_mds]{with_mds()}} to build a lazy layout specification for \code{\link[=add_layout_]{add_layout_()}}. Other graph layouts: \code{\link[=add_layout_]{add_layout_()}}, diff --git a/man/layout_with_sugiyama.Rd b/man/layout_with_sugiyama.Rd index 11e4ecf083b..a68599ffceb 100644 --- a/man/layout_with_sugiyama.Rd +++ b/man/layout_with_sugiyama.Rd @@ -24,27 +24,22 @@ layout_with_sugiyama( Layers are numbered from one. Default: \code{NULL}, igraph calculates the layers automatically.} -\item{hgap}{Real scalar, the minimum horizontal gap between vertices in the -same layer.} +\item{hgap}{Real scalar, the minimum horizontal gap between vertices in the same layer.} \item{vgap}{Real scalar, the distance between layers.} -\item{maxiter}{Integer scalar, the maximum number of iterations in the -crossing minimization stage. 100 is a reasonable default; if you feel that -you have too many edge crossings, increase this.} +\item{maxiter}{Integer scalar, the maximum number of iterations in the crossing minimization stage. +100 is a reasonable default; if you feel that you have too many edge crossings, increase this.} -\item{weights}{Optional edge weight vector. If \code{NULL}, then the -'weight' edge attribute is used, if there is one. Supply \code{NA} here and -igraph ignores the edge weights. These are used only if the graph -contains cycles; igraph will tend to reverse edges with smaller weights -when breaking the cycles.} +\item{weights}{Optional edge weight vector. +If \code{NULL}, then the 'weight' edge attribute is used, if there is one. +Supply \code{NA} here and igraph ignores the edge weights. +These are used only if the graph contains cycles; igraph will tend to reverse edges with smaller weights when breaking the cycles.} -\item{attributes}{Which graph/vertex/edge attributes to keep in the extended -graph. \sQuote{default} keeps the \sQuote{size}, \sQuote{size2}, -\sQuote{shape}, \sQuote{label} and \sQuote{color} vertex attributes and the -\sQuote{arrow.mode} and \sQuote{arrow.size} edge attributes. \sQuote{all} -keep all graph, vertex and edge attributes, \sQuote{none} keeps none of -them.} +\item{attributes}{Which graph/vertex/edge attributes to keep in the extended graph. +\sQuote{default} keeps the \sQuote{size}, \sQuote{size2}, \sQuote{shape}, +\sQuote{label} and \sQuote{color} vertex attributes and the \sQuote{arrow.mode} and \sQuote{arrow.size} edge attributes. +\sQuote{all} keep all graph, vertex and edge attributes, \sQuote{none} keeps none of them.} } \value{ A list with the components: @@ -65,27 +60,22 @@ and it is the layout matrix for all (original and dummy) vertices. } } \description{ -Sugiyama layout algorithm for layered directed acyclic graphs. The algorithm -minimized edge crossings. +Sugiyama layout algorithm for layered directed acyclic graphs. +The algorithm minimized edge crossings. } \details{ -This layout algorithm is designed for directed acyclic graphs where each -vertex is assigned to a layer. Layers are indexed from zero, and vertices of -the same layer will be placed on the same horizontal line. The X coordinates -of vertices within each layer are decided by the heuristic proposed by -Sugiyama et al. to minimize edge crossings. +This layout algorithm is designed for directed acyclic graphs where each vertex is assigned to a layer. +Layers are indexed from zero, and vertices of the same layer will be placed on the same horizontal line. +The X coordinates of vertices within each layer are decided by the heuristic proposed by Sugiyama et al. to minimize edge crossings. -You can also try to lay out undirected graphs, graphs containing cycles, or -graphs without an a priori layered assignment with this algorithm. igraph -will try to eliminate cycles and assign vertices to layers, but there is no -guarantee on the quality of the layout in such cases. +You can also try to lay out undirected graphs, graphs containing cycles, +or graphs without an a priori layered assignment with this algorithm. igraph will try to eliminate cycles and assign vertices to layers, +but there is no guarantee on the quality of the layout in such cases. -The Sugiyama layout may introduce \dQuote{bends} on the edges in order to -obtain a visually more pleasing layout. This is achieved by adding dummy -nodes to edges spanning more than one layer. The resulting layout assigns -coordinates not only to the nodes of the original graph but also to the -dummy nodes. The layout algorithm will also return the extended graph with -the dummy nodes. +The Sugiyama layout may introduce \dQuote{bends} on the edges in order to obtain a visually more pleasing layout. +This is achieved by adding dummy nodes to edges spanning more than one layer. +The resulting layout assigns coordinates not only to the nodes of the original graph but also to the dummy nodes. +The layout algorithm will also return the extended graph with the dummy nodes. For more details, see the reference below. } @@ -240,8 +230,7 @@ Understanding of Hierarchical Systems". IEEE Transactions on Systems, Man and Cybernetics 11(2):109-125, 1981. } \seealso{ -\code{\link[=with_sugiyama]{with_sugiyama()}} to build a lazy layout specification for -\code{\link[=add_layout_]{add_layout_()}}. +\code{\link[=with_sugiyama]{with_sugiyama()}} to build a lazy layout specification for \code{\link[=add_layout_]{add_layout_()}}. Other graph layouts: \code{\link[=add_layout_]{add_layout_()}}, diff --git a/man/leading.eigenvector.community.Rd b/man/leading.eigenvector.community.Rd index 6c0891bb2f3..b16f0ba5b4a 100644 --- a/man/leading.eigenvector.community.Rd +++ b/man/leading.eigenvector.community.Rd @@ -16,28 +16,27 @@ leading.eigenvector.community( ) } \arguments{ -\item{graph}{The input graph. Should be undirected as the method needs a -symmetric matrix.} +\item{graph}{The input graph. +Should be undirected as the method needs a symmetric matrix.} -\item{steps}{The number of steps to take, this is actually the number of -tries to make a step. It is not a particularly useful parameter.} +\item{steps}{The number of steps to take, this is actually the number of tries to make a step. +It is not a particularly useful parameter.} -\item{weights}{The weights of the edges. It must be a positive numeric vector, -\code{NULL} or \code{NA}. If it is \code{NULL} and the input graph has a -\sQuote{weight} edge attribute, then that attribute will be used. If -\code{NULL} and no such attribute is present, then the edges will have equal -weights. Set this to \code{NA} if the graph was a \sQuote{weight} edge -attribute, but you don't want to use it for community detection. A larger -edge weight means a stronger connection for this function.} +\item{weights}{The weights of the edges. +It must be a positive numeric vector, \code{NULL} or \code{NA}. +If it is \code{NULL} and the input graph has a \sQuote{weight} edge attribute, then that attribute will be used. +If \code{NULL} and no such attribute is present, then the edges will have equal weights. +Set this to \code{NA} if the graph was a \sQuote{weight} edge attribute, but you don't want to use it for community detection. +A larger edge weight means a stronger connection for this function.} -\item{start}{\code{NULL}, or a numeric membership vector, giving the start -configuration of the algorithm.} +\item{start}{\code{NULL}, or a numeric membership vector, giving the start configuration of the algorithm.} \item{options}{A named list to override some ARPACK options.} -\item{callback}{Callback function. This -is called after each iteration, after calculating the leading eigenvector of -the modularity matrix. See details below. Default: \code{NULL}.} +\item{callback}{Callback function. +This is called after each iteration, after calculating the leading eigenvector of the modularity matrix. +See details below. +Default: \code{NULL}.} \item{extra}{Additional argument to supply to the callback function.} @@ -46,8 +45,7 @@ the modularity matrix. See details below. Default: \code{NULL}.} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{leading.eigenvector.community()} was renamed to \code{\link[=cluster_leading_eigen]{cluster_leading_eigen()}} to create a more -consistent API. +\code{leading.eigenvector.community()} was renamed to \code{\link[=cluster_leading_eigen]{cluster_leading_eigen()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Community.html#igraph_community_leading_eigenvector}{\code{community_leading_eigenvector()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/line.graph.Rd b/man/line.graph.Rd index e4bf1142c52..78cef85d5eb 100644 --- a/man/line.graph.Rd +++ b/man/line.graph.Rd @@ -12,8 +12,7 @@ line.graph(graph) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{line.graph()} was renamed to \code{\link[=make_line_graph]{make_line_graph()}} to create a more -consistent API. +\code{line.graph()} was renamed to \code{\link[=make_line_graph]{make_line_graph()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Operators.html#igraph_linegraph}{\code{linegraph()}} diff --git a/man/list.edge.attributes.Rd b/man/list.edge.attributes.Rd index e6475c08d37..abc3de180d0 100644 --- a/man/list.edge.attributes.Rd +++ b/man/list.edge.attributes.Rd @@ -12,7 +12,6 @@ list.edge.attributes(graph) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{list.edge.attributes()} was renamed to \code{\link[=edge_attr_names]{edge_attr_names()}} to create a more -consistent API. +\code{list.edge.attributes()} was renamed to \code{\link[=edge_attr_names]{edge_attr_names()}} to create a more consistent API. } \keyword{internal} diff --git a/man/list.graph.attributes.Rd b/man/list.graph.attributes.Rd index d156cbadcee..a9095da57dd 100644 --- a/man/list.graph.attributes.Rd +++ b/man/list.graph.attributes.Rd @@ -12,7 +12,6 @@ list.graph.attributes(graph) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{list.graph.attributes()} was renamed to \code{\link[=graph_attr_names]{graph_attr_names()}} to create a more -consistent API. +\code{list.graph.attributes()} was renamed to \code{\link[=graph_attr_names]{graph_attr_names()}} to create a more consistent API. } \keyword{internal} diff --git a/man/list.vertex.attributes.Rd b/man/list.vertex.attributes.Rd index 7c5bb9f6132..47cc1a540f9 100644 --- a/man/list.vertex.attributes.Rd +++ b/man/list.vertex.attributes.Rd @@ -12,7 +12,6 @@ list.vertex.attributes(graph) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{list.vertex.attributes()} was renamed to \code{\link[=vertex_attr_names]{vertex_attr_names()}} to create a more -consistent API. +\code{list.vertex.attributes()} was renamed to \code{\link[=vertex_attr_names]{vertex_attr_names()}} to create a more consistent API. } \keyword{internal} diff --git a/man/local_scan.Rd b/man/local_scan.Rd index 17a89226881..d7cee4a96e8 100644 --- a/man/local_scan.Rd +++ b/man/local_scan.Rd @@ -17,71 +17,57 @@ local_scan( ) } \arguments{ -\item{graph.us, graph}{An igraph object, the graph for which the scan -statistics will be computed} +\item{graph.us, graph}{An igraph object, the graph for which the scan statistics will be computed} \item{graph.them}{An igraph object on which the \sQuote{them} statistics is computed, i.e. the neighborhoods calculated from \code{graph.us} are evaluated on \code{graph.them}. Default: \code{NULL}.} -\item{k}{An integer scalar, the size of the local neighborhood for each -vertex. Should be non-negative.} +\item{k}{An integer scalar, the size of the local neighborhood for each vertex. +Should be non-negative.} -\item{FUN}{Character, a function name, or a function object itself, for -computing the local statistic in each neighborhood. If \code{NULL}(the -default value), \code{ecount()} is used for unweighted graphs (if -\code{weighted=FALSE}) and a function that computes the sum of edge -weights is used for weighted graphs (if \code{weighted=TRUE}). This -argument is ignored if \code{k} is zero.} +\item{FUN}{Character, a function name, or a function object itself, for computing the local statistic in each neighborhood. +If \code{NULL}(the default value), +\code{ecount()} is used for unweighted graphs (if \code{weighted=FALSE}) and a function that computes the sum of edge weights is used for weighted graphs (if \code{weighted=TRUE}). +This argument is ignored if \code{k} is zero.} -\item{weighted}{Logical, TRUE if the edge weights should be used -for computation of the scan statistic. If TRUE, the graph should be -weighted. Note that this argument is ignored if \code{FUN} is not -\code{NULL}, \code{"ecount"} and \code{"sumweights"}.} +\item{weighted}{Logical, TRUE if the edge weights should be used for computation of the scan statistic. +If TRUE, the graph should be weighted. +Note that this argument is ignored if \code{FUN} is not \code{NULL}, \code{"ecount"} and \code{"sumweights"}.} -\item{mode}{Character scalar, the kind of neighborhoods to use for the -calculation. One of \sQuote{\code{out}}, \sQuote{\verb{in}}, -\sQuote{\code{all}} or \sQuote{\code{total}}. This argument is ignored -for undirected graphs.} +\item{mode}{Character scalar, the kind of neighborhoods to use for the calculation. +One of \sQuote{\code{out}}, \sQuote{\verb{in}}, \sQuote{\code{all}} or \sQuote{\code{total}}. +This argument is ignored for undirected graphs.} -\item{neighborhoods}{A list of neighborhoods, one for each vertex, or -\code{NULL}. If it is not \code{NULL}, then the function is evaluated on -the induced subgraphs specified by these neighborhoods. +\item{neighborhoods}{A list of neighborhoods, one for each vertex, or \code{NULL}. +If it is not \code{NULL}, then the function is evaluated on the induced subgraphs specified by these neighborhoods. -In theory this could be useful if the same \code{graph.us} graph is used -for multiple \code{graph.them} arguments. Then the neighborhoods can be -calculated on \code{graph.us} and used with multiple graphs. In -practice, this is currently slower than simply using \code{graph.them} -multiple times.} +In theory this could be useful if the same \code{graph.us} graph is used for multiple \code{graph.them} arguments. +Then the neighborhoods can be calculated on \code{graph.us} and used with multiple graphs. +In practice, this is currently slower than simply using \code{graph.them} multiple times.} -\item{weights}{Numeric vector, edge weights to use for the scan instead of the edge attribute weight. If \code{NULL} (the default) the edge weight attribute is used.} +\item{weights}{Numeric vector, edge weights to use for the scan instead of the edge attribute weight. +If \code{NULL} (the default) the edge weight attribute is used.} -\item{\dots}{Arguments passed to \code{FUN}, the function that computes -the local statistics.} +\item{\dots}{Arguments passed to \code{FUN}, the function that computes the local statistics.} } \value{ -For \code{local_scan()} typically a numeric vector containing the -computed local statistics for each vertex. In general a list or vector -of objects, as returned by \code{FUN}. +For \code{local_scan()} typically a numeric vector containing the computed local statistics for each vertex. +In general a list or vector of objects, as returned by \code{FUN}. } \description{ -The scan statistic is a summary of the locality statistics that is -computed from the local neighborhood of each vertex. The -\code{local_scan()} function computes the local statistics for each vertex -for a given neighborhood size and the statistic function. +The scan statistic is a summary of the locality statistics that is computed from the local neighborhood of each vertex. +The \code{local_scan()} function computes the local statistics for each vertex for a given neighborhood size and the statistic function. } \details{ -See the given reference below for the details on the local scan -statistics. +See the given reference below for the details on the local scan statistics. \code{local_scan()} calculates exact local scan statistics. -If \code{graph.them} is \code{NULL}, then \code{local_scan()} computes the -\sQuote{us} variant of the scan statistics. Otherwise, -\code{graph.them} should be an igraph object and the \sQuote{them} -variant is computed using \code{graph.us} to extract the neighborhood -information, and applying \code{FUN} on these neighborhoods in -\code{graph.them}. +If \code{graph.them} is \code{NULL}, then \code{local_scan()} computes the \sQuote{us} variant of the scan statistics. +Otherwise, +\code{graph.them} should be an igraph object and the \sQuote{them} variant is computed using \code{graph.us} to extract the neighborhood information, +and applying \code{FUN} on these neighborhoods in \code{graph.them}. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_local_scan_neighborhood_ecount}{\code{local_scan_neighborhood_ecount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_local_scan_0_them}{\code{local_scan_0_them()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_local_scan_1_ecount_them}{\code{local_scan_1_ecount_them()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_local_scan_k_ecount_them}{\code{local_scan_k_ecount_them()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_local_scan_0}{\code{local_scan_0()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_local_scan_1_ecount}{\code{local_scan_1_ecount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_local_scan_k_ecount}{\code{local_scan_k_ecount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Operators.html#igraph_induced_subgraph}{\code{induced_subgraph()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/make_.Rd b/man/make_.Rd index f7f087f8ebb..94880a6a96f 100644 --- a/man/make_.Rd +++ b/man/make_.Rd @@ -18,15 +18,12 @@ For every graph constructor in igraph that has a \code{make_} prefix, there is a corresponding function without the prefix: e.g. for \code{\link[=make_ring]{make_ring()}} there is also \code{\link[=ring]{ring()}}, etc. -The same is true for the random graph samplers, i.e. for each -constructor with a \code{sample_} prefix, there is a corresponding -function without that prefix. +The same is true for the random graph samplers, i.e. for each constructor with a \code{sample_} prefix, +there is a corresponding function without that prefix. These shorter forms can be used together with \code{make_()}. -The advantage of this form is that the user can specify constructor -modifiers which work with all constructors. E.g. the -\code{\link[=with_vertex_]{with_vertex_()}} modifier adds vertex attributes -to the newly created graphs. +The advantage of this form is that the user can specify constructor modifiers which work with all constructors. +E.g. the \code{\link[=with_vertex_]{with_vertex_()}} modifier adds vertex attributes to the newly created graphs. See the examples and the various constructor modifiers below. } diff --git a/man/make_bipartite_graph.Rd b/man/make_bipartite_graph.Rd index 647e2b5d324..d7a602ad6c9 100644 --- a/man/make_bipartite_graph.Rd +++ b/man/make_bipartite_graph.Rd @@ -10,43 +10,38 @@ make_bipartite_graph(types, edges, ..., directed = FALSE) bipartite_graph(types, edges, ..., directed = FALSE) } \arguments{ -\item{types}{A vector giving the vertex types. It will be coerced into -boolean. The length of the vector gives the number of vertices in the graph. -When the vector is a named vector, the names will be attached to the graph -as the \code{name} vertex attribute.} +\item{types}{A vector giving the vertex types. +It will be coerced into boolean. +The length of the vector gives the number of vertices in the graph. +When the vector is a named vector, the names will be attached to the graph as the \code{name} vertex attribute.} -\item{edges}{A vector giving the edges of the graph, the same way as for the -regular \code{\link[=make_graph]{make_graph()}} function. It is checked that the edges indeed -connect vertices of different kind, according to the supplied \code{types} -vector. The vector may be a string vector if \code{types} is a named vector.} +\item{edges}{A vector giving the edges of the graph, the same way as for the regular \code{\link[=make_graph]{make_graph()}} function. +It is checked that the edges indeed connect vertices of different kind, according to the supplied \code{types} vector. +The vector may be a string vector if \code{types} is a named vector.} \item{...}{These dots are for future extensions and must be empty.} -\item{directed}{Logical, whether to create a directed graph. Note -that by default undirected graphs are created, as this is more common for -bipartite graphs.} +\item{directed}{Logical, whether to create a directed graph. +Note that by default undirected graphs are created, as this is more common for bipartite graphs.} } \value{ -\code{make_bipartite_graph()} returns a bipartite igraph graph. In other -words, an igraph graph that has a vertex attribute named \code{type}. +\code{make_bipartite_graph()} returns a bipartite igraph graph. +In other words, an igraph graph that has a vertex attribute named \code{type}. \code{is_bipartite()} returns a Logical. } \description{ -A bipartite graph has two kinds of vertices and connections are only allowed -between different kinds. +A bipartite graph has two kinds of vertices and connections are only allowed between different kinds. } \details{ -Bipartite graphs have a \code{type} vertex attribute in igraph, this is -boolean and \code{FALSE} for the vertices of the first kind and \code{TRUE} -for vertices of the second kind. +Bipartite graphs have a \code{type} vertex attribute in igraph, +this is boolean and \code{FALSE} for the vertices of the first kind and \code{TRUE} for vertices of the second kind. -\code{make_bipartite_graph()} basically does three things. First it checks the -\code{edges} vector against the vertex \code{types}. Then it creates a graph -using the \code{edges} vector and finally it adds the \code{types} vector as -a vertex attribute called \code{type}. \code{edges} may contain strings as -vertex names; in this case, \code{types} must be a named vector that specifies -the type for each vertex name that occurs in \code{edges}. +\code{make_bipartite_graph()} basically does three things. +First it checks the \code{edges} vector against the vertex \code{types}. +Then it creates a graph using the \code{edges} vector and finally it adds the \code{types} vector as a vertex attribute called \code{type}. +\code{edges} may contain strings as vertex names; in this case, +\code{types} must be a named vector that specifies the type for each vertex name that occurs in \code{edges}. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Bipartite.html#igraph_create_bipartite}{\code{create_bipartite()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/make_chordal_ring.Rd b/man/make_chordal_ring.Rd index 6a94ce5c8de..3b84385b43d 100644 --- a/man/make_chordal_ring.Rd +++ b/man/make_chordal_ring.Rd @@ -12,8 +12,8 @@ chordal_ring(n, w, ..., directed = FALSE) \arguments{ \item{n}{The number of vertices.} -\item{w}{A matrix which specifies the extended chordal ring. See -details below.} +\item{w}{A matrix which specifies the extended chordal ring. +See details below.} \item{...}{These dots are for future extensions and must be empty.} @@ -24,16 +24,13 @@ An igraph graph. } \description{ \code{make_chordal_ring()} creates an extended chordal ring. -An extended chordal ring is regular graph, each node has the same -degree. It can be obtained from a simple ring by adding some extra -edges specified by a matrix. Let p denote the number of columns in -the \sQuote{\code{W}} matrix. The extra edges of vertex \code{i} -are added according to column \verb{i mod p} in -\sQuote{\code{W}}. The number of extra edges is the number -of rows in \sQuote{\code{W}}: for each row \code{j} an edge -\code{i->i+w[ij]} is added if \code{i+w[ij]} is less than the number -of total nodes. See also Kotsis, G: Interconnection Topologies for -Parallel Processing Systems, PARS Mitteilungen 11, 1-6, 1993. +An extended chordal ring is regular graph, each node has the same degree. +It can be obtained from a simple ring by adding some extra edges specified by a matrix. +Let p denote the number of columns in the \sQuote{\code{W}} matrix. +The extra edges of vertex \code{i} are added according to column \verb{i mod p} in \sQuote{\code{W}}. +The number of extra edges is the number of rows in \sQuote{\code{W}}: +for each row \code{j} an edge \code{i->i+w[ij]} is added if \code{i+w[ij]} is less than the number of total nodes. +See also Kotsis, G: Interconnection Topologies for Parallel Processing Systems, PARS Mitteilungen 11, 1-6, 1993. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_extended_chordal_ring}{\code{extended_chordal_ring()}} diff --git a/man/make_circulant.Rd b/man/make_circulant.Rd index c67ad5e4543..c8f4bfdc6a9 100644 --- a/man/make_circulant.Rd +++ b/man/make_circulant.Rd @@ -22,9 +22,8 @@ circulant(n, shifts, ..., directed = FALSE) An igraph graph. } \description{ -A circulant graph \eqn{C_n^{\textrm{shifts}}} consists of \eqn{n} vertices -\eqn{v_0, \ldots, v_{n-1}} such that for each \eqn{s_i} in the list of offsets -\code{shifts}, \eqn{v_j} is connected to \eqn{v_{(j + s_i) \mod n}} for all \eqn{j}. +A circulant graph \eqn{C_n^{\textrm{shifts}}} consists of \eqn{n} vertices \eqn{v_0, \ldots, v_{n-1}} such that for each \eqn{s_i} in the list of offsets \code{shifts}, +\eqn{v_j} is connected to \eqn{v_{(j + s_i) \mod n}} for all \eqn{j}. } \details{ The function can generate either directed or undirected graphs. diff --git a/man/make_clusters.Rd b/man/make_clusters.Rd index 1a108f92226..50d6fcbe6a4 100644 --- a/man/make_clusters.Rd +++ b/man/make_clusters.Rd @@ -16,21 +16,17 @@ make_clusters( \arguments{ \item{graph}{The graph of the community structure.} -\item{membership}{The membership vector of the community structure, a -numeric vector denoting the ID of the community for each vertex. It -might be \code{NULL} for hierarchical community structures.} +\item{membership}{The membership vector of the community structure, a numeric vector denoting the ID of the community for each vertex. +It might be \code{NULL} for hierarchical community structures.} \item{...}{These dots are for future extensions and must be empty.} -\item{algorithm}{Character string, the algorithm that generated -the community structure, it can be arbitrary.} +\item{algorithm}{Character string, the algorithm that generated the community structure, it can be arbitrary.} -\item{merges}{A merge matrix, for hierarchical community structures (or -\code{NULL} otherwise.} +\item{merges}{A merge matrix, for hierarchical community structures (or \code{NULL} otherwise.} -\item{modularity}{Modularity value of the community structure. If this -is \code{TRUE} and the membership vector is available, then it the -modularity values is calculated automatically.} +\item{modularity}{Modularity value of the community structure. +If this is \code{TRUE} and the membership vector is available, then it the modularity values is calculated automatically.} } \value{ A \code{communities} object. @@ -50,8 +46,7 @@ Number of vertices in the graph. } } \description{ -This is useful to integrate the results of community finding algorithms -that are not included in igraph. +This is useful to integrate the results of community finding algorithms that are not included in igraph. } \seealso{ Community detection: diff --git a/man/make_de_bruijn_graph.Rd b/man/make_de_bruijn_graph.Rd index 4af4910b84f..56821a25a7e 100644 --- a/man/make_de_bruijn_graph.Rd +++ b/man/make_de_bruijn_graph.Rd @@ -10,9 +10,11 @@ make_de_bruijn_graph(m, n) de_bruijn_graph(m, n) } \arguments{ -\item{m}{Integer scalar, the size of the alphabet. See details below.} +\item{m}{Integer scalar, the size of the alphabet. +See details below.} -\item{n}{Integer scalar, the length of the labels. See details below.} +\item{n}{Integer scalar, the length of the labels. +See details below.} } \value{ A graph object. @@ -21,19 +23,15 @@ A graph object. De Bruijn graphs are labeled graphs representing the overlap of strings. } \details{ -A de Bruijn graph represents relationships between strings. An alphabet of -\code{m} letters are used and strings of length \code{n} are considered. A -vertex corresponds to every possible string and there is a directed edge -from vertex \code{v} to vertex \code{w} if the string of \code{v} can be -transformed into the string of \code{w} by removing its first letter and -appending a letter to it. +A de Bruijn graph represents relationships between strings. +An alphabet of \code{m} letters are used and strings of length \code{n} are considered. +A vertex corresponds to every possible string and there is a directed edge from vertex \code{v} to vertex \code{w} +if the string of \code{v} can be transformed into the string of \code{w} by removing its first letter and appending a letter to it. -Please note that the graph will have \code{m} to the power \code{n} vertices -and even more edges, so probably you don't want to supply too big numbers -for \code{m} and \code{n}. +Please note that the graph will have \code{m} to the power \code{n} vertices and even more edges, +so probably you don't want to supply too big numbers for \code{m} and \code{n}. -De Bruijn graphs have some interesting properties, please see another -source, e.g. Wikipedia for details. +De Bruijn graphs have some interesting properties, please see another source, e.g. Wikipedia for details. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_de_bruijn}{\code{de_bruijn()}} diff --git a/man/make_from_prufer.Rd b/man/make_from_prufer.Rd index 0bb8c8aed16..019e7a3cf3a 100644 --- a/man/make_from_prufer.Rd +++ b/man/make_from_prufer.Rd @@ -16,15 +16,13 @@ from_prufer(prufer) A graph object. } \description{ -\code{make_from_prufer()} creates an undirected tree graph from its Prüfer -sequence. +\code{make_from_prufer()} creates an undirected tree graph from its Prüfer sequence. } \details{ -The Prüfer sequence of a tree graph with n labeled vertices is a sequence of -n-2 numbers, constructed as follows. If the graph has more than two vertices, -find a vertex with degree one, remove it from the tree and add the label of -the vertex that it was connected to to the sequence. Repeat until there are -only two vertices in the remaining graph. +The Prüfer sequence of a tree graph with n labeled vertices is a sequence of n-2 numbers, constructed as follows. +If the graph has more than two vertices, find a vertex with degree one, +remove it from the tree and add the label of the vertex that it was connected to to the sequence. +Repeat until there are only two vertices in the remaining graph. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_from_prufer}{\code{from_prufer()}} diff --git a/man/make_full_bipartite_graph.Rd b/man/make_full_bipartite_graph.Rd index d726e238e97..3b15e3f7e37 100644 --- a/man/make_full_bipartite_graph.Rd +++ b/man/make_full_bipartite_graph.Rd @@ -31,22 +31,20 @@ full_bipartite_graph( \item{directed}{Logical, whether the graphs is directed.} \item{mode}{Scalar giving the kind of edges to create for directed graphs. -If this is \sQuote{\code{out}} then all vertices of the first kind are -connected to the others; \sQuote{\verb{in}} specifies the opposite -direction; \sQuote{\code{all}} creates mutual edges. This argument is -ignored for undirected graphs.x} +If this is \sQuote{\code{out}} then all vertices of the first kind are connected to the others; +\sQuote{\verb{in}} specifies the opposite direction; \sQuote{\code{all}} creates mutual edges. +This argument is ignored for undirected graphs.x} } \value{ An igraph graph, with the \sQuote{\code{type}} vertex attribute set. } \description{ -Bipartite graphs are also called two-mode by some. This function creates a -bipartite graph in which every possible edge is present. +Bipartite graphs are also called two-mode by some. +This function creates a bipartite graph in which every possible edge is present. } \details{ Bipartite graphs have a \sQuote{\code{type}} vertex attribute in igraph, -this is boolean and \code{FALSE} for the vertices of the first kind and -\code{TRUE} for vertices of the second kind. +this is boolean and \code{FALSE} for the vertices of the first kind and \code{TRUE} for vertices of the second kind. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Bipartite.html#igraph_full_bipartite}{\code{full_bipartite()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/make_full_citation_graph.Rd b/man/make_full_citation_graph.Rd index 76b86a7488e..692be8ab128 100644 --- a/man/make_full_citation_graph.Rd +++ b/man/make_full_citation_graph.Rd @@ -20,9 +20,9 @@ full_citation_graph(n, ..., directed = TRUE) An igraph graph. } \description{ -\code{make_full_citation_graph()} creates a full citation graph. This is a -directed graph, where every \code{i->j} edge is present if and only if -\eqn{jj} edge is present if and only if \eqn{j}}\preformatted{g <- make_graph(~ 0-1-2-3-4-1) min_st_separators(g) diff --git a/man/minimal.st.separators.Rd b/man/minimal.st.separators.Rd index ce68851dee0..116421f4f67 100644 --- a/man/minimal.st.separators.Rd +++ b/man/minimal.st.separators.Rd @@ -7,14 +7,13 @@ minimal.st.separators(graph) } \arguments{ -\item{graph}{The input graph. It may be directed, but edge directions are -ignored.} +\item{graph}{The input graph. +It may be directed, but edge directions are ignored.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{minimal.st.separators()} was renamed to \code{\link[=min_st_separators]{min_st_separators()}} to create a more -consistent API. +\code{minimal.st.separators()} was renamed to \code{\link[=min_st_separators]{min_st_separators()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Separators.html#igraph_all_minimal_st_separators}{\code{all_minimal_st_separators()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/minimum.size.separators.Rd b/man/minimum.size.separators.Rd index 18aad1738e5..b669204a838 100644 --- a/man/minimum.size.separators.Rd +++ b/man/minimum.size.separators.Rd @@ -7,14 +7,13 @@ minimum.size.separators(graph) } \arguments{ -\item{graph}{The input graph. It may be directed, but edge directions are -ignored.} +\item{graph}{The input graph. +It may be directed, but edge directions are ignored.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{minimum.size.separators()} was renamed to \code{\link[=min_separators]{min_separators()}} to create a more -consistent API. +\code{minimum.size.separators()} was renamed to \code{\link[=min_separators]{min_separators()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Separators.html#igraph_minimum_size_separators}{\code{minimum_size_separators()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/minimum.spanning.tree.Rd b/man/minimum.spanning.tree.Rd index ba76a8ad6c5..12340e205da 100644 --- a/man/minimum.spanning.tree.Rd +++ b/man/minimum.spanning.tree.Rd @@ -9,25 +9,24 @@ minimum.spanning.tree(graph, weights = NULL, algorithm = NULL, ...) \arguments{ \item{graph}{The graph object to analyze.} -\item{weights}{Numeric vector giving the weights of the edges in the -graph. The order is determined by the edge IDs. This is ignored if the -\code{unweighted} algorithm is chosen. Edge weights are interpreted as -distances.} +\item{weights}{Numeric vector giving the weights of the edges in the graph. +The order is determined by the edge IDs. +This is ignored if the \code{unweighted} algorithm is chosen. +Edge weights are interpreted as distances.} -\item{algorithm}{The algorithm to use for calculation. \code{unweighted} can -be used for unweighted graphs, and \code{prim} runs Prim's algorithm for -weighted graphs. If this is \code{NULL} then igraph will select the -algorithm automatically: if the graph has an edge attribute called -\code{weight} or the \code{weights} argument is not \code{NULL} then Prim's -algorithm is chosen, otherwise the unweighted algorithm is used.} +\item{algorithm}{The algorithm to use for calculation. +\code{unweighted} can be used for unweighted graphs, +and \code{prim} runs Prim's algorithm for weighted graphs. +If this is \code{NULL} then igraph will select the algorithm automatically: +if the graph has an edge attribute called \code{weight} or the \code{weights} argument is not \code{NULL} then Prim's algorithm is chosen, +otherwise the unweighted algorithm is used.} \item{...}{Additional arguments, unused.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{minimum.spanning.tree()} was renamed to \code{\link[=mst]{mst()}} to create a more -consistent API. +\code{minimum.spanning.tree()} was renamed to \code{\link[=mst]{mst()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_minimum_spanning_tree_prim}{\code{minimum_spanning_tree_prim()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_minimum_spanning_tree_unweighted}{\code{minimum_spanning_tree_unweighted()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/mod.matrix.Rd b/man/mod.matrix.Rd index f7e0a5d0e2b..0651300a09f 100644 --- a/man/mod.matrix.Rd +++ b/man/mod.matrix.Rd @@ -7,22 +7,22 @@ mod.matrix(graph, membership, weights = NULL, resolution = 1, directed = TRUE) } \arguments{ -\item{membership}{Numeric vector, one value for each vertex, the membership -vector of the community structure.} +\item{membership}{Numeric vector, one value for each vertex, the membership vector of the community structure.} -\item{weights}{Numeric vector giving edge weights. Default: \code{NULL}.} +\item{weights}{Numeric vector giving edge weights. +Default: \code{NULL}.} -\item{resolution}{The resolution parameter. Must be greater than or equal to +\item{resolution}{The resolution parameter. +Must be greater than or equal to 0. Set it to 1 to use the classical definition of modularity.} -\item{directed}{Whether to use the directed or undirected version of -modularity. Ignored for undirected graphs.} +\item{directed}{Whether to use the directed or undirected version of modularity. +Ignored for undirected graphs.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{mod.matrix()} was renamed to \code{\link[=modularity_matrix]{modularity_matrix()}} to create a more -consistent API. +\code{mod.matrix()} was renamed to \code{\link[=modularity_matrix]{modularity_matrix()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Community.html#igraph_modularity_matrix}{\code{modularity_matrix()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/modularity.igraph.Rd b/man/modularity.igraph.Rd index 5684ea9f65a..ad76c77dbcd 100644 --- a/man/modularity.igraph.Rd +++ b/man/modularity.igraph.Rd @@ -20,71 +20,61 @@ modularity_matrix( \arguments{ \item{x, graph}{The input graph.} -\item{membership}{Numeric vector, one value for each vertex, the membership -vector of the community structure.} +\item{membership}{Numeric vector, one value for each vertex, the membership vector of the community structure.} -\item{weights}{Numeric vector giving edge weights. Default: \code{NULL}.} +\item{weights}{Numeric vector giving edge weights. +Default: \code{NULL}.} -\item{resolution}{The resolution parameter. Must be greater than or equal to +\item{resolution}{The resolution parameter. +Must be greater than or equal to 0. Set it to 1 to use the classical definition of modularity.} -\item{directed}{Whether to use the directed or undirected version of -modularity. Ignored for undirected graphs.} +\item{directed}{Whether to use the directed or undirected version of modularity. +Ignored for undirected graphs.} -\item{\dots}{For \code{modularity_matrix()}, these dots must be empty. For -\code{modularity()}, unused, present for S3 method consistency but may be -used by other methods that implement it.} +\item{\dots}{For \code{modularity_matrix()}, these dots must be empty. +For \code{modularity()}, unused, present for S3 method consistency but may be used by other methods that implement it.} } \value{ -For \code{modularity()} a numeric scalar, the modularity score of the -given configuration. +For \code{modularity()} a numeric scalar, the modularity score of the given configuration. -For \code{modularity_matrix()} a numeric square matrix, its order is the number of -vertices in the graph. +For \code{modularity_matrix()} a numeric square matrix, its order is the number of vertices in the graph. } \description{ -This function calculates how modular is a given division of a graph into -subgraphs. +This function calculates how modular is a given division of a graph into subgraphs. } \details{ -\code{modularity()} calculates the modularity of a graph with respect to the -given \code{membership} vector. +\code{modularity()} calculates the modularity of a graph with respect to the given \code{membership} vector. -The modularity of a graph with respect to some division (or vertex types) -measures how good the division is, or how separated are the different vertex +The modularity of a graph with respect to some division (or vertex types) measures how good the division is, +or how separated are the different vertex types from each other. It defined as \deqn{Q=\frac{1}{2m} \sum_{i,j} (A_{ij}-\gamma\frac{k_i k_j}{2m})\delta(c_i,c_j),}{Q=1/(2m) * sum( (Aij-gamma*ki*kj/(2m) ) delta(ci,cj),i,j),} here \eqn{m} is the number of edges, \eqn{A_{ij}}{Aij} -is the element of the \eqn{A} adjacency matrix in row \eqn{i} and column -\eqn{j}, \eqn{k_i}{ki} is the degree of \eqn{i}, \eqn{k_j}{kj} is the degree -of \eqn{j}, \eqn{c_i}{ci} is the type (or component) of \eqn{i}, -\eqn{c_j}{cj} that of \eqn{j}, the sum goes over all \eqn{i} and \eqn{j} -pairs of vertices, and \eqn{\delta(x,y)}{delta(x,y)} is 1 if \eqn{x=y} and 0 -otherwise. For directed graphs, it is defined as +is the element of the \eqn{A} adjacency matrix in row \eqn{i} and column \eqn{j}, \eqn{k_i}{ki} is the degree of \eqn{i}, +\eqn{k_j}{kj} is the degree of \eqn{j}, \eqn{c_i}{ci} is the type (or component) of \eqn{i}, \eqn{c_j}{cj} that of \eqn{j}, +the sum goes over all \eqn{i} and \eqn{j} pairs of vertices, and \eqn{\delta(x,y)}{delta(x,y)} is 1 if \eqn{x=y} and 0 otherwise. +For directed graphs, it is defined as \deqn{Q = \frac{1}{m} \sum_{i,j} (A_{ij}-\gamma \frac{k_i^{out} k_j^{in}}{m})\delta(c_i,c_j).}{Q=1/(m) * sum( (Aij-gamma*ki^out*kj^in/(m) ) delta(ci,cj),i,j).} -The resolution parameter \eqn{\gamma}{gamma} allows weighting the random -null model, which might be useful when finding partitions with a high -modularity. Maximizing modularity with higher values of the resolution -parameter typically results in more, smaller clusters when finding -partitions with a high modularity. Lower values typically results in fewer, -larger clusters. The original definition of modularity is retrieved when -setting \eqn{\gamma}{gamma} to 1. +The resolution parameter \eqn{\gamma}{gamma} allows weighting the random null model, +which might be useful when finding partitions with a high modularity. +Maximizing modularity with higher values of the resolution parameter typically results in more, +smaller clusters when finding partitions with a high modularity. +Lower values typically results in fewer, larger clusters. +The original definition of modularity is retrieved when setting \eqn{\gamma}{gamma} to 1. -If edge weights are given, then these are considered as the element of the -\eqn{A} adjacency matrix, and \eqn{k_i}{ki} is the sum of weights of -adjacent edges for vertex \eqn{i}. +If edge weights are given, then these are considered as the element of the \eqn{A} adjacency matrix, +and \eqn{k_i}{ki} is the sum of weights of adjacent edges for vertex \eqn{i}. -\code{modularity_matrix()} calculates the modularity matrix. This is a dense matrix, -and it is defined as the difference of the adjacency matrix and the -configuration model null model matrix. In other words element -\eqn{M_{ij}}{M[i,j]} is given as \eqn{A_{ij}-d_i +\code{modularity_matrix()} calculates the modularity matrix. +This is a dense matrix, and it is defined as the difference of the adjacency matrix and the configuration model null model matrix. +In other words element \eqn{M_{ij}}{M[i,j]} is given as \eqn{A_{ij}-d_i d_j/(2m)}{A[i,j]-d[i]d[j]/(2m)}, where \eqn{A_{ij}}{A[i,j]} is the (possibly weighted) adjacency matrix, \eqn{d_i}{d[i]} is the degree of vertex \eqn{i}, -and \eqn{m} is the number of edges (or the total weights in the graph, if it -is weighed). +and \eqn{m} is the number of edges (or the total weights in the graph, if it is weighed). } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Community.html#igraph_modularity}{\code{modularity()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Community.html#igraph_modularity_matrix}{\code{modularity_matrix()}} @@ -104,11 +94,8 @@ Clauset, A.; Newman, M. E. J. & Moore, C. Finding community structure in very large networks, \emph{Physical Review E} 2004, 70, 066111 } \seealso{ -\code{\link[=cluster_walktrap]{cluster_walktrap()}}, -\code{\link[=cluster_edge_betweenness]{cluster_edge_betweenness()}}, -\code{\link[=cluster_fast_greedy]{cluster_fast_greedy()}}, \code{\link[=cluster_spinglass]{cluster_spinglass()}}, -\code{\link[=cluster_louvain]{cluster_louvain()}} and \code{\link[=cluster_leiden]{cluster_leiden()}} for -various community detection methods. +\code{\link[=cluster_walktrap]{cluster_walktrap()}}, \code{\link[=cluster_edge_betweenness]{cluster_edge_betweenness()}}, \code{\link[=cluster_fast_greedy]{cluster_fast_greedy()}}, \code{\link[=cluster_spinglass]{cluster_spinglass()}}, +\code{\link[=cluster_louvain]{cluster_louvain()}} and \code{\link[=cluster_leiden]{cluster_leiden()}} for various community detection methods. Community detection: \code{\link[=as_membership]{as_membership()}}, diff --git a/man/motifs.Rd b/man/motifs.Rd index 7d504c84955..c60770ad8a4 100644 --- a/man/motifs.Rd +++ b/man/motifs.Rd @@ -9,46 +9,39 @@ motifs(graph, size = 3, ..., cut.prob = NULL, callback = NULL) \arguments{ \item{graph}{Graph object, the input graph.} -\item{size}{The size of the motif, currently sizes 3 and 4 are supported in -directed graphs and sizes 3 to 6 in undirected graphs.} +\item{size}{The size of the motif, currently sizes 3 and 4 are supported in directed graphs and sizes 3 to 6 in undirected graphs.} \item{...}{These dots are for future extensions and must be empty.} -\item{cut.prob}{Numeric vector giving the probabilities that the search -graph is cut at a certain level. Its length should be the same as the size -of the motif (the \code{size} argument). +\item{cut.prob}{Numeric vector giving the probabilities that the search graph is cut at a certain level. +Its length should be the same as the size of the motif (the \code{size} argument). If \code{NULL}, the default, no cuts are made.} \item{callback}{Optional callback function to call for each motif found. -The function should accept two arguments: \code{vids} (integer vector of vertex IDs -in the motif) and \code{isoclass} (the isomorphism class of the motif). +The function should accept two arguments: +\code{vids} (integer vector of vertex IDs in the motif) and \code{isoclass} (the isomorphism class of the motif). The function should return \code{FALSE} to continue the search or \code{TRUE} to stop it. If \code{NULL} (the default), motif counts are returned as a numeric vector. -\strong{Important limitation:} Callback functions must NOT call any igraph -functions (including simple queries like \code{vcount()} or \code{ecount()}). Doing -so will cause R to crash due to reentrancy issues. Extract -any needed graph information before calling the function with a callback, or -use collector mode (the default) and process results afterward.} +\strong{Important limitation:} Callback functions must NOT call any igraph functions (including simple queries like \code{vcount()} or \code{ecount()}). +Doing so will cause R to crash due to reentrancy issues. +Extract any needed graph information before calling the function with a callback, +or use collector mode (the default) and process results afterward.} } \value{ -When \code{callback} is \code{NULL}, \code{motifs()} returns a numeric vector, -the number of occurrences of each motif in the graph. The motifs are ordered -by their isomorphism classes. Note that for unconnected subgraphs, which are -not considered to be motifs, the result will be \code{NA}. +When \code{callback} is \code{NULL}, \code{motifs()} returns a numeric vector, the number of occurrences of each motif in the graph. +The motifs are ordered by their isomorphism classes. +Note that for unconnected subgraphs, which are not considered to be motifs, the result will be \code{NA}. -When \code{callback} is provided, the function returns \code{NULL} invisibly and calls -the callback function for each motif found. +When \code{callback} is provided, the function returns \code{NULL} invisibly and calls the callback function for each motif found. } \description{ -Graph motifs are small connected induced subgraphs with a well-defined -structure. These functions search a graph for various motifs. +Graph motifs are small connected induced subgraphs with a well-defined structure. +These functions search a graph for various motifs. } \details{ -\code{motifs()} searches a graph for motifs of a given size and returns a -numeric vector containing the number of different motifs. The order of -the motifs is defined by their isomorphism class, see -\code{\link[=isomorphism_class]{isomorphism_class()}}. +\code{motifs()} searches a graph for motifs of a given size and returns a numeric vector containing the number of different motifs. +The order of the motifs is defined by their isomorphism class, see \code{\link[=isomorphism_class]{isomorphism_class()}}. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Motifs.html#igraph_motifs_randesu_callback}{\code{motifs_randesu_callback()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Motifs.html#igraph_motifs_randesu}{\code{motifs_randesu()}} diff --git a/man/mst.Rd b/man/mst.Rd index a63878e1126..d2470bf0a16 100644 --- a/man/mst.Rd +++ b/man/mst.Rd @@ -9,35 +9,32 @@ mst(graph, weights = NULL, algorithm = NULL, ...) \arguments{ \item{graph}{The graph object to analyze.} -\item{weights}{Numeric vector giving the weights of the edges in the -graph. The order is determined by the edge IDs. This is ignored if the -\code{unweighted} algorithm is chosen. Edge weights are interpreted as -distances.} +\item{weights}{Numeric vector giving the weights of the edges in the graph. +The order is determined by the edge IDs. +This is ignored if the \code{unweighted} algorithm is chosen. +Edge weights are interpreted as distances.} -\item{algorithm}{The algorithm to use for calculation. \code{unweighted} can -be used for unweighted graphs, and \code{prim} runs Prim's algorithm for -weighted graphs. If this is \code{NULL} then igraph will select the -algorithm automatically: if the graph has an edge attribute called -\code{weight} or the \code{weights} argument is not \code{NULL} then Prim's -algorithm is chosen, otherwise the unweighted algorithm is used.} +\item{algorithm}{The algorithm to use for calculation. +\code{unweighted} can be used for unweighted graphs, +and \code{prim} runs Prim's algorithm for weighted graphs. +If this is \code{NULL} then igraph will select the algorithm automatically: +if the graph has an edge attribute called \code{weight} or the \code{weights} argument is not \code{NULL} then Prim's algorithm is chosen, +otherwise the unweighted algorithm is used.} \item{\dots}{Additional arguments, unused.} } \value{ -A graph object with the minimum spanning forest. To check whether it -is a tree, check that the number of its edges is \code{vcount(graph)-1}. -The edge and vertex attributes of the original graph are preserved in the -result. +A graph object with the minimum spanning forest. +To check whether it is a tree, check that the number of its edges is \code{vcount(graph)-1}. +The edge and vertex attributes of the original graph are preserved in the result. } \description{ -A \emph{spanning tree} of a connected graph is a connected subgraph with -the smallest number of edges that includes all vertices of the graph. -A graph will have many spanning trees. Among these, the \emph{minimum spanning -tree} will have the smallest sum of edge weights. +A \emph{spanning tree} of a connected graph is a connected subgraph with the smallest number of edges that includes all vertices of the graph. +A graph will have many spanning trees. +Among these, the \emph{minimum spanning tree} will have the smallest sum of edge weights. } \details{ -The \emph{minimum spanning forest} of a disconnected graph is the collection -of minimum spanning trees of all of its components. +The \emph{minimum spanning forest} of a disconnected graph is the collection of minimum spanning trees of all of its components. If the graph is not connected a minimum spanning forest is returned. } diff --git a/man/multilevel.community.Rd b/man/multilevel.community.Rd index 0b44412feba..c16e712cd28 100644 --- a/man/multilevel.community.Rd +++ b/man/multilevel.community.Rd @@ -7,27 +7,24 @@ multilevel.community(graph, weights = NULL, resolution = 1) } \arguments{ -\item{graph}{The input graph. It must be undirected.} +\item{graph}{The input graph. +It must be undirected.} -\item{weights}{The weights of the edges. It must be a positive numeric vector, -\code{NULL} or \code{NA}. If it is \code{NULL} and the input graph has a -\sQuote{weight} edge attribute, then that attribute will be used. If -\code{NULL} and no such attribute is present, then the edges will have equal -weights. Set this to \code{NA} if the graph was a \sQuote{weight} edge -attribute, but you don't want to use it for community detection. A larger -edge weight means a stronger connection for this function.} +\item{weights}{The weights of the edges. +It must be a positive numeric vector, \code{NULL} or \code{NA}. +If it is \code{NULL} and the input graph has a \sQuote{weight} edge attribute, then that attribute will be used. +If \code{NULL} and no such attribute is present, then the edges will have equal weights. +Set this to \code{NA} if the graph was a \sQuote{weight} edge attribute, but you don't want to use it for community detection. +A larger edge weight means a stronger connection for this function.} -\item{resolution}{Optional resolution parameter that allows the user to -adjust the resolution parameter of the modularity function that the algorithm -uses internally. Lower values typically yield fewer, larger clusters. The -original definition of modularity is recovered when the resolution parameter -is set to 1.} +\item{resolution}{Optional resolution parameter that allows the user to adjust the resolution parameter of the modularity function that the algorithm uses internally. +Lower values typically yield fewer, larger clusters. +The original definition of modularity is recovered when the resolution parameter is set to 1.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{multilevel.community()} was renamed to \code{\link[=cluster_louvain]{cluster_louvain()}} to create a more -consistent API. +\code{multilevel.community()} was renamed to \code{\link[=cluster_louvain]{cluster_louvain()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Community.html#igraph_community_multilevel}{\code{community_multilevel()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/neighborhood.size.Rd b/man/neighborhood.size.Rd index 3264876a6fe..3692e64f3c9 100644 --- a/man/neighborhood.size.Rd +++ b/man/neighborhood.size.Rd @@ -15,27 +15,25 @@ neighborhood.size( \arguments{ \item{graph}{The input graph.} -\item{order}{Integer giving the order of the neighborhood. Negative values -indicate an infinite order.} +\item{order}{Integer giving the order of the neighborhood. +Negative values indicate an infinite order.} \item{nodes}{The vertices for which the calculation is performed. The default \code{NULL} selects all vertices.} -\item{mode}{Character constant, it specifies how to use the direction of -the edges if a directed graph is analyzed. For \sQuote{out} only the -outgoing edges are followed, so all vertices reachable from the source -vertex in at most \code{order} steps are counted. For \sQuote{"in"} all -vertices from which the source vertex is reachable in at most \code{order} -steps are counted. \sQuote{"all"} ignores the direction of the edges. This -argument is ignored for undirected graphs.} +\item{mode}{Character constant, it specifies how to use the direction of the edges if a directed graph is analyzed. +For \sQuote{out} only the outgoing edges are followed, +so all vertices reachable from the source vertex in at most \code{order} steps are counted. +For \sQuote{"in"} all vertices from which the source vertex is reachable in at most \code{order} steps are counted. +\sQuote{"all"} ignores the direction of the edges. +This argument is ignored for undirected graphs.} \item{mindist}{The minimum distance to include the vertex in the result.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{neighborhood.size()} was renamed to \code{\link[=ego_size]{ego_size()}} to create a more -consistent API. +\code{neighborhood.size()} was renamed to \code{\link[=ego_size]{ego_size()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/neighbors.Rd b/man/neighbors.Rd index 7ddf86de6ce..ab3abc9ca4d 100644 --- a/man/neighbors.Rd +++ b/man/neighbors.Rd @@ -13,16 +13,14 @@ neighbors(graph, v, ..., mode = c("out", "in", "all", "total")) \item{...}{These dots are for future extensions and must be empty.} -\item{mode}{Whether to query outgoing (\sQuote{out}), incoming -(\sQuote{in}) edges, or both types (\sQuote{all}). This is -ignored for undirected graphs.} +\item{mode}{Whether to query outgoing (\sQuote{out}), incoming (\sQuote{in}) edges, or both types (\sQuote{all}). +This is ignored for undirected graphs.} } \value{ A vertex sequence containing the neighbors of the input vertex. } \description{ -A vertex is a neighbor of another one (in other words, the two -vertices are adjacent), if they are incident to the same edge. +A vertex is a neighbor of another one (in other words, the two vertices are adjacent), if they are incident to the same edge. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_neighbors}{\code{neighbors()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/no.clusters.Rd b/man/no.clusters.Rd index 43a87f30cc3..94cd6587718 100644 --- a/man/no.clusters.Rd +++ b/man/no.clusters.Rd @@ -9,14 +9,14 @@ no.clusters(graph, mode = c("weak", "strong")) \arguments{ \item{graph}{The graph to analyze.} -\item{mode}{Character string, either \dQuote{weak} or \dQuote{strong}. For -directed graphs \dQuote{weak} implies weakly, \dQuote{strong} strongly -connected components to search. It is ignored for undirected graphs.} +\item{mode}{Character string, either \dQuote{weak} or \dQuote{strong}. +For directed graphs \dQuote{weak} implies weakly, +\dQuote{strong} strongly connected components to search. +It is ignored for undirected graphs.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{no.clusters()} was renamed to \code{\link[=count_components]{count_components()}} to create a more -consistent API. +\code{no.clusters()} was renamed to \code{\link[=count_components]{count_components()}} to create a more consistent API. } \keyword{internal} diff --git a/man/norm_coords.Rd b/man/norm_coords.Rd index 7938c1efa58..4fd4d5456a4 100644 --- a/man/norm_coords.Rd +++ b/man/norm_coords.Rd @@ -20,15 +20,14 @@ norm_coords( \item{...}{These dots are for future extensions and must be empty.} -\item{xmin, xmax}{The limits for the first coordinate, if one of them or both -are \code{NULL} then no normalization is performed along this direction.} +\item{xmin, xmax}{The limits for the first coordinate, +if one of them or both are \code{NULL} then no normalization is performed along this direction.} -\item{ymin, ymax}{The limits for the second coordinate, if one of them or -both are \code{NULL} then no normalization is performed along this -direction.} +\item{ymin, ymax}{The limits for the second coordinate, +if one of them or both are \code{NULL} then no normalization is performed along this direction.} -\item{zmin, zmax}{The limits for the third coordinate, if one of them or both -are \code{NULL} then no normalization is performed along this direction.} +\item{zmin, zmax}{The limits for the third coordinate, +if one of them or both are \code{NULL} then no normalization is performed along this direction.} } \value{ A numeric matrix with at the same dimension as \code{layout}. @@ -37,8 +36,7 @@ A numeric matrix with at the same dimension as \code{layout}. Rescale coordinates linearly to be within given bounds. } \details{ -\code{norm_coords()} normalizes a layout, it linearly transforms each -coordinate separately to fit into the given limits. +\code{norm_coords()} normalizes a layout, it linearly transforms each coordinate separately to fit into the given limits. } \seealso{ Other graph layouts: diff --git a/man/normalize.Rd b/man/normalize.Rd index c45f3047caf..c73a55d5d4f 100644 --- a/man/normalize.Rd +++ b/man/normalize.Rd @@ -16,13 +16,11 @@ normalize( \arguments{ \item{xmin, xmax}{Minimum and maximum for x coordinates.} -\item{ymin, ymax}{Minimum and maximum for y coordinates. When omitted, -they follow \code{xmin} and \code{xmax}; \code{NULL} disables normalization along -this axis.} +\item{ymin, ymax}{Minimum and maximum for y coordinates. +When omitted, they follow \code{xmin} and \code{xmax}; \code{NULL} disables normalization along this axis.} -\item{zmin, zmax}{Minimum and maximum for z coordinates. When omitted, -they follow \code{xmin} and \code{xmax}; \code{NULL} disables normalization along -this axis.} +\item{zmin, zmax}{Minimum and maximum for z coordinates. +When omitted, they follow \code{xmin} and \code{xmax}; \code{NULL} disables normalization along this axis.} } \description{ Scale coordinates of a layout. diff --git a/man/optimal.community.Rd b/man/optimal.community.Rd index 625fcc65873..7cb3cf88351 100644 --- a/man/optimal.community.Rd +++ b/man/optimal.community.Rd @@ -7,21 +7,20 @@ optimal.community(graph, weights = NULL) } \arguments{ -\item{graph}{The input graph. It may be undirected or directed.} +\item{graph}{The input graph. +It may be undirected or directed.} -\item{weights}{The weights of the edges. It must be a positive numeric -vector, \code{NULL} or \code{NA}. If it is \code{NULL} and the input graph has a -\sQuote{weight} edge attribute, then that attribute will be used. If -\code{NULL} and no such attribute is present, then the edges will have equal -weights. Set this to \code{NA} if the graph was a \sQuote{weight} edge -attribute, but you don't want to use it for community detection. A larger -edge weight means a stronger connection for this function.} +\item{weights}{The weights of the edges. +It must be a positive numeric vector, \code{NULL} or \code{NA}. +If it is \code{NULL} and the input graph has a \sQuote{weight} edge attribute, then that attribute will be used. +If \code{NULL} and no such attribute is present, then the edges will have equal weights. +Set this to \code{NA} if the graph was a \sQuote{weight} edge attribute, but you don't want to use it for community detection. +A larger edge weight means a stronger connection for this function.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{optimal.community()} was renamed to \code{\link[=cluster_optimal]{cluster_optimal()}} to create a more -consistent API. +\code{optimal.community()} was renamed to \code{\link[=cluster_optimal]{cluster_optimal()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Community.html#igraph_community_optimal_modularity}{\code{community_optimal_modularity()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/page.rank.Rd b/man/page.rank.Rd index 0c81f6fdfc3..8bfb4d8c97f 100644 --- a/man/page.rank.Rd +++ b/man/page.rank.Rd @@ -18,48 +18,43 @@ page.rank( \arguments{ \item{graph}{The graph object.} -\item{algo}{Character scalar, which implementation to use to carry out the -calculation. The default is \code{"prpack"}, which uses the PRPACK library -(\url{https://github.com/dgleich/prpack}) to calculate PageRank scores -by solving a set of linear equations. This is a new implementation in igraph -version 0.7, and the suggested one, as it is the most stable and the fastest -for all but small graphs. \code{"arpack"} uses the ARPACK library, the -default implementation from igraph version 0.5 until version 0.7. It computes -PageRank scores by solving an eingevalue problem.} +\item{algo}{Character scalar, which implementation to use to carry out the calculation. +The default is \code{"prpack"}, +which uses the PRPACK library (\url{https://github.com/dgleich/prpack}) to calculate PageRank scores by solving a set of linear equations. +This is a new implementation in igraph version 0.7, and the suggested one, +as it is the most stable and the fastest for all but small graphs. +\code{"arpack"} uses the ARPACK library, +the default implementation from igraph version 0.5 until version 0.7. It computes PageRank scores by solving an eingevalue problem.} \item{vids}{The vertices of interest. The default \code{NULL} selects all vertices.} -\item{directed}{Logical, if true directed paths will be considered for -directed graphs. It is ignored for undirected graphs.} +\item{directed}{Logical, if true directed paths will be considered for directed graphs. +It is ignored for undirected graphs.} \item{damping}{The damping factor (\sQuote{d} in the original paper).} -\item{personalized}{Optional vector giving a probability distribution to -calculate personalized PageRank. For personalized PageRank, the probability -of jumping to a node when abandoning the random walk is not uniform, but it -is given by this vector. The vector should contains an entry for each vertex -and it will be rescaled to sum up to one.} - -\item{weights}{A numerical vector or \code{NULL}. This argument can be used -to give edge weights for calculating the weighted PageRank of vertices. If -this is \code{NULL} and the graph has a \code{weight} edge attribute then -that is used. If \code{weights} is a numerical vector then it used, even if -the graph has a \code{weights} edge attribute. If this is \code{NA}, then no -edge weights are used (even if the graph has a \code{weight} edge attribute. -This function interprets edge weights as connection strengths. In the -random surfer model, an edge with a larger weight is more likely to be -selected by the surfer.} - -\item{options}{A named list, to override some ARPACK options. See -\code{\link[=arpack]{arpack()}} for details. This argument is ignored if the PRPACK -implementation is used.} +\item{personalized}{Optional vector giving a probability distribution to calculate personalized PageRank. +For personalized PageRank, the probability of jumping to a node when abandoning the random walk is not uniform, +but it is given by this vector. +The vector should contains an entry for each vertex and it will be rescaled to sum up to one.} + +\item{weights}{A numerical vector or \code{NULL}. +This argument can be used to give edge weights for calculating the weighted PageRank of vertices. +If this is \code{NULL} and the graph has a \code{weight} edge attribute then that is used. +If \code{weights} is a numerical vector then it used, even if the graph has a \code{weights} edge attribute. +If this is \code{NA}, then no edge weights are used (even if the graph has a \code{weight} edge attribute. +This function interprets edge weights as connection strengths. +In the random surfer model, an edge with a larger weight is more likely to be selected by the surfer.} + +\item{options}{A named list, to override some ARPACK options. +See \code{\link[=arpack]{arpack()}} for details. +This argument is ignored if the PRPACK implementation is used.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{page.rank()} was renamed to \code{\link[=page_rank]{page_rank()}} to create a more -consistent API. +\code{page.rank()} was renamed to \code{\link[=page_rank]{page_rank()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_personalized_pagerank}{\code{personalized_pagerank()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/page_rank.Rd b/man/page_rank.Rd index 58937b15dfc..2b25af1cec2 100644 --- a/man/page_rank.Rd +++ b/man/page_rank.Rd @@ -21,42 +21,38 @@ page_rank( \item{...}{These dots are for future extensions and must be empty.} -\item{algo}{Character scalar, which implementation to use to carry out the -calculation. The default is \code{"prpack"}, which uses the PRPACK library -(\url{https://github.com/dgleich/prpack}) to calculate PageRank scores -by solving a set of linear equations. This is a new implementation in igraph -version 0.7, and the suggested one, as it is the most stable and the fastest -for all but small graphs. \code{"arpack"} uses the ARPACK library, the -default implementation from igraph version 0.5 until version 0.7. It computes -PageRank scores by solving an eingevalue problem.} +\item{algo}{Character scalar, which implementation to use to carry out the calculation. +The default is \code{"prpack"}, +which uses the PRPACK library (\url{https://github.com/dgleich/prpack}) to calculate PageRank scores by solving a set of linear equations. +This is a new implementation in igraph version 0.7, and the suggested one, +as it is the most stable and the fastest for all but small graphs. +\code{"arpack"} uses the ARPACK library, +the default implementation from igraph version 0.5 until version 0.7. It computes PageRank scores by solving an eingevalue problem.} \item{vids}{The vertices of interest. The default \code{NULL} selects all vertices.} -\item{directed}{Logical, if true directed paths will be considered for -directed graphs. It is ignored for undirected graphs.} +\item{directed}{Logical, if true directed paths will be considered for directed graphs. +It is ignored for undirected graphs.} \item{damping}{The damping factor (\sQuote{d} in the original paper).} -\item{personalized}{Optional vector giving a probability distribution to -calculate personalized PageRank. For personalized PageRank, the probability -of jumping to a node when abandoning the random walk is not uniform, but it -is given by this vector. The vector should contains an entry for each vertex -and it will be rescaled to sum up to one.} - -\item{weights}{A numerical vector or \code{NULL}. This argument can be used -to give edge weights for calculating the weighted PageRank of vertices. If -this is \code{NULL} and the graph has a \code{weight} edge attribute then -that is used. If \code{weights} is a numerical vector then it used, even if -the graph has a \code{weights} edge attribute. If this is \code{NA}, then no -edge weights are used (even if the graph has a \code{weight} edge attribute. -This function interprets edge weights as connection strengths. In the -random surfer model, an edge with a larger weight is more likely to be -selected by the surfer.} - -\item{options}{A named list, to override some ARPACK options. See -\code{\link[=arpack]{arpack()}} for details. This argument is ignored if the PRPACK -implementation is used.} +\item{personalized}{Optional vector giving a probability distribution to calculate personalized PageRank. +For personalized PageRank, the probability of jumping to a node when abandoning the random walk is not uniform, +but it is given by this vector. +The vector should contains an entry for each vertex and it will be rescaled to sum up to one.} + +\item{weights}{A numerical vector or \code{NULL}. +This argument can be used to give edge weights for calculating the weighted PageRank of vertices. +If this is \code{NULL} and the graph has a \code{weight} edge attribute then that is used. +If \code{weights} is a numerical vector then it used, even if the graph has a \code{weights} edge attribute. +If this is \code{NA}, then no edge weights are used (even if the graph has a \code{weight} edge attribute. +This function interprets edge weights as connection strengths. +In the random surfer model, an edge with a larger weight is more likely to be selected by the surfer.} + +\item{options}{A named list, to override some ARPACK options. +See \code{\link[=arpack]{arpack()}} for details. +This argument is ignored if the PRPACK implementation is used.} } \value{ A named list with entries: @@ -76,22 +72,17 @@ Some information about the underlying ARPACK calculation. See \code{\link[=arpac Calculates the Google PageRank for the specified vertices. } \details{ -For the explanation of the PageRank algorithm, see the following webpage: -\url{http://infolab.stanford.edu/~backrub/google.html}, or the following -reference: - -Sergey Brin and Larry Page: The Anatomy of a Large-Scale Hypertextual Web -Search Engine. Proceedings of the 7th World-Wide Web Conference, Brisbane, -Australia, April 1998. - -The \code{page_rank()} function can use either the PRPACK library or ARPACK -(see \code{\link[=arpack]{arpack()}}) to perform the calculation. - -Please note that the PageRank of a given vertex depends on the PageRank of -all other vertices, so even if you want to calculate the PageRank for only -some of the vertices, all of them must be calculated. Requesting the -PageRank for only some of the vertices does not result in any performance -increase at all. +For the explanation of the PageRank algorithm, see the following webpage: \url{http://infolab.stanford.edu/~backrub/google.html}, +or the following reference: + +Sergey Brin and Larry Page: The Anatomy of a Large-Scale Hypertextual Web Search Engine. +Proceedings of the 7th World-Wide Web Conference, Brisbane, Australia, April 1998. + +The \code{page_rank()} function can use either the PRPACK library or ARPACK (see \code{\link[=arpack]{arpack()}}) to perform the calculation. + +Please note that the PageRank of a given vertex depends on the PageRank of all other vertices, +so even if you want to calculate the PageRank for only some of the vertices, all of them must be calculated. +Requesting the PageRank for only some of the vertices does not result in any performance increase at all. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_personalized_pagerank}{\code{personalized_pagerank()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/path.Rd b/man/path.Rd index 3c60a96028c..75467274775 100644 --- a/man/path.Rd +++ b/man/path.Rd @@ -10,22 +10,18 @@ path(...) \item{...}{See details below.} } \value{ -A special object that can be used together with igraph -graphs and the plus and minus operators. +A special object that can be used together with igraph graphs and the plus and minus operators. } \description{ This function can be used to add or delete edges that form a path. } \details{ -When adding edges via \code{+}, all unnamed arguments are -concatenated, and each element of a final vector is interpreted -as a vertex in the graph. For a vector of length \eqn{n+1}, \eqn{n} -edges are then added, from vertex 1 to vertex 2, from vertex 2 to vertex -3, etc. Named arguments will be used as edge attributes for the new -edges. +When adding edges via \code{+}, all unnamed arguments are concatenated, +and each element of a final vector is interpreted as a vertex in the graph. +For a vector of length \eqn{n+1}, \eqn{n} edges are then added, from vertex 1 to vertex 2, from vertex 2 to vertex 3, +etc. Named arguments will be used as edge attributes for the new edges. -When deleting edges, all attributes are concatenated and then passed -to \code{\link[=delete_edges]{delete_edges()}}. +When deleting edges, all attributes are concatenated and then passed to \code{\link[=delete_edges]{delete_edges()}}. } \examples{ # Create a (directed) wheel diff --git a/man/path.length.hist.Rd b/man/path.length.hist.Rd index cf2ebf9912e..d71935de82b 100644 --- a/man/path.length.hist.Rd +++ b/man/path.length.hist.Rd @@ -15,8 +15,7 @@ this argument is ignored for undirected graphs.} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{path.length.hist()} was renamed to \code{\link[=distance_table]{distance_table()}} to create a more -consistent API. +\code{path.length.hist()} was renamed to \code{\link[=distance_table]{distance_table()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_path_length_hist}{\code{path_length_hist()}} diff --git a/man/permute.Rd b/man/permute.Rd index 8e3a68e7cdc..15d3c86b3d2 100644 --- a/man/permute.Rd +++ b/man/permute.Rd @@ -9,9 +9,8 @@ permute(graph, permutation) \arguments{ \item{graph}{The input graph, it can directed or undirected.} -\item{permutation}{A numeric vector giving the permutation to apply. The -first element is the new ID of vertex 1, etc. Every number between one and -\code{vcount(graph)} must appear exactly once.} +\item{permutation}{A numeric vector giving the permutation to apply. +The first element is the new ID of vertex 1, etc. Every number between one and \code{vcount(graph)} must appear exactly once.} } \value{ A new graph object. @@ -20,10 +19,8 @@ A new graph object. Create a new graph, by permuting vertex IDs. } \details{ -This function creates a new graph from the input graph by permuting its -vertices according to the specified mapping. Call this function with the -output of \code{\link[=canonical_permutation]{canonical_permutation()}} to create the canonical form -of a graph. +This function creates a new graph from the input graph by permuting its vertices according to the specified mapping. +Call this function with the output of \code{\link[=canonical_permutation]{canonical_permutation()}} to create the canonical form of a graph. \code{permute()} keeps all graph, vertex and edge attributes of the graph. } diff --git a/man/permute.vertices.Rd b/man/permute.vertices.Rd index 9240ede4e13..b6022641462 100644 --- a/man/permute.vertices.Rd +++ b/man/permute.vertices.Rd @@ -9,15 +9,13 @@ permute.vertices(graph, permutation) \arguments{ \item{graph}{The input graph, it can directed or undirected.} -\item{permutation}{A numeric vector giving the permutation to apply. The -first element is the new ID of vertex 1, etc. Every number between one and -\code{vcount(graph)} must appear exactly once.} +\item{permutation}{A numeric vector giving the permutation to apply. +The first element is the new ID of vertex 1, etc. Every number between one and \code{vcount(graph)} must appear exactly once.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{permute.vertices()} was renamed to \code{\link[=permute]{permute()}} to create a more -consistent API. +\code{permute.vertices()} was renamed to \code{\link[=permute]{permute()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Isomorphism.html#igraph_permute_vertices}{\code{permute_vertices()}} diff --git a/man/piecewise.layout.Rd b/man/piecewise.layout.Rd index 3442d206bb7..951bff9756e 100644 --- a/man/piecewise.layout.Rd +++ b/man/piecewise.layout.Rd @@ -9,18 +9,16 @@ piecewise.layout(graph, layout = layout_with_kk, ...) \arguments{ \item{graph}{The input graph.} -\item{layout}{A function object, the layout function to use. The default -\code{NULL} uses \code{layout_with_kk}.} +\item{layout}{A function object, the layout function to use. +The default \code{NULL} uses \code{layout_with_kk}.} -\item{...}{For \code{layout_components()}, additional arguments to pass to -the \code{layout} layout function. For \code{merge_coords()}, these dots must be -empty.} +\item{...}{For \code{layout_components()}, additional arguments to pass to the \code{layout} layout function. +For \code{merge_coords()}, these dots must be empty.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{piecewise.layout()} was renamed to \code{\link[=layout_components]{layout_components()}} to create a more -consistent API. +\code{piecewise.layout()} was renamed to \code{\link[=layout_components]{layout_components()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_decompose}{\code{decompose()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/pipe.Rd b/man/pipe.Rd index 22008cb63f7..e34d6a0fe67 100644 --- a/man/pipe.Rd +++ b/man/pipe.Rd @@ -9,13 +9,11 @@ \item{rhs}{Right hand side of the pipe.} } \value{ -Result of applying the right hand side to the -result of the left hand side. +Result of applying the right hand side to the result of the left hand side. } \description{ -igraph re-exports the \verb{\%>\%} operator of magrittr, because -we find it very useful. Please see the documentation in the -\code{magrittr} package. +igraph re-exports the \verb{\%>\%} operator of magrittr, because we find it very useful. +Please see the documentation in the \code{magrittr} package. } \examples{ make_ring(10) \%>\% diff --git a/man/plot.common.Rd b/man/plot.common.Rd index 5cd7128d499..a19f63ad259 100644 --- a/man/plot.common.Rd +++ b/man/plot.common.Rd @@ -9,92 +9,78 @@ The common bits of the three plotting functions \code{plot.igraph}, \code{tkplot} and \code{rglplot} are discussed in this manual page. } \details{ -There are currently three different functions in the igraph package which -can draw graph in various ways: +There are currently three different functions in the igraph package which can draw graph in various ways: \code{plot.igraph} does simple non-interactive 2D plotting to R devices. -Actually it is an implementation of the \code{\link[graphics:plot]{graphics::plot()}} generic -function, so you can write \code{plot(graph)} instead of -\code{plot.igraph(graph)}. As it used the standard R devices it supports -every output format for which R has an output device. The list is quite -impressing: PostScript, PDF files, XFig files, SVG files, JPG, PNG and of -course you can plot to the screen as well using the default devices, or the -good-looking anti-aliased Cairo device. See \code{\link[=plot.igraph]{plot.igraph()}} for -some more information. - -\code{\link[=tkplot]{tkplot()}} does interactive 2D plotting using the \code{tcltk} -package. It can only handle graphs of moderate size, a thousand vertices is -probably already too many. Some parameters of the plotted graph can be -changed interactively after issuing the \code{tkplot} command: the position, -color and size of the vertices and the color and width of the edges. See -\code{\link[=tkplot]{tkplot()}} for details. - -\code{\link[=rglplot]{rglplot()}} is an experimental function to draw graphs in 3D using -OpenGL. See \code{\link[=rglplot]{rglplot()}} for some more information. +Actually it is an implementation of the \code{\link[graphics:plot]{graphics::plot()}} generic function, +so you can write \code{plot(graph)} instead of \code{plot.igraph(graph)}. +As it used the standard R devices it supports every output format for which R has an output device. +The list is quite impressing: +PostScript, PDF files, XFig files, SVG files, JPG, PNG and of course you can plot to the screen as well using the default devices, +or the good-looking anti-aliased Cairo device. +See \code{\link[=plot.igraph]{plot.igraph()}} for some more information. + +\code{\link[=tkplot]{tkplot()}} does interactive 2D plotting using the \code{tcltk} package. +It can only handle graphs of moderate size, a thousand vertices is probably already too many. +Some parameters of the plotted graph can be changed interactively after issuing the \code{tkplot} command: the position, +color and size of the vertices and the color and width of the edges. +See \code{\link[=tkplot]{tkplot()}} for details. + +\code{\link[=rglplot]{rglplot()}} is an experimental function to draw graphs in 3D using OpenGL. +See \code{\link[=rglplot]{rglplot()}} for some more information. Please also check the examples below. } \section{How to specify graphical parameters}{ There are three ways to give -values to the parameters described below, in section 'Parameters'. We give -these three ways here in the order of their precedence. +values to the parameters described below, in section 'Parameters'. +We give these three ways here in the order of their precedence. -The first method is to supply named arguments to the plotting commands: -\code{\link[=plot.igraph]{plot.igraph()}}, \code{\link[=tkplot]{tkplot()}} or rglplot()]. -Parameters for vertices start with prefix \sQuote{\code{vertex.}}, -parameters for edges have prefix \sQuote{\code{edge.}}, and global -parameters have no prefix. Eg. the color of the vertices can be given via -argument \code{vertex.color}, whereas \code{edge.color} sets the color of -the edges. \code{layout} gives the layout of the graphs. +The first method is to supply named arguments to the plotting commands: \code{\link[=plot.igraph]{plot.igraph()}}, \code{\link[=tkplot]{tkplot()}} or rglplot()]. +Parameters for vertices start with prefix \sQuote{\code{vertex.}}, parameters for edges have prefix \sQuote{\code{edge.}}, +and global parameters have no prefix. +Eg. the color of the vertices can be given via argument \code{vertex.color}, whereas \code{edge.color} sets the color of the edges. +\code{layout} gives the layout of the graphs. The second way is to assign vertex, edge and graph attributes to the graph. -These attributes have no prefix, ie. the color of the vertices is taken from -the \code{color} vertex attribute and the color of the edges from the -\code{color} edge attribute. The layout of the graph is given by the -\code{layout} graph attribute. (Always assuming that the corresponding -command argument is not present.) Setting vertex and edge attributes are -handy if you want to assign a given \sQuote{look} to a graph, attributes are -saved with the graph is you save it with \code{\link[base:save]{base::save()}} or in -GraphML format with \code{\link[=write_graph]{write_graph()}}, so the graph will have the -same look after loading it again. - -If a parameter is not given in the command line, and the corresponding -vertex/edge/graph attribute is also missing then the general igraph -parameters handled by \code{\link[=igraph_options]{igraph_options()}} are also checked. Vertex -parameters have prefix \sQuote{\code{vertex.}}, edge parameters are prefixed -with \sQuote{\code{edge.}}, general parameters like \code{layout} are -prefixed with \sQuote{\code{plot}}. These parameters are useful if you want -all or most of your graphs to have the same look, vertex size, vertex color, -etc. Then you don't need to set these at every plotting, and you also don't -need to assign vertex/edge attributes to every graph. - -If the value of a parameter is not specified by any of the three ways -described here, its default valued is used, as given in the source code. - -Different parameters can have different type, eg. vertex colors can be given -as a character vector with color names, or as an integer vector with the -color numbers from the current palette. Different types are valid for -different parameters, this is discussed in detail in the next section. It is -however always true that the parameter can always be a function object in -which it will be called with the graph as its single argument to get the -\dQuote{proper} value of the parameter. (If the function returns another -function object that will \emph{not} be called again\dots) +These attributes have no prefix, ie. the color of the vertices is taken from the \code{color} vertex attribute +and the color of the edges from the \code{color} edge attribute. +The layout of the graph is given by the \code{layout} graph attribute. +(Always assuming that the corresponding command argument is not present.) +Setting vertex and edge attributes are handy if you want to assign a given \sQuote{look} to a graph, +attributes are saved with the graph is you save it with \code{\link[base:save]{base::save()}} or in GraphML format with \code{\link[=write_graph]{write_graph()}}, +so the graph will have the same look after loading it again. + +If a parameter is not given in the command line, +and the corresponding vertex/edge/graph attribute is also missing then the general igraph parameters handled by \code{\link[=igraph_options]{igraph_options()}} are also checked. +Vertex parameters have prefix \sQuote{\code{vertex.}}, edge parameters are prefixed with \sQuote{\code{edge.}}, +general parameters like \code{layout} are prefixed with \sQuote{\code{plot}}. +These parameters are useful +if you want all or most of your graphs to have the same look, vertex size, vertex color, +etc. Then you don't need to set these at every plotting, and you also don't need to assign vertex/edge attributes to every graph. + +If the value of a parameter is not specified by any of the three ways described here, its default valued is used, +as given in the source code. + +Different parameters can have different type, eg. vertex colors can be given as a character vector with color names, +or as an integer vector with the color numbers from the current palette. +Different types are valid for different parameters, this is discussed in detail in the next section. +It is however always true that the parameter can always be a function object +in which it will be called with the graph as its single argument to get the \dQuote{proper} value of the parameter. +(If the function returns another function object that will \emph{not} be called again\dots) } \section{The list of parameters}{ Vertex parameters first, note that the -\sQuote{\code{vertex.}} prefix needs to be added if they are used as an -argument or when setting via \code{\link[=igraph_options]{igraph_options()}}. The value of the -parameter may be scalar valid for every vertex or a vector with a separate -value for each vertex. (Shorter vectors are recycled.) +\sQuote{\code{vertex.}} prefix needs to be added if they are used as an argument or when setting via \code{\link[=igraph_options]{igraph_options()}}. +The value of the parameter may be scalar valid for every vertex or a vector with a separate value for each vertex. +(Shorter vectors are recycled.) \describe{ \item{size}{ -The size of the vertex, a numeric scalar or vector, -in the latter case each vertex sizes may differ. -This vertex sizes are scaled in order have about the same size of vertices -for a given value for all three plotting commands. -It does not need to be an integer number. The default value is 15. -This is big enough to place short labels on vertices. +The size of the vertex, a numeric scalar or vector, in the latter case each vertex sizes may differ. +This vertex sizes are scaled in order have about the same size of vertices for a given value for all three plotting commands. +It does not need to be an integer number. +The default value is 15. This is big enough to place short labels on vertices. If \code{size.scaling} is \code{TRUE}, \code{relative.size} is used to scale the size appropriately. } \item{size2}{ @@ -106,18 +92,15 @@ It is ignored by shapes for which the size can be specified with a single number The default is 15. } \item{color}{ -The fill color of the vertex. If it is -numeric then the current palette is used, see -\code{\link[grDevices:palette]{grDevices::palette()}}. If it is a character vector then it may -either contain integer values, named colors or RGB specified colors with -three or four bytes. All strings starting with \sQuote{\code{#}} are assumed -to be RGB color specifications. It is possible to mix named color and RGB -colors. Note that \code{\link[=tkplot]{tkplot()}} ignores the fourth byte (alpha -channel) in the RGB color specification. - -For \code{plot.igraph} and integer values, the default igraph palette is -used (see the \sQuote{palette} parameter below. Note that this is different -from the R palette. +The fill color of the vertex. +If it is numeric then the current palette is used, see \code{\link[grDevices:palette]{grDevices::palette()}}. +If it is a character vector then it may either contain integer values, named colors or RGB specified colors with three or four bytes. +All strings starting with \sQuote{\code{#}} are assumed to be RGB color specifications. +It is possible to mix named color and RGB colors. +Note that \code{\link[=tkplot]{tkplot()}} ignores the fourth byte (alpha channel) in the RGB color specification. + +For \code{plot.igraph} and integer values, the default igraph palette is used (see the \sQuote{palette} parameter below. +Note that this is different from the R palette. If you don't want (some) vertices to have any color, supply \code{NA} as the color name. @@ -135,23 +118,16 @@ By default it is \dQuote{black}. The width of the frame of the vertices. The default value is 1. } \item{shape}{ -The shape of the vertex, currently \dQuote{\code{circle}}, -\dQuote{\code{square}}, \dQuote{\code{csquare}}, \dQuote{\code{rectangle}}, -\dQuote{\code{crectangle}}, \dQuote{\code{vrectangle}}, \dQuote{\code{pie}} -(see \code{\link[=vertex.shape.pie]{vertex.shape.pie()}}), \sQuote{\code{sphere}}, and -\dQuote{\code{none}} are supported, and only by the -\code{\link[=plot.igraph]{plot.igraph()}} command. \dQuote{\code{none}} does not draw the -vertices at all, although vertex label are plotted (if given). See -\code{\link[=shapes]{shapes()}} for details about vertex shapes and -\code{\link[=vertex.shape.pie]{vertex.shape.pie()}} for using pie charts as vertices. - -The \dQuote{\code{sphere}} vertex shape plots vertices as 3D ray-traced -spheres, in the given color and size. This produces a raster image and it is -only supported with some graphics devices. On some devices raster -transparency is not supported and the spheres do not have a transparent -background. See \link{dev.capabilities} and the -\sQuote{\code{rasterImage}} capability to check that your device is -supported. +The shape of the vertex, currently \dQuote{\code{circle}}, \dQuote{\code{square}}, \dQuote{\code{csquare}}, \dQuote{\code{rectangle}}, +\dQuote{\code{crectangle}}, \dQuote{\code{vrectangle}}, \dQuote{\code{pie}} (see \code{\link[=vertex.shape.pie]{vertex.shape.pie()}}), \sQuote{\code{sphere}}, +and \dQuote{\code{none}} are supported, and only by the \code{\link[=plot.igraph]{plot.igraph()}} command. +\dQuote{\code{none}} does not draw the vertices at all, although vertex label are plotted (if given). +See \code{\link[=shapes]{shapes()}} for details about vertex shapes and \code{\link[=vertex.shape.pie]{vertex.shape.pie()}} for using pie charts as vertices. + +The \dQuote{\code{sphere}} vertex shape plots vertices as 3D ray-traced spheres, in the given color and size. +This produces a raster image and it is only supported with some graphics devices. +On some devices raster transparency is not supported and the spheres do not have a transparent background. +See \link{dev.capabilities} and the \sQuote{\code{rasterImage}} capability to check that your device is supported. By default vertices are drawn as circles. } @@ -160,28 +136,24 @@ The vertex labels. They will be converted to character. Specify \code{NA} to omit vertex labels. The default vertex labels are the vertex IDs. } \item{label.family}{ -The -font family to be used for vertex labels. As different plotting commands -can used different fonts, they interpret this parameter different ways. The -basic notation is, however, understood by both \code{\link[=plot.igraph]{plot.igraph()}} and -\code{\link[=tkplot]{tkplot()}}. \code{\link[=rglplot]{rglplot()}} does not support fonts at all -right now, it ignores this parameter completely. +The font family to be used for vertex labels. +As different plotting commands can used different fonts, they interpret this parameter different ways. +The basic notation is, however, understood by both \code{\link[=plot.igraph]{plot.igraph()}} and \code{\link[=tkplot]{tkplot()}}. +\code{\link[=rglplot]{rglplot()}} does not support fonts at all right now, it ignores this parameter completely. For \code{\link[=plot.igraph]{plot.igraph()}} this parameter is simply passed to \code{\link[graphics:text]{graphics::text()}} as argument \code{family}. -For \code{\link[=tkplot]{tkplot()}} some conversion is performed. If this parameter is -the name of an existing Tk font, then that font is used and the -\code{label.font} and \code{label.cex} parameters are ignored completely. If -it is one of the base families (serif, sans, mono) then Times, Helvetica or -Courier fonts are used, there are guaranteed to exist on all systems. For -the \sQuote{symbol} base family we used the symbol font is available, -otherwise the first font which has \sQuote{symbol} in its name. If the -parameter is not a name of the base families and it is also not a named Tk -font then we pass it to \code{\link[tcltk:tkfont.create]{tcltk::tkfont.create()}} and hope the user -knows what she is doing. The \code{label.font} and \code{label.cex} -parameters are also passed to \code{\link[tcltk:tkfont.create]{tcltk::tkfont.create()}} in this -case. +For \code{\link[=tkplot]{tkplot()}} some conversion is performed. +If this parameter is the name of an existing Tk font, then that font is used and the \code{label.font} +and \code{label.cex} parameters are ignored completely. +If it is one of the base families (serif, sans, mono) then Times, Helvetica or Courier fonts are used, +there are guaranteed to exist on all systems. +For the \sQuote{symbol} base family we used the symbol font is available, otherwise the first font +which has \sQuote{symbol} in its name. +If the parameter is not a name of the base families and it is also not a named Tk font then we pass it to \code{\link[tcltk:tkfont.create]{tcltk::tkfont.create()}} +and hope the user knows what she is doing. +The \code{label.font} and \code{label.cex} parameters are also passed to \code{\link[tcltk:tkfont.create]{tcltk::tkfont.create()}} in this case. The default value is \sQuote{serif}. } @@ -246,18 +218,16 @@ If FALSE, \code{vertex.size} and \code{vertex.size2} are used as is. If TRUE, \code{relative.size} is used to scale both appropriately with \code{relative.size}. } \item{relative.size}{ -The relative size of the smallest and largest vertices as percentage of -the plotting region. When all vertices have the same size, then by default -the relative size observed in the plot will be equal to -\code{relative.size[2]}. +The relative size of the smallest and largest vertices as percentage of the plotting region. +When all vertices have the same size, then by default the relative size observed in the plot will be equal to \code{relative.size[2]}. The default value is \code{c(.01,.025)} (1\\% and 2.5\\% respectively). Only used if \code{size.scaling} is TRUE`. } } -Edge parameters require to add the \sQuote{\code{edge.}} prefix when used as -arguments or set by \code{\link[=igraph_options]{igraph_options()}}. The edge parameters: +Edge parameters require to add the \sQuote{\code{edge.}} prefix when used as arguments or set by \code{\link[=igraph_options]{igraph_options()}}. +The edge parameters: \describe{ \item{color}{ The color of the edges, see the \code{color} vertex parameter for the possible values. @@ -273,12 +243,10 @@ The size of the arrows. The default value is 1. The width of the arrows. The default value is 1. } \item{lty}{ -The line type for the edges. Almost the -same format is accepted as for the standard graphics -\code{\link[graphics:par]{graphics::par()}}, 0 and \dQuote{blank} mean no edges, 1 and -\dQuote{solid} are for solid lines, the other possible values are: 2 -(\dQuote{dashed}), 3 (\dQuote{dotted}), 4 (\dQuote{dotdash}), 5 -(\dQuote{longdash}), 6 (\dQuote{twodash}). +The line type for the edges. +Almost the same format is accepted as for the standard graphics \code{\link[graphics:par]{graphics::par()}}, 0 and \dQuote{blank} mean no edges, 1 +and \dQuote{solid} are for solid lines, the other possible values are: 2 (\dQuote{dashed}), 3 (\dQuote{dotted}), 4 (\dQuote{dotdash}), +5 (\dQuote{longdash}), 6 (\dQuote{twodash}). \code{\link[=tkplot]{tkplot()}} also accepts standard Tk line type strings, it does not however support \dQuote{blank} lines, instead of type \sQuote{0} type diff --git a/man/plot.igraph.Rd b/man/plot.igraph.Rd index a2eb1a656ba..6cafda56de9 100644 --- a/man/plot.igraph.Rd +++ b/man/plot.igraph.Rd @@ -26,64 +26,54 @@ \item{axes}{Logical, whether to plot axes, defaults to FALSE.} -\item{add}{Logical, whether to add the plot to the current device, or -delete the device's current contents first.} - -\item{xlim}{The limits for the horizontal axis, it is unlikely that you want -to modify this.} - -\item{ylim}{The limits for the vertical axis, it is unlikely that you want -to modify this.} - -\item{mark.groups}{A list of vertex ID vectors. It is interpreted as a set -of vertex groups. Each vertex group is highlighted, by plotting a colored -smoothed polygon around and \dQuote{under} it. See the arguments below to -control the look of the polygons.} - -\item{mark.shape}{A numeric scalar or vector. Controls the smoothness of the -vertex group marking polygons. This is basically the \sQuote{shape} -parameter of the \code{\link[graphics:xspline]{graphics::xspline()}} function, its possible -values are between -1 and 1. If it is a vector, then a different value is -used for the different vertex groups.} - -\item{mark.col}{A scalar or vector giving the colors of marking the -polygons, in any format accepted by \code{\link[graphics:xspline]{graphics::xspline()}}; e.g. -numeric color IDs, symbolic color names, or colors in RGB. The default -\code{NULL} uses semi-transparent rainbow colors.} - -\item{mark.border}{A scalar or vector giving the colors of the borders of -the vertex group marking polygons. If it is \code{NA}, then no border is -drawn. The default \code{NULL} uses rainbow colors.} - -\item{mark.expand}{A numeric scalar or vector, the size of the border around -the marked vertex groups. It is in the same units as the vertex sizes. If a -vector is given, then different values are used for the different vertex -groups.} - -\item{mark.lwd}{A numeric scalar or vector, the linewidth of the border around -the marked vertex groups. If a -vector is given, then different values are used for the different vertex -groups.} - -\item{loop.size}{A numeric scalar that allows the user to scale the loop edges -of the network. The default loop size is 1. Larger values will produce larger -loops.} - -\item{\dots}{Additional plotting parameters. See \link{igraph.plotting} for -the complete list.} +\item{add}{Logical, whether to add the plot to the current device, or delete the device's current contents first.} + +\item{xlim}{The limits for the horizontal axis, it is unlikely that you want to modify this.} + +\item{ylim}{The limits for the vertical axis, it is unlikely that you want to modify this.} + +\item{mark.groups}{A list of vertex ID vectors. +It is interpreted as a set of vertex groups. +Each vertex group is highlighted, by plotting a colored smoothed polygon around and \dQuote{under} it. +See the arguments below to control the look of the polygons.} + +\item{mark.shape}{A numeric scalar or vector. +Controls the smoothness of the vertex group marking polygons. +This is basically the \sQuote{shape} parameter of the \code{\link[graphics:xspline]{graphics::xspline()}} function, +its possible values are between -1 and 1. If it is a vector, then a different value is used for the different vertex groups.} + +\item{mark.col}{A scalar or vector giving the colors of marking the polygons, in any format accepted by \code{\link[graphics:xspline]{graphics::xspline()}}; +e.g. numeric color IDs, symbolic color names, or colors in RGB. +The default \code{NULL} uses semi-transparent rainbow colors.} + +\item{mark.border}{A scalar or vector giving the colors of the borders of the vertex group marking polygons. +If it is \code{NA}, then no border is drawn. +The default \code{NULL} uses rainbow colors.} + +\item{mark.expand}{A numeric scalar or vector, the size of the border around the marked vertex groups. +It is in the same units as the vertex sizes. +If a vector is given, then different values are used for the different vertex groups.} + +\item{mark.lwd}{A numeric scalar or vector, the linewidth of the border around the marked vertex groups. +If a vector is given, +then different values are used for the different vertex groups.} + +\item{loop.size}{A numeric scalar that allows the user to scale the loop edges of the network. +The default loop size is 1. Larger values will produce larger loops.} + +\item{\dots}{Additional plotting parameters. +See \link{igraph.plotting} for the complete list.} } \value{ Returns \code{NULL}, invisibly. } \description{ -\code{plot.igraph()} is able to plot graphs to any R device. It is the -non-interactive companion of the \code{tkplot()} function. +\code{plot.igraph()} is able to plot graphs to any R device. +It is the non-interactive companion of the \code{tkplot()} function. } \details{ -One convenient way to plot graphs is to plot with \code{\link[=tkplot]{tkplot()}} -first, handtune the placement of the vertices, query the coordinates by the -\code{\link[=tk_coords]{tk_coords()}} function and use them with \code{\link[=plot]{plot()}} to -plot the graph to any R device. +One convenient way to plot graphs is to plot with \code{\link[=tkplot]{tkplot()}} first, handtune the placement of the vertices, +query the coordinates by the \code{\link[=tk_coords]{tk_coords()}} function and use them with \code{\link[=plot]{plot()}} to plot the graph to any R device. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_edgelist}{\code{get_edgelist()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_incident}{\code{incident()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_loop}{\code{is_loop()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_is_directed}{\code{is_directed()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Nongraph.html#igraph_convex_hull_2d}{\code{convex_hull_2d()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}} @@ -97,9 +87,7 @@ plot(g, layout = layout_with_kk, vertex.color = "green") } \seealso{ \code{\link[=layout]{layout()}} for different layouts, -\link{igraph.plotting} for the detailed description of the plotting -parameters and \code{\link[=tkplot]{tkplot()}} and \code{\link[=rglplot]{rglplot()}} for other -graph plotting functions. +\link{igraph.plotting} for the detailed description of the plotting parameters and \code{\link[=tkplot]{tkplot()}} and \code{\link[=rglplot]{rglplot()}} for other graph plotting functions. Other plot: \code{\link[=rglplot]{rglplot()}} diff --git a/man/plot.sir.Rd b/man/plot.sir.Rd index 7e3982742d2..be37bd2a357 100644 --- a/man/plot.sir.Rd +++ b/man/plot.sir.Rd @@ -23,11 +23,10 @@ ) } \arguments{ -\item{x}{The output of the SIR simulation, coming from the \code{\link[=sir]{sir()}} -function.} +\item{x}{The output of the SIR simulation, coming from the \code{\link[=sir]{sir()}} function.} -\item{comp}{Character scalar, which component to plot. Either \sQuote{NI} -(infected, default), \sQuote{NS} (susceptible) or \sQuote{NR} (recovered).} +\item{comp}{Character scalar, which component to plot. +Either \sQuote{NI} (infected, default), \sQuote{NS} (susceptible) or \sQuote{NR} (recovered).} \item{median}{Logical, whether to plot the (binned) median.} @@ -37,8 +36,8 @@ function.} \item{median_color}{Color of the median curve.} -\item{quantile_color}{Color(s) of the quantile curves. (It is recycled if -needed and non-needed entries are ignored if too long.)} +\item{quantile_color}{Color(s) of the quantile curves. +(It is recycled if needed and non-needed entries are ignored if too long.)} \item{lwd.median}{Line width of the median.} @@ -46,30 +45,27 @@ needed and non-needed entries are ignored if too long.)} \item{lty.quantile}{Line type of the quantile curves.} -\item{xlim}{The x limits, a two-element numeric vector. If \code{NULL}, then -it is calculated from the data.} +\item{xlim}{The x limits, a two-element numeric vector. +If \code{NULL}, then it is calculated from the data.} -\item{ylim}{The y limits, a two-element numeric vector. If \code{NULL}, then -it is calculated from the data.} +\item{ylim}{The y limits, a two-element numeric vector. +If \code{NULL}, then it is calculated from the data.} \item{xlab}{The x label.} -\item{ylab}{The y label. If \code{NULL} then it is automatically added based -on the \code{comp} argument.} +\item{ylab}{The y label. +If \code{NULL} then it is automatically added based on the \code{comp} argument.} -\item{\dots}{Additional arguments are passed to \code{\link[=plot]{plot()}}, that is run -before any of the curves are added, to create the figure.} +\item{\dots}{Additional arguments are passed to \code{\link[=plot]{plot()}}, that is run before any of the curves are added, to create the figure.} } \value{ Nothing. } \description{ -This function can conveniently plot the results of multiple SIR model -simulations. +This function can conveniently plot the results of multiple SIR model simulations. } \details{ -The number of susceptible/infected/recovered individuals is plotted over -time, for multiple simulations. +The number of susceptible/infected/recovered individuals is plotted over time, for multiple simulations. } \examples{ diff --git a/man/plotHierarchy.Rd b/man/plotHierarchy.Rd index e3318d8ad20..b48227c2a3d 100644 --- a/man/plotHierarchy.Rd +++ b/man/plotHierarchy.Rd @@ -11,20 +11,18 @@ plotHierarchy( ) } \arguments{ -\item{layout}{The layout of a plot, it is simply passed on to -\code{plot.igraph()}, see the possible formats there. The default \code{NULL} uses -the Reingold-Tilford layout generator.} +\item{layout}{The layout of a plot, it is simply passed on to \code{plot.igraph()}, see the possible formats there. +The default \code{NULL} uses the Reingold-Tilford layout generator.} -\item{...}{Additional arguments. \code{plot_hierarchy()} and \code{\link[=plot]{plot()}} pass -them to \code{plot.igraph()}. \code{\link[=print]{print()}} and \code{\link[=summary]{summary()}} ignore them. -\code{cohesive_blocks()} and \code{export_pajek()} do not accept extra arguments; -these dots must be empty for them.} +\item{...}{Additional arguments. +\code{plot_hierarchy()} and \code{\link[=plot]{plot()}} pass them to \code{plot.igraph()}. +\code{\link[=print]{print()}} and \code{\link[=summary]{summary()}} ignore them. +\code{cohesive_blocks()} and \code{export_pajek()} do not accept extra arguments; these dots must be empty for them.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{plotHierarchy()} was renamed to \code{\link[=plot_hierarchy]{plot_hierarchy()}} to create a more -consistent API. +\code{plotHierarchy()} was renamed to \code{\link[=plot_hierarchy]{plot_hierarchy()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/plot_dendrogram.communities.Rd b/man/plot_dendrogram.communities.Rd index 0b8bc7f9ffb..ebdb13ccb77 100644 --- a/man/plot_dendrogram.communities.Rd +++ b/man/plot_dendrogram.communities.Rd @@ -16,17 +16,16 @@ plot_dendrogram(x, mode = NULL, ...) ) } \arguments{ -\item{x}{An object containing the community structure of a graph. See -\code{\link[=communities]{communities()}} for details.} +\item{x}{An object containing the community structure of a graph. +See \code{\link[=communities]{communities()}} for details.} -\item{mode}{Which dendrogram plotting function to use. See details below. +\item{mode}{Which dendrogram plotting function to use. +See details below. The default \code{NULL} uses the \code{dend.plot.type} igraph option.} -\item{\dots}{Additional arguments to supply to the dendrogram plotting -function.} +\item{\dots}{Additional arguments to supply to the dendrogram plotting function.} -\item{use.modularity}{Logical, whether to use the modularity values -to define the height of the branches.} +\item{use.modularity}{Logical, whether to use the modularity values to define the height of the branches.} \item{palette}{The color palette to use for colored plots.} } @@ -38,19 +37,18 @@ Returns whatever the return value was from the plotting function, Plot a hierarchical community structure as a dendrogram. } \details{ -\code{plot_dendrogram()} supports three different plotting functions, selected via -the \code{mode} argument. By default the plotting function is taken from the -\code{dend.plot.type} igraph option, and it has for possible values: +\code{plot_dendrogram()} supports three different plotting functions, selected via the \code{mode} argument. +By default the plotting function is taken from the \code{dend.plot.type} igraph option, and it has for possible values: \itemize{ \item \code{auto} Choose automatically between the plotting -functions. As \code{plot.phylo} is the most sophisticated, that is choosen, -whenever the \code{ape} package is available. Otherwise \code{plot.hclust} -is used. \item \code{phylo} Use \code{plot.phylo} from the \code{ape} -package. \item \code{hclust} Use \code{plot.hclust} from the \code{stats} -package. \item \code{dendrogram} Use \code{plot.dendrogram} from the -\code{stats} package. } +functions. +As \code{plot.phylo} is the most sophisticated, that is choosen, whenever the \code{ape} package is available. +Otherwise \code{plot.hclust} is used. +\item \code{phylo} Use \code{plot.phylo} from the \code{ape} package. +\item \code{hclust} Use \code{plot.hclust} from the \code{stats} package. +\item \code{dendrogram} Use \code{plot.dendrogram} from the \code{stats} package. } -The different plotting functions take different sets of arguments. When -using \code{plot.phylo} (\code{mode="phylo"}), we have the following syntax: +The different plotting functions take different sets of arguments. +When using \code{plot.phylo} (\code{mode="phylo"}), we have the following syntax: \preformatted{ plot_dendrogram(x, mode="phylo", colbar = palette(), edge.color = NULL, use.edge.length = FALSE, \dots) @@ -67,24 +65,16 @@ The syntax for \code{plot.hclust} (\code{mode="hclust"}): \preformatted{ hang = 0.01, ann = FALSE, main = "", sub = "", xlab = "", ylab = "", \dots) } The extra arguments not documented above: \itemize{ -\item \code{rect} A numeric scalar, the number of groups to mark on -the dendrogram. The dendrogram is cut into exactly \code{rect} -groups and they are marked via the \code{rect.hclust} command. Set -this to zero if you don't want to mark any groups. -\item \code{colbar} The colors of the rectangles that mark the -vertex groups via the \code{rect} argument. -\item \code{hang} Where to put the leaf nodes, this corresponds to the -\code{hang} argument of \code{plot.hclust}. -\item \code{ann} Whether to annotate the plot, the \code{ann} -argument of \code{plot.hclust}. -\item \code{main} The main title of the plot, the \code{main} argument -of \code{plot.hclust}. -\item \code{sub} The sub-title of the plot, the \code{sub} argument of -\code{plot.hclust}. -\item \code{xlab} The label on the horizontal axis, passed to -\code{plot.hclust}. -\item \code{ylab} The label on the vertical axis, passed to -\code{plot.hclust}. +\item \code{rect} A numeric scalar, the number of groups to mark on the dendrogram. +The dendrogram is cut into exactly \code{rect} groups and they are marked via the \code{rect.hclust} command. +Set this to zero if you don't want to mark any groups. +\item \code{colbar} The colors of the rectangles that mark the vertex groups via the \code{rect} argument. +\item \code{hang} Where to put the leaf nodes, this corresponds to the \code{hang} argument of \code{plot.hclust}. +\item \code{ann} Whether to annotate the plot, the \code{ann} argument of \code{plot.hclust}. +\item \code{main} The main title of the plot, the \code{main} argument of \code{plot.hclust}. +\item \code{sub} The sub-title of the plot, the \code{sub} argument of \code{plot.hclust}. +\item \code{xlab} The label on the horizontal axis, passed to \code{plot.hclust}. +\item \code{ylab} The label on the vertical axis, passed to \code{plot.hclust}. \item \code{dots} Attitional arguments to pass to \code{plot.hclust}. } diff --git a/man/plot_dendrogram.igraphHRG.Rd b/man/plot_dendrogram.igraphHRG.Rd index caf346887db..32015cc06cf 100644 --- a/man/plot_dendrogram.igraphHRG.Rd +++ b/man/plot_dendrogram.igraphHRG.Rd @@ -7,14 +7,13 @@ \method{plot_dendrogram}{igraphHRG}(x, mode = NULL, ...) } \arguments{ -\item{x}{An \code{igraphHRG}, a hierarchical random graph, as returned by -the \code{\link[=fit_hrg]{fit_hrg()}} function.} +\item{x}{An \code{igraphHRG}, a hierarchical random graph, as returned by the \code{\link[=fit_hrg]{fit_hrg()}} function.} -\item{mode}{Which dendrogram plotting function to use. See details below. +\item{mode}{Which dendrogram plotting function to use. +See details below. The default \code{NULL} uses the \code{dend.plot.type} igraph option.} -\item{\dots}{Additional arguments to supply to the dendrogram plotting -function.} +\item{\dots}{Additional arguments to supply to the dendrogram plotting function.} } \value{ Returns whatever the return value was from the plotting function, @@ -24,19 +23,18 @@ Returns whatever the return value was from the plotting function, Plot a hierarchical random graph as a dendrogram. } \details{ -\code{plot_dendrogram()} supports three different plotting functions, selected via -the \code{mode} argument. By default the plotting function is taken from the -\code{dend.plot.type} igraph option, and it has for possible values: +\code{plot_dendrogram()} supports three different plotting functions, selected via the \code{mode} argument. +By default the plotting function is taken from the \code{dend.plot.type} igraph option, and it has for possible values: \itemize{ \item \code{auto} Choose automatically between the plotting -functions. As \code{plot.phylo} is the most sophisticated, that is choosen, -whenever the \code{ape} package is available. Otherwise \code{plot.hclust} -is used. \item \code{phylo} Use \code{plot.phylo} from the \code{ape} -package. \item \code{hclust} Use \code{plot.hclust} from the \code{stats} -package. \item \code{dendrogram} Use \code{plot.dendrogram} from the -\code{stats} package. } +functions. +As \code{plot.phylo} is the most sophisticated, that is choosen, whenever the \code{ape} package is available. +Otherwise \code{plot.hclust} is used. +\item \code{phylo} Use \code{plot.phylo} from the \code{ape} package. +\item \code{hclust} Use \code{plot.hclust} from the \code{stats} package. +\item \code{dendrogram} Use \code{plot.dendrogram} from the \code{stats} package. } -The different plotting functions take different sets of arguments. When -using \code{plot.phylo} (\code{mode="phylo"}), we have the following syntax: +The different plotting functions take different sets of arguments. +When using \code{plot.phylo} (\code{mode="phylo"}), we have the following syntax: \preformatted{ plot_dendrogram(x, mode="phylo", colbar = rainbow(11, start=0.7, end=0.1), edge.color = NULL, use.edge.length = FALSE, \dots) @@ -53,24 +51,16 @@ The syntax for \code{plot.hclust} (\code{mode="hclust"}): \preformatted{ hang = 0.01, ann = FALSE, main = "", sub = "", xlab = "", ylab = "", \dots) } The extra arguments not documented above: \itemize{ -\item \code{rect} A numeric scalar, the number of groups to mark on -the dendrogram. The dendrogram is cut into exactly \code{rect} -groups and they are marked via the \code{rect.hclust} command. Set -this to zero if you don't want to mark any groups. -\item \code{colbar} The colors of the rectangles that mark the -vertex groups via the \code{rect} argument. -\item \code{hang} Where to put the leaf nodes, this corresponds to the -\code{hang} argument of \code{plot.hclust}. -\item \code{ann} Whether to annotate the plot, the \code{ann} argument -of \code{plot.hclust}. -\item \code{main} The main title of the plot, the \code{main} argument -of \code{plot.hclust}. -\item \code{sub} The sub-title of the plot, the \code{sub} argument of -\code{plot.hclust}. -\item \code{xlab} The label on the horizontal axis, passed to -\code{plot.hclust}. -\item \code{ylab} The label on the vertical axis, passed to -\code{plot.hclust}. +\item \code{rect} A numeric scalar, the number of groups to mark on the dendrogram. +The dendrogram is cut into exactly \code{rect} groups and they are marked via the \code{rect.hclust} command. +Set this to zero if you don't want to mark any groups. +\item \code{colbar} The colors of the rectangles that mark the vertex groups via the \code{rect} argument. +\item \code{hang} Where to put the leaf nodes, this corresponds to the \code{hang} argument of \code{plot.hclust}. +\item \code{ann} Whether to annotate the plot, the \code{ann} argument of \code{plot.hclust}. +\item \code{main} The main title of the plot, the \code{main} argument of \code{plot.hclust}. +\item \code{sub} The sub-title of the plot, the \code{sub} argument of \code{plot.hclust}. +\item \code{xlab} The label on the horizontal axis, passed to \code{plot.hclust}. +\item \code{ylab} The label on the vertical axis, passed to \code{plot.hclust}. \item \code{dots} Attitional arguments to pass to \code{plot.hclust}. } diff --git a/man/plus-.igraph.Rd b/man/plus-.igraph.Rd index 4340a102477..9c36681ea5a 100644 --- a/man/plus-.igraph.Rd +++ b/man/plus-.igraph.Rd @@ -7,8 +7,7 @@ \method{+}{igraph}(e1, e2) } \arguments{ -\item{e1}{First argument, probably an igraph graph, but see details -below.} +\item{e1}{First argument, probably an igraph graph, but see details below.} \item{e2}{Second argument, see details below.} } @@ -17,8 +16,7 @@ Add vertices, edges or another graph to a graph } \details{ The plus operator can be used to add vertices or edges to graph. -The actual operation that is performed depends on the type of the -right hand side argument. +The actual operation that is performed depends on the type of the right hand side argument. \itemize{ \item If is is another igraph graph object and they are both named graphs, then the union of the two graphs are calculated, @@ -31,11 +29,9 @@ are added to the graph. \item If it is a character scalar or vector, then it is interpreted as the names of the vertices to add to the graph. \item If it is an object created with the \code{\link[=vertex]{vertex()}} or -\code{\link[=vertices]{vertices()}} function, then new vertices are added to the -graph. This form is appropriate when one wants to add some vertex -attributes as well. The operands of the \code{vertices()} function -specifies the number of vertices to add and their attributes as -well. +\code{\link[=vertices]{vertices()}} function, then new vertices are added to the graph. +This form is appropriate when one wants to add some vertex attributes as well. +The operands of the \code{vertices()} function specifies the number of vertices to add and their attributes as well. The unnamed arguments of \code{vertices()} are concatenated and used as the \sQuote{\code{name}} vertex attribute (i.e. vertex @@ -46,17 +42,14 @@ attributes. Examples: \preformatted{ g <- g + g <- g + vertex("bar", "foobar") g <- g + vertices("bar2", "foobar2", color=1:2, shape="rectangle")} -\code{vertex()} is just an alias to \code{vertices()}, and it is -provided for readability. The user should use it if a single vertex -is added to the graph. +\code{vertex()} is just an alias to \code{vertices()}, and it is provided for readability. +The user should use it if a single vertex is added to the graph. \item If it is an object created with the \code{\link[=edge]{edge()}} or -\code{\link[=edges]{edges()}} function, then new edges will be added to the -graph. The new edges and possibly their attributes can be specified as -the arguments of the \code{edges()} function. +\code{\link[=edges]{edges()}} function, then new edges will be added to the graph. +The new edges and possibly their attributes can be specified as the arguments of the \code{edges()} function. -The unnamed arguments of \code{edges()} are concatenated and used -as vertex IDs of the end points of the new edges. The named -arguments will be added as edge attributes. +The unnamed arguments of \code{edges()} are concatenated and used as vertex IDs of the end points of the new edges. +The named arguments will be added as edge attributes. Examples: \preformatted{ g <- make_empty_graph() + vertices(letters[1:10]) + @@ -66,15 +59,13 @@ Examples: \preformatted{ g <- make_empty_graph() + g <- g + edges(c("bar", "foo", "foobar2", "bar2"), color="red", weight=1:2)} See more examples below. -\code{edge()} is just an alias to \code{edges()} and it is provided -for readability. The user should use it if a single edge is added to -the graph. +\code{edge()} is just an alias to \code{edges()} and it is provided for readability. +The user should use it if a single edge is added to the graph. \item If it is an object created with the \code{\link[=path]{path()}} function, then -new edges that form a path are added. The edges and possibly their -attributes are specified as the arguments to the \code{path()} -function. The non-named arguments are concatenated and interpreted -as the vertex IDs along the path. The remaining arguments are added -as edge attributes. +new edges that form a path are added. +The edges and possibly their attributes are specified as the arguments to the \code{path()} function. +The non-named arguments are concatenated and interpreted as the vertex IDs along the path. +The remaining arguments are added as edge attributes. Examples: \preformatted{ g <- make_empty_graph() + vertices(letters[1:10]) g <- g + path("a", "b", "c", "d") diff --git a/man/power.law.fit.Rd b/man/power.law.fit.Rd index 07170f5079c..cc033df6e5a 100644 --- a/man/power.law.fit.Rd +++ b/man/power.law.fit.Rd @@ -14,39 +14,37 @@ power.law.fit( ) } \arguments{ -\item{x}{The data to fit, a numeric vector. For implementation -\sQuote{\code{R.mle}} the data must be integer values. For the -\sQuote{\code{plfit}} implementation non-integer values might be present and -then a continuous power-law distribution is fitted.} +\item{x}{The data to fit, a numeric vector. +For implementation \sQuote{\code{R.mle}} the data must be integer values. +For the \sQuote{\code{plfit}} implementation non-integer values might be present and then a continuous power-law distribution is fitted.} -\item{xmin}{Numeric scalar, or \code{NULL}. The lower bound for fitting the -power-law. If \code{NULL}, the smallest value in \code{x} will be used for -the \sQuote{\code{R.mle}} implementation, and its value will be -automatically determined for the \sQuote{\code{plfit}} implementation. This -argument makes it possible to fit only the tail of the distribution.} +\item{xmin}{Numeric scalar, or \code{NULL}. +The lower bound for fitting the power-law. +If \code{NULL}, the smallest value in \code{x} will be used for the \sQuote{\code{R.mle}} implementation, +and its value will be automatically determined for the \sQuote{\code{plfit}} implementation. +This argument makes it possible to fit only the tail of the distribution.} -\item{start}{Numeric scalar. The initial value of the exponent for the -minimizing function, for the \sQuote{\code{R.mle}} implementation. Usually -it is safe to leave this untouched.} +\item{start}{Numeric scalar. +The initial value of the exponent for the minimizing function, for the \sQuote{\code{R.mle}} implementation. +Usually it is safe to leave this untouched.} -\item{force.continuous}{Logical. Whether to force a continuous -distribution for the \sQuote{\code{plfit}} implementation, even if the -sample vector contains integer values only (by chance). If this argument is -false, igraph will assume a continuous distribution if at least one sample -is non-integer and assume a discrete distribution otherwise.} +\item{force.continuous}{Logical. +Whether to force a continuous distribution for the \sQuote{\code{plfit}} implementation, +even if the sample vector contains integer values only (by chance). +If this argument is false, +igraph will assume a continuous distribution if at least one sample is non-integer and assume a discrete distribution otherwise.} -\item{implementation}{Character scalar. Which implementation to use. See -details below.} +\item{implementation}{Character scalar. +Which implementation to use. +See details below.} -\item{...}{Additional arguments, passed to the maximum likelihood -optimizing function, \code{\link[stats4:mle]{stats4::mle()}}, if the \sQuote{\code{R.mle}} -implementation is chosen. It is ignored by the \sQuote{\code{plfit}} -implementation.} +\item{...}{Additional arguments, passed to the maximum likelihood optimizing function, \code{\link[stats4:mle]{stats4::mle()}}, +if the \sQuote{\code{R.mle}} implementation is chosen. +It is ignored by the \sQuote{\code{plfit}} implementation.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{power.law.fit()} was renamed to \code{\link[=fit_power_law]{fit_power_law()}} to create a more -consistent API. +\code{power.law.fit()} was renamed to \code{\link[=fit_power_law]{fit_power_law()}} to create a more consistent API. } \keyword{internal} diff --git a/man/power_centrality.Rd b/man/power_centrality.Rd index 7bd3a990d65..4b9233cf233 100644 --- a/man/power_centrality.Rd +++ b/man/power_centrality.Rd @@ -19,104 +19,92 @@ power_centrality( \arguments{ \item{graph}{the input graph.} -\item{nodes}{vertex sequence indicating which vertices are to be included in -the calculation. The default \code{NULL} selects all vertices.} +\item{nodes}{vertex sequence indicating which vertices are to be included in the calculation. +The default \code{NULL} selects all vertices.} \item{...}{These dots are for future extensions and must be empty.} -\item{loops}{Logical indicating whether or not the diagonal should be -treated as valid data. Set this true if and only if the data can contain -loops. \code{loops} is \code{FALSE} by default.} +\item{loops}{Logical indicating whether or not the diagonal should be treated as valid data. +Set this true if and only +if the data can contain loops. +\code{loops} is \code{FALSE} by default.} -\item{exponent}{exponent (decay rate) for the Bonacich power centrality -score; can be negative} +\item{exponent}{exponent (decay rate) for the Bonacich power centrality score; can be negative} -\item{rescale}{if true, centrality scores are rescaled such that they sum to -1.} +\item{rescale}{if true, centrality scores are rescaled such that they sum to 1.} -\item{tol}{tolerance for near-singularities during matrix inversion (see -\code{\link[Matrix:solve]{Matrix::solve()}})} +\item{tol}{tolerance for near-singularities during matrix inversion (see \code{\link[Matrix:solve]{Matrix::solve()}})} -\item{sparse}{Logical, whether to use sparse matrices for the -calculation. The \sQuote{Matrix} package is required for sparse matrix -support} +\item{sparse}{Logical, whether to use sparse matrices for the calculation. +The \sQuote{Matrix} package is required for sparse matrix support} \item{weights}{One of the following: \itemize{ -\item \code{NULL} (default): use the \code{weight} edge attribute if the graph has -one, otherwise return a traditional (unweighted) adjacency matrix. +\item \code{NULL} (default): use the \code{weight} edge attribute if the graph has one, +otherwise return a traditional (unweighted) adjacency matrix. \item \code{NA}: explicitly unweighted, ignoring any \code{weight} edge attribute. -\item A numeric or logical vector of length \code{\link[=ecount]{ecount()}}: use these values -directly as edge weights. -\item A character scalar: the name of an edge attribute whose values are -used as weights. The attribute must be numeric or logical. +\item A numeric or logical vector of length \code{\link[=ecount]{ecount()}}: use these values directly as edge weights. +\item A character scalar: the name of an edge attribute whose values are used as weights. +The attribute must be numeric or logical. } -If multiple edges share endpoints, the value of an arbitrarily chosen edge -is included in the matrix.} +If multiple edges share endpoints, the value of an arbitrarily chosen edge is included in the matrix.} } \value{ A vector, containing the centrality scores. } \description{ -\code{power_centrality()} takes a graph (\code{dat}) and returns the Boncich power -centralities of positions (selected by \code{nodes}). The decay rate for -power contributions is specified by \code{exponent} (1 by default). +\code{power_centrality()} takes a graph (\code{dat}) and returns the Boncich power centralities of positions (selected by \code{nodes}). +The decay rate for power contributions is specified by \code{exponent} (1 by default). } \details{ -Bonacich's power centrality measure is defined by -\eqn{C_{BP}\left(\alpha,\beta\right)=\alpha\left(\mathbf{I}-\beta\mathbf{A}\right)^{-1}\mathbf{A}\mathbf{1}}{C_BP(alpha,beta)=alpha +Bonacich's power centrality measure is defined by \eqn{C_{BP}\left(\alpha,\beta\right)=\alpha\left(\mathbf{I}-\beta\mathbf{A}\right)^{-1}\mathbf{A}\mathbf{1}}{C_BP(alpha,beta)=alpha (I-beta A)^-1 A 1}, where \eqn{\beta}{beta} is an attenuation parameter (set -here by \code{exponent}) and \eqn{\mathbf{A}}{A} is the graph adjacency -matrix. (The coefficient \eqn{\alpha}{alpha} acts as a scaling parameter, -and is set here (following Bonacich (1987)) such that the sum of squared -scores is equal to the number of vertices. This allows 1 to be used as a -reference value for the ``middle'' of the centrality range.) When -\eqn{\beta \rightarrow }{beta->1/lambda_A1}\eqn{ +here by \code{exponent}) and \eqn{\mathbf{A}}{A} is the graph adjacency matrix. +(The coefficient \eqn{\alpha}{alpha} acts as a scaling parameter, +and is set here (following Bonacich (1987)) such that the sum of squared scores is equal to the number of vertices. +This allows 1 to be used as a reference value for the ``middle'' of the centrality range.) +When \eqn{\beta \rightarrow }{beta->1/lambda_A1}\eqn{ 1/\lambda_{\mathbf{A}1}}{beta->1/lambda_A1} (the reciprocal of the largest -eigenvalue of \eqn{\mathbf{A}}{A}), this is to within a constant multiple of -the familiar eigenvector centrality score; for other values of \eqn{\beta}, -the behavior of the measure is quite different. In particular, \eqn{\beta} -gives positive and negative weight to even and odd walks, respectively, as -can be seen from the series expansion -\eqn{C_{BP}\left(\alpha,\beta\right)=\alpha \sum_{k=0}^\infty \beta^k +eigenvalue of \eqn{\mathbf{A}}{A}), this is to within a constant multiple of the familiar eigenvector centrality score; +for other values of \eqn{\beta}, the behavior of the measure is quite different. +In particular, +\eqn{\beta} gives positive and negative weight to even and odd walks, respectively, +as can be seen from the series expansion \eqn{C_{BP}\left(\alpha,\beta\right)=\alpha \sum_{k=0}^\infty \beta^k }{C_BP(alpha,beta) = alpha sum( beta^k A^(k+1) 1, k in 0..infinity )}\eqn{ \mathbf{A}^{k+1} \mathbf{1}}{C_BP(alpha,beta) = alpha sum( beta^k A^(k+1) 1, k in 0..infinity )} which converges so long as \eqn{|\beta| }{|beta|<1/lambda_A1}\eqn{ < 1/\lambda_{\mathbf{A}1}}{|beta|<1/lambda_A1}. -The magnitude of \eqn{\beta}{beta} controls the influence of distant actors -on ego's centrality score, with larger magnitudes indicating slower rates of -decay. (High rates, hence, imply a greater sensitivity to edge effects.) - -Interpretively, the Bonacich power measure corresponds to the notion that -the power of a vertex is recursively defined by the sum of the power of its -alters. The nature of the recursion involved is then controlled by the -power exponent: positive values imply that vertices become more powerful as -their alters become more powerful (as occurs in cooperative relations), -while negative values imply that vertices become more powerful only as their -alters become \emph{weaker} (as occurs in competitive or antagonistic -relations). The magnitude of the exponent indicates the tendency of the -effect to decay across long walks; higher magnitudes imply slower decay. -One interesting feature of this measure is its relative instability to -changes in exponent magnitude (particularly in the negative case). If your -theory motivates use of this measure, you should be very careful to choose a -decay parameter on a non-ad hoc basis. - -For directed networks, the Bonacich power measure can be understood as -similar to status in the network where higher status nodes have more edges -that point from them to others with status. Node A's centrality depends -on the centrality of all the nodes that A points toward, and their centrality -depends on the nodes they point toward, etc. Note, this means that a node -with an out-degree of 0 will have a Bonacich power centrality of 0 as they -do not point towards anyone. When using this with directed network it -is important to think about the edge direction and what it represents. +The magnitude of \eqn{\beta}{beta} controls the influence of distant actors on ego's centrality score, +with larger magnitudes indicating slower rates of decay. +(High rates, hence, imply a greater sensitivity to edge effects.) + +Interpretively, the Bonacich power measure corresponds to the notion +that the power of a vertex is recursively defined by the sum of the power of its alters. +The nature of the recursion involved is then controlled by the power exponent: +positive values imply that vertices become more powerful as their alters become more powerful (as occurs in cooperative relations), +while negative values imply that vertices become more powerful only +as their alters become \emph{weaker} (as occurs in competitive or antagonistic relations). +The magnitude of the exponent indicates the tendency of the effect to decay across long walks; +higher magnitudes imply slower decay. +One interesting feature of this measure is its relative instability to changes in exponent magnitude (particularly in the negative case). +If your theory motivates use of this measure, +you should be very careful to choose a decay parameter on a non-ad hoc basis. + +For directed networks, +the Bonacich power measure can be understood as similar to status in the network +where higher status nodes have more edges that point from them to others with status. +Node A's centrality depends on the centrality of all the nodes that A points toward, +and their centrality depends on the nodes they point toward, etc. Note, +this means that a node with an out-degree of 0 will have a Bonacich power centrality of 0 as they do not point towards anyone. +When using this with directed network it is important to think about the edge direction and what it represents. } \note{ This function was ported (i.e. copied) from the SNA package. } \section{Warning }{ Singular adjacency matrices cause no end of headaches for -this algorithm; thus, the routine may fail in certain cases. This will be -fixed when we get a better algorithm. +this algorithm; thus, the routine may fail in certain cases. +This will be fixed when we get a better algorithm. } \section{Related documentation in the C library}{ diff --git a/man/predict_edges.Rd b/man/predict_edges.Rd index 9690befd6ff..c46fef9be2a 100644 --- a/man/predict_edges.Rd +++ b/man/predict_edges.Rd @@ -14,24 +14,20 @@ predict_edges( ) } \arguments{ -\item{graph}{The graph to fit the model to. Edge directions are ignored in -directed graphs.} +\item{graph}{The graph to fit the model to. +Edge directions are ignored in directed graphs.} -\item{hrg}{A hierarchical random graph model, in the form of an -\code{igraphHRG} object. \code{predict_edges()} allow this to be -\code{NULL} as well, then a HRG is fitted to the graph first, from a -random starting point.} +\item{hrg}{A hierarchical random graph model, in the form of an \code{igraphHRG} object. +\code{predict_edges()} allow this to be \code{NULL} as well, then a HRG is fitted to the graph first, from a random starting point.} \item{...}{These dots are for future extensions and must be empty.} -\item{start}{Logical, whether to start the fitting/sampling from the -supplied \code{igraphHRG} object, or from a random starting point.} +\item{start}{Logical, whether to start the fitting/sampling from the supplied \code{igraphHRG} object, or from a random starting point.} -\item{num.samples}{Number of samples to use for consensus generation or -missing edge prediction.} +\item{num.samples}{Number of samples to use for consensus generation or missing edge prediction.} -\item{num.bins}{Number of bins for the edge probabilities. Give a higher -number for a more accurate prediction.} +\item{num.bins}{Number of bins for the edge probabilities. +Give a higher number for a more accurate prediction.} } \value{ A list with entries: @@ -48,12 +44,10 @@ The (supplied or fitted) hierarchical random graph model. } } \description{ -\code{predict_edges()} uses a hierarchical random graph model to predict -missing edges from a network. This is done by sampling hierarchical models -around the optimum model, proportionally to their likelihood. The MCMC -sampling is stated from \code{hrg()}, if it is given and the \code{start} -argument is set to \code{TRUE}. Otherwise a HRG is fitted to the graph -first. +\code{predict_edges()} uses a hierarchical random graph model to predict missing edges from a network. +This is done by sampling hierarchical models around the optimum model, proportionally to their likelihood. +The MCMC sampling is stated from \code{hrg()}, if it is given and the \code{start} argument is set to \code{TRUE}. +Otherwise a HRG is fitted to the graph first. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-HRG.html#igraph_hrg_predict}{\code{hrg_predict()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/preference.game.Rd b/man/preference.game.Rd index d55dea83770..70c948a38cd 100644 --- a/man/preference.game.Rd +++ b/man/preference.game.Rd @@ -19,19 +19,17 @@ preference.game( \item{types}{The number of different vertex types.} -\item{type.dist}{The distribution of the vertex types, a numeric vector of -length \sQuote{types} containing non-negative numbers. The vector will be -normed to obtain probabilities. The default \code{NULL} gives a uniform -distribution.} +\item{type.dist}{The distribution of the vertex types, a numeric vector of length \sQuote{types} containing non-negative numbers. +The vector will be normed to obtain probabilities. +The default \code{NULL} gives a uniform distribution.} -\item{fixed.sizes}{Fix the number of vertices with a given vertex type -label. The \code{type.dist} argument gives the group sizes (i.e. number of -vertices with the different labels) in this case.} +\item{fixed.sizes}{Fix the number of vertices with a given vertex type label. +The \code{type.dist} argument gives the group sizes (i.e. number of vertices with the different labels) in this case.} -\item{pref.matrix}{A square matrix giving the preferences of the vertex -types. The matrix has \sQuote{types} rows and columns. When generating -an undirected graph, it must be symmetric. The default \code{NULL} sets all -preferences to one.} +\item{pref.matrix}{A square matrix giving the preferences of the vertex types. +The matrix has \sQuote{types} rows and columns. +When generating an undirected graph, it must be symmetric. +The default \code{NULL} sets all preferences to one.} \item{directed}{Logical, whether to create a directed graph.} @@ -40,8 +38,7 @@ preferences to one.} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{preference.game()} was renamed to \code{\link[=sample_pref]{sample_pref()}} to create a more -consistent API. +\code{preference.game()} was renamed to \code{\link[=sample_pref]{sample_pref()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_preference_game}{\code{preference_game()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/print.igraph.Rd b/man/print.igraph.Rd index 0aa9e07f11f..0db4fd0b64c 100644 --- a/man/print.igraph.Rd +++ b/man/print.igraph.Rd @@ -24,28 +24,27 @@ \arguments{ \item{x}{The graph to print.} -\item{full}{Logical, whether to print the graph structure itself as -well. The default \code{NULL} uses the \code{print.full} igraph option.} +\item{full}{Logical, whether to print the graph structure itself as well. +The default \code{NULL} uses the \code{print.full} igraph option.} -\item{graph.attributes}{Logical, whether to print graph attributes. The -default \code{NULL} uses the \code{print.graph.attributes} igraph option.} +\item{graph.attributes}{Logical, whether to print graph attributes. +The default \code{NULL} uses the \code{print.graph.attributes} igraph option.} -\item{vertex.attributes}{Logical, whether to print vertex -attributes. The default \code{NULL} uses the \code{print.vertex.attributes} igraph -option.} +\item{vertex.attributes}{Logical, whether to print vertex attributes. +The default \code{NULL} uses the \code{print.vertex.attributes} igraph option.} -\item{edge.attributes}{Logical, whether to print edge attributes. The -default \code{NULL} uses the \code{print.edge.attributes} igraph option.} +\item{edge.attributes}{Logical, whether to print edge attributes. +The default \code{NULL} uses the \code{print.edge.attributes} igraph option.} \item{names}{Logical, whether to print symbolic vertex names (i.e. the \code{name} vertex attribute) or vertex IDs.} -\item{max.lines}{The maximum number of lines to use. The rest of the -output will be truncated. If not given, the \code{auto.print.lines} igraph -option applies; \code{NULL} prints all lines.} +\item{max.lines}{The maximum number of lines to use. +The rest of the output will be truncated. +If not given, the \code{auto.print.lines} igraph option applies; \code{NULL} prints all lines.} -\item{id}{Whether to print the graph ID. The default \code{NULL} uses the -\code{print.id} igraph option.} +\item{id}{Whether to print the graph ID. +The default \code{NULL} uses the \code{print.id} igraph option.} \item{\dots}{Additional agruments.} @@ -55,62 +54,47 @@ option applies; \code{NULL} prints all lines.} All these functions return the graph invisibly. } \description{ -These functions attempt to print a graph to the terminal in a human readable -form. +These functions attempt to print a graph to the terminal in a human readable form. } \details{ -\code{summary.igraph} prints the number of vertices, edges and whether the -graph is directed. +\code{summary.igraph} prints the number of vertices, edges and whether the graph is directed. -\code{print_all()} prints the same information, and also lists the edges, and -optionally graph, vertex and/or edge attributes. +\code{print_all()} prints the same information, and also lists the edges, and optionally graph, vertex and/or edge attributes. -\code{print.igraph()} behaves either as \code{summary.igraph} or -\code{print_all()} depending on the \code{full} argument. See also the -\sQuote{print.full} igraph option and \code{\link[=igraph_opt]{igraph_opt()}}. +\code{print.igraph()} behaves either as \code{summary.igraph} or \code{print_all()} depending on the \code{full} argument. +See also the \sQuote{print.full} igraph option and \code{\link[=igraph_opt]{igraph_opt()}}. -The graph summary printed by \code{summary.igraph} (and \code{print.igraph()} -and \code{print_all()}) consists of one or more lines. The first line contains -the basic properties of the graph, and the rest contains its attributes. +The graph summary printed by \code{summary.igraph} (and \code{print.igraph()} and \code{print_all()}) consists of one or more lines. +The first line contains the basic properties of the graph, and the rest contains its attributes. Here is an example, a small star graph with weighted directed edges and named vertices: \preformatted{ IGRAPH badcafe DNW- 10 9 -- In-star + attr: name (g/c), mode (g/c), center (g/n), name (v/c), weight (e/n) } -The first line always -starts with \code{IGRAPH}, showing you that the object is an igraph graph. -Then a seven character code is printed, this the first seven characters -of the unique ID of the graph. See \code{\link[=graph_id]{graph_id()}} for more. -Then a four letter long code string is printed. The first letter -distinguishes between directed (\sQuote{\code{D}}) and undirected -(\sQuote{\code{U}}) graphs. The second letter is \sQuote{\code{N}} for named -graphs, i.e. graphs with the \code{name} vertex attribute set. The third -letter is \sQuote{\code{W}} for weighted graphs, i.e. graphs with the -\code{weight} edge attribute set. The fourth letter is \sQuote{\code{B}} for -bipartite graphs, i.e. for graphs with the \code{type} vertex attribute set. +The first line always starts with \code{IGRAPH}, showing you that the object is an igraph graph. +Then a seven character code is printed, this the first seven characters of the unique ID of the graph. +See \code{\link[=graph_id]{graph_id()}} for more. +Then a four letter long code string is printed. +The first letter distinguishes between directed (\sQuote{\code{D}}) and undirected (\sQuote{\code{U}}) graphs. +The second letter is \sQuote{\code{N}} for named graphs, i.e. graphs with the \code{name} vertex attribute set. +The third letter is \sQuote{\code{W}} for weighted graphs, i.e. graphs with the \code{weight} edge attribute set. +The fourth letter is \sQuote{\code{B}} for bipartite graphs, i.e. for graphs with the \code{type} vertex attribute set. This is followed by the number of vertices and edges, then two dashes. Finally, after two dashes, the name of the graph is printed, if it has one, i.e. if the \code{name} graph attribute is set. -From the second line, the attributes of the graph are listed, separated by a -comma. After the attribute names, the kind of the attribute -- graph -(\sQuote{\code{g}}), vertex (\sQuote{\code{v}}) or edge (\sQuote{\code{e}}) --- is denoted, and the type of the attribute as well, character -(\sQuote{\code{c}}), numeric (\sQuote{\code{n}}), logical -(\sQuote{\code{l}}), or other (\sQuote{\code{x}}). +From the second line, the attributes of the graph are listed, separated by a comma. +After the attribute names, the kind of the attribute -- graph (\sQuote{\code{g}}), vertex (\sQuote{\code{v}}) or edge (\sQuote{\code{e}}) -- is denoted, +and the type of the attribute as well, character (\sQuote{\code{c}}), numeric (\sQuote{\code{n}}), logical (\sQuote{\code{l}}), or other (\sQuote{\code{x}}). -As of igraph 0.4 \code{print_all()} and \code{print.igraph()} use the -\code{max.print} option, see \code{\link[base:options]{base::options()}} for details. +As of igraph 0.4 \code{print_all()} and \code{print.igraph()} use the \code{max.print} option, see \code{\link[base:options]{base::options()}} for details. -As of igraph 1.1.1, the \code{str.igraph} function is defunct, use -\code{print_all()}. +As of igraph 1.1.1, the \code{str.igraph} function is defunct, use \code{print_all()}. -Output style is controlled by the \code{print.style} igraph option. The default -\code{"cli"} produces cli-styled output with section rules, typed attribute -listings and Unicode arrows for edges. Set -\code{igraph_options(print.style = "classic")} for the historical -\verb{IGRAPH ... DNW-} header relied on by parsers and tutorials. +Output style is controlled by the \code{print.style} igraph option. +The default \code{"cli"} produces cli-styled output with section rules, typed attribute listings and Unicode arrows for edges. +Set \code{igraph_options(print.style = "classic")} for the historical \verb{IGRAPH ... DNW-} header relied on by parsers and tutorials. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_degree}{\code{degree()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_is_directed}{\code{is_directed()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}} diff --git a/man/print.igraph.es.Rd b/man/print.igraph.es.Rd index 5d3a9505ca2..42369f19a27 100644 --- a/man/print.igraph.es.Rd +++ b/man/print.igraph.es.Rd @@ -9,11 +9,10 @@ \arguments{ \item{x}{An edge sequence.} -\item{full}{Whether to show the full sequence, or truncate the output -to the screen size.} +\item{full}{Whether to show the full sequence, or truncate the output to the screen size.} -\item{id}{Whether to print the graph ID. The default \code{NULL} uses the -\code{print.id} igraph option.} +\item{id}{Whether to print the graph ID. +The default \code{NULL} uses the \code{print.id} igraph option.} \item{...}{Currently ignored.} } @@ -21,14 +20,12 @@ to the screen size.} The edge sequence, invisibly. } \description{ -For long edge sequences, the printing is truncated to fit to the -screen. Use \code{\link[=print]{print()}} explicitly and the \code{full} argument to -see the full sequence. +For long edge sequences, the printing is truncated to fit to the screen. +Use \code{\link[=print]{print()}} explicitly and the \code{full} argument to see the full sequence. } \details{ -Edge sequences created with the double bracket operator are printed -differently, together with all attributes of the edges in the sequence, -as a table. +Edge sequences created with the double bracket operator are printed differently, +together with all attributes of the edges in the sequence, as a table. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_is_directed}{\code{is_directed()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/print.igraph.vs.Rd b/man/print.igraph.vs.Rd index 92504a5dcd2..231e3bfd7d0 100644 --- a/man/print.igraph.vs.Rd +++ b/man/print.igraph.vs.Rd @@ -9,11 +9,10 @@ \arguments{ \item{x}{A vertex sequence.} -\item{full}{Whether to show the full sequence, or truncate the output -to the screen size.} +\item{full}{Whether to show the full sequence, or truncate the output to the screen size.} -\item{id}{Whether to print the graph ID. The default \code{NULL} uses the -\code{print.id} igraph option.} +\item{id}{Whether to print the graph ID. +The default \code{NULL} uses the \code{print.id} igraph option.} \item{...}{These arguments are currently ignored.} } @@ -21,14 +20,12 @@ to the screen size.} The vertex sequence, invisibly. } \description{ -For long vertex sequences, the printing is truncated to fit to the -screen. Use \code{\link[=print]{print()}} explicitly and the \code{full} argument to -see the full sequence. +For long vertex sequences, the printing is truncated to fit to the screen. +Use \code{\link[=print]{print()}} explicitly and the \code{full} argument to see the full sequence. } \details{ -Vertex sequence created with the double bracket operator are -printed differently, together with all attributes of the vertices -in the sequence, as a table. +Vertex sequence created with the double bracket operator are printed differently, +together with all attributes of the vertices in the sequence, as a table. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/print.igraphHRG.Rd b/man/print.igraphHRG.Rd index e9ae0f4c744..7fd048d876f 100644 --- a/man/print.igraphHRG.Rd +++ b/man/print.igraphHRG.Rd @@ -19,11 +19,10 @@ The hierarchical random graph model itself, invisibly. } \description{ -\code{igraphHRG} objects can be printed to the screen in two forms: as -a tree or as a list, depending on the \code{type} argument of the -print function. By default the \code{auto} type is used, which selects -\code{tree} for small graphs and \code{simple} (=list) for bigger -ones. The \code{tree} format looks like +\code{igraphHRG} objects can be printed to the screen in two forms: as a tree or as a list, +depending on the \code{type} argument of the print function. +By default the \code{auto} type is used, which selects \code{tree} for small graphs and \code{simple} (=list) for bigger ones. +The \code{tree} format looks like this: \preformatted{Hierarchical random graph, at level 3: g1 p= 0 '- g15 p=0.33 1 @@ -31,16 +30,12 @@ g1 p= 0 '- g8 p= 0.5 '- g16 p= 0.2 20 14 17 19 11 15 16 13 '- g5 p= 0 12 18 } -This is a graph with 20 vertices, and the -top three levels of the fitted hierarchical random graph are -printed. The root node of the HRG is always vertex group #1 -(\sQuote{\code{g1}} in the the printout). Vertex pairs in the left -subtree of \code{g1} connect to vertices in the right subtree with -probability zero, according to the fitted model. \code{g1} has two -subgroups, \code{g15} and \code{g8}. \code{g15} has a subgroup of a -single vertex (vertex 1), and another larger subgroup that contains -vertices 6, 3, etc. on lower levels, etc. -The \code{plain} printing is simpler and faster to produce, but less +This is a graph with 20 vertices, and the top three levels of the fitted hierarchical random graph are printed. +The root node of the HRG is always vertex group #1 (\sQuote{\code{g1}} in the the printout). +Vertex pairs in the left subtree of \code{g1} connect to vertices in the right subtree with probability zero, according to the fitted model. +\code{g1} has two subgroups, \code{g15} and \code{g8}. +\code{g15} has a subgroup of a single vertex (vertex 1), and another larger subgroup that contains vertices 6, 3, etc. on lower levels, +etc. The \code{plain} printing is simpler and faster to produce, but less visual: \preformatted{Hierarchical random graph: g1 p=0.0 -> g12 g10 g2 p=1.0 -> 7 10 g3 p=1.0 -> g18 14 g4 p=1.0 -> g17 15 g5 p=0.4 -> g15 17 g6 p=0.0 -> 1 4 @@ -49,8 +44,7 @@ g10 p=0.2 -> g4 g5 g11 p=1.0 -> g6 5 g12 p=0.8 -> g8 8 g13 p=0.0 -> g14 9 g14 p=1.0 -> 2 6 g15 p=0.2 -> g19 18 g16 p=1.0 -> g13 g2 g17 p=0.5 -> g7 13 g18 p=1.0 -> 12 19 g19 p=0.7 -> g3 20} -It lists the two subgroups of each internal node, in -as many columns as the screen width allows. +It lists the two subgroups of each internal node, in as many columns as the screen width allows. } \seealso{ Other hierarchical random graph functions: diff --git a/man/print.igraphHRGConsensus.Rd b/man/print.igraphHRGConsensus.Rd index 488e4f6ea65..1321a09a14d 100644 --- a/man/print.igraphHRGConsensus.Rd +++ b/man/print.igraphHRGConsensus.Rd @@ -15,14 +15,12 @@ The input object, invisibly, to allow method chaining. } \description{ -Consensus dendrograms (\code{igraphHRGConsensus} objects) are printed -simply by listing the children of each internal node of the +Consensus dendrograms (\code{igraphHRGConsensus} objects) are printed simply by listing the children of each internal node of the dendrogram: \preformatted{HRG consensus tree: g1 -> 11 12 13 14 15 16 17 18 19 20 g2 -> 1 2 3 4 5 6 7 8 9 10 g3 -> g1 g2} -The root of the dendrogram is \code{g3} (because it has no incoming -edges), and it has two subgroups, \code{g1} and \code{g2}. +The root of the dendrogram is \code{g3} (because it has no incoming edges), and it has two subgroups, \code{g1} and \code{g2}. } \seealso{ Other hierarchical random graph functions: diff --git a/man/printer_callback.Rd b/man/printer_callback.Rd index 27a5e797365..3e9b39d3dc1 100644 --- a/man/printer_callback.Rd +++ b/man/printer_callback.Rd @@ -10,8 +10,8 @@ printer_callback(fun) \item{fun}{The function to use as a printer callback function.} } \description{ -A printer callback function is a function can performs the actual -printing. It has a number of subcommands, that are called by +A printer callback function is a function can performs the actual printing. +It has a number of subcommands, that are called by the \code{printer} package, in a form \preformatted{ printer_callback("subcommand", argument1, argument2, ...) } See the examples below. diff --git a/man/r_pal.Rd b/man/r_pal.Rd index 0a269ba1ed2..6bc8cc2d6bb 100644 --- a/man/r_pal.Rd +++ b/man/r_pal.Rd @@ -13,9 +13,8 @@ r_pal(n) A character vector of color names. } \description{ -This is the default R palette, to be able to reproduce the -colors of older igraph versions. Its colors are appropriate -for categories, but they are not very attractive. +This is the default R palette, to be able to reproduce the colors of older igraph versions. +Its colors are appropriate for categories, but they are not very attractive. } \seealso{ Other palettes: diff --git a/man/radius.Rd b/man/radius.Rd index d9bd5176321..44bcaee9879 100644 --- a/man/radius.Rd +++ b/man/radius.Rd @@ -11,33 +11,30 @@ radius(graph, ..., weights = NULL, mode = c("all", "out", "in", "total")) \item{...}{These dots are for future extensions and must be empty.} -\item{weights}{Possibly a numeric vector giving edge weights. If this is -\code{NULL} and the graph has a \code{weight} edge attribute, then the -attribute is used. If this is \code{NA} then no weights are used (even if -the graph has a \code{weight} attribute). In a weighted graph, the length -of a path is the sum of the weights of its constituent edges.} +\item{weights}{Possibly a numeric vector giving edge weights. +If this is \code{NULL} and the graph has a \code{weight} edge attribute, then the attribute is used. +If this is \code{NA} then no weights are used (even if the graph has a \code{weight} attribute). +In a weighted graph, the length of a path is the sum of the weights of its constituent edges.} -\item{mode}{Character constant, gives whether the shortest paths to or from -the given vertices should be calculated for directed graphs. If \code{out} -then the shortest paths \emph{from} the vertex, if \verb{in} then \emph{to} -it will be considered. If \code{all}, the default, then the graph is treated -as undirected, i.e. edge directions are not taken into account. This -argument is ignored for undirected graphs.} +\item{mode}{Character constant, +gives whether the shortest paths to or from the given vertices should be calculated for directed graphs. +If \code{out} then the shortest paths \emph{from} the vertex, if \verb{in} then \emph{to} it will be considered. +If \code{all}, the default, then the graph is treated as undirected, i.e. edge directions are not taken into account. +This argument is ignored for undirected graphs.} } \value{ A numeric scalar, the radius of the graph. } \description{ -The eccentricity of a vertex is its distance from the farthest other node -in the graph. The smallest eccentricity in a graph is called its radius. +The eccentricity of a vertex is its distance from the farthest other node in the graph. +The smallest eccentricity in a graph is called its radius. } \details{ -The eccentricity of a vertex is calculated by measuring the shortest -distance from (or to) the vertex, to (or from) all vertices in the -graph, and taking the maximum. +The eccentricity of a vertex is calculated by measuring the shortest distance from (or to) the vertex, +to (or from) all vertices in the graph, and taking the maximum. -This implementation ignores vertex pairs that are in different -components. Isolated vertices have eccentricity zero. +This implementation ignores vertex pairs that are in different components. +Isolated vertices have eccentricity zero. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_radius_dijkstra}{\code{radius_dijkstra()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} @@ -53,9 +50,7 @@ Harary, F. Graph Theory. Reading, MA: Addison-Wesley, p. 35, 1994. } \seealso{ -\code{\link[=eccentricity]{eccentricity()}} for the underlying -calculations, \link{distances} for general shortest path -calculations. +\code{\link[=eccentricity]{eccentricity()}} for the underlying calculations, \link{distances} for general shortest path calculations. Other paths: \code{\link[=all_simple_paths]{all_simple_paths()}}, diff --git a/man/random_walk.Rd b/man/random_walk.Rd index 2b4887a6fa5..c8f0e17836b 100644 --- a/man/random_walk.Rd +++ b/man/random_walk.Rd @@ -34,36 +34,33 @@ random_edge_walk( \item{...}{These dots are for future extensions and must be empty.} -\item{weights}{The edge weights. Larger edge weights increase the -probability that an edge is selected by the random walker. In other -words, larger edge weights correspond to stronger connections. The -\sQuote{weight} edge attribute is used if present. Supply -\sQuote{\code{NA}} here if you want to ignore the \sQuote{weight} edge -attribute.} +\item{weights}{The edge weights. +Larger edge weights increase the probability that an edge is selected by the random walker. +In other words, larger edge weights correspond to stronger connections. +The \sQuote{weight} edge attribute is used if present. +Supply \sQuote{\code{NA}} here if you want to ignore the \sQuote{weight} edge attribute.} -\item{mode}{How to follow directed edges. \code{"out"} steps along the -edge direction, \code{"in"} is opposite to that. \code{"all"} ignores -edge directions. This argument is ignored for undirected graphs.} +\item{mode}{How to follow directed edges. +\code{"out"} steps along the edge direction, \code{"in"} is opposite to that. +\code{"all"} ignores edge directions. +This argument is ignored for undirected graphs.} -\item{stuck}{What to do if the random walk gets stuck. \code{"return"} -returns the partial walk, \code{"error"} raises an error.} +\item{stuck}{What to do if the random walk gets stuck. +\code{"return"} returns the partial walk, \code{"error"} raises an error.} } \value{ -For \code{random_walk()}, a vertex sequence of length \code{steps + 1} -containing the vertices along the walk, starting with \code{start}. -For \code{random_edge_walk()}, an edge sequence of length \code{steps} containing -the edges along the walk. +For \code{random_walk()}, a vertex sequence of length \code{steps + 1} containing the vertices along the walk, starting with \code{start}. +For \code{random_edge_walk()}, an edge sequence of length \code{steps} containing the edges along the walk. } \description{ -\code{random_walk()} performs a random walk on the graph and returns the -vertices that the random walk passed through. \code{random_edge_walk()} -is the same but returns the edges that that random walk passed through. +\code{random_walk()} performs a random walk on the graph and returns the vertices that the random walk passed through. +\code{random_edge_walk()} is the same but returns the edges that that random walk passed through. } \details{ -Do a random walk. From the given start vertex, take the given number of -steps, choosing an edge from the actual vertex uniformly randomly. Edge -directions are observed in directed graphs (see the \code{mode} argument -as well). Multiple and loop edges are also observed. +Do a random walk. +From the given start vertex, take the given number of steps, choosing an edge from the actual vertex uniformly randomly. +Edge directions are observed in directed graphs (see the \code{mode} argument as well). +Multiple and loop edges are also observed. For igraph < 1.6.0, \code{random_walk()} counted steps differently, and returned a sequence of length \code{steps} instead of \code{steps + 1}. diff --git a/man/read.graph.Rd b/man/read.graph.Rd index 98e50a3d354..98a35cd070d 100644 --- a/man/read.graph.Rd +++ b/man/read.graph.Rd @@ -12,23 +12,20 @@ read.graph( ) } \arguments{ -\item{file}{The connection to read from. This can be a local file, or a -\code{http} or \code{ftp} connection. It can also be a character string with -the file name or URI.} +\item{file}{The connection to read from. +This can be a local file, or a \code{http} or \code{ftp} connection. +It can also be a character string with the file name or URI.} -\item{format}{Character constant giving the file format. Right now -\code{edgelist}, \code{pajek}, \code{ncol}, \code{lgl}, \code{graphml}, -\code{dimacs}, \code{graphdb}, \code{gml} and \code{dl} are supported, -the default is \code{edgelist}. As of igraph 0.4 this argument is case -insensitive.} +\item{format}{Character constant giving the file format. +Right now \code{edgelist}, \code{pajek}, \code{ncol}, \code{lgl}, \code{graphml}, \code{dimacs}, \code{graphdb}, \code{gml} and \code{dl} are supported, the default is \code{edgelist}. +As of igraph 0.4 this argument is case insensitive.} \item{...}{Additional arguments, see below.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{read.graph()} was renamed to \code{\link[=read_graph]{read_graph()}} to create a more -consistent API. +\code{read.graph()} was renamed to \code{\link[=read_graph]{read_graph()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Foreign.html#igraph_read_graph_pajek}{\code{read_graph_pajek()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Foreign.html#igraph_read_graph_graphml}{\code{read_graph_graphml()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Foreign.html#igraph_read_graph_gml}{\code{read_graph_gml()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Foreign.html#igraph_read_graph_dl}{\code{read_graph_dl()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Foreign.html#igraph_read_graph_graphdb}{\code{read_graph_graphdb()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/read_graph.Rd b/man/read_graph.Rd index 15f4f2fa85b..35e1aff9283 100644 --- a/man/read_graph.Rd +++ b/man/read_graph.Rd @@ -18,15 +18,13 @@ read_graph( ) } \arguments{ -\item{file}{The connection to read from. This can be a local file, or a -\code{http} or \code{ftp} connection. It can also be a character string with -the file name or URI.} +\item{file}{The connection to read from. +This can be a local file, or a \code{http} or \code{ftp} connection. +It can also be a character string with the file name or URI.} -\item{format}{Character constant giving the file format. Right now -\code{edgelist}, \code{pajek}, \code{ncol}, \code{lgl}, \code{graphml}, -\code{dimacs}, \code{graphdb}, \code{gml} and \code{dl} are supported, -the default is \code{edgelist}. As of igraph 0.4 this argument is case -insensitive.} +\item{format}{Character constant giving the file format. +Right now \code{edgelist}, \code{pajek}, \code{ncol}, \code{lgl}, \code{graphml}, \code{dimacs}, \code{graphdb}, \code{gml} and \code{dl} are supported, the default is \code{edgelist}. +As of igraph 0.4 this argument is case insensitive.} \item{\dots}{Additional arguments, see below.} } @@ -34,42 +32,37 @@ insensitive.} A graph object. } \description{ -The \code{read_graph()} function is able to read graphs in various -representations from a file, or from a http connection. Various formats -are supported. +The \code{read_graph()} function is able to read graphs in various representations from a file, or from a http connection. +Various formats are supported. } \details{ -The \code{read_graph()} function may have additional arguments depending on -the file format (the \code{format} argument). See the details separately for -each file format, below. +The \code{read_graph()} function may have additional arguments depending on the file format (the \code{format} argument). +See the details separately for each file format, below. } \section{Edge list format}{ -This format is a simple text file with numeric -vertex IDs defining the edges. There is no need to have newline characters -between the edges, a simple space will also do. Vertex IDs contained in -the file are assumed to start at zero. +This format is a simple text file with numeric vertex IDs defining the edges. +There is no need to have newline characters between the edges, a simple space will also do. +Vertex IDs contained in the file are assumed to start at zero. Additional arguments: \describe{ \item{n}{ -The number of vertices in the -graph. If it is smaller than or equal to the largest integer in the file, -then it is ignored; so it is safe to set it to zero (the default). +The number of vertices in the graph. +If it is smaller than or equal to the largest integer in the file, then it is ignored; +so it is safe to set it to zero (the default). } \item{directed}{ -Logical scalar, whether to create a directed graph. The -default value is \code{TRUE}. +Logical scalar, whether to create a directed graph. +The default value is \code{TRUE}. } } } \section{Pajek format}{ -Currently igraph only supports Pajek network -files, with a \code{.net} extension, but not Pajek project files with -a \code{.paj} extension. Only network data is supported; permutations, -hierarchies, clusters and vectors are not. +Currently igraph only supports Pajek network files, with a \code{.net} extension, but not Pajek project files with a \code{.paj} extension. +Only network data is supported; permutations, hierarchies, clusters and vectors are not. } \section{NCOL format}{ @@ -119,7 +112,8 @@ containing multiple graphs. Defaults to 0 for the first graph.} \section{LGL format}{ -The .lgl format is used by the Large Graph Layout visualization software (\url{https://lgl.sourceforge.net}), it can describe undirected optionally weighted graphs +The .lgl format is used by the Large Graph Layout visualization software (\url{https://lgl.sourceforge.net}), +it can describe undirected optionally weighted graphs \describe{ \item{names}{Logical, whether to add vertex names as a vertex attribute called "name". Default is TRUE.} @@ -141,15 +135,15 @@ if there is at least one explicit edge weight in the input file. This is a line-oriented text file (ASCII) format. The first character of each line defines the type of the line. If the first character is c the line is a comment line and it is ignored. -There is one problem line (p in the file), -it must appear before any node and arc descriptor lines. -The problem line has three fields separated by spaces: the problem type (max or edge), -the number of vertices, and number of edges in the graph. In MAX problems, -exactly two node identification lines are expected (n), one for the source, and one for the target vertex. +There is one problem line (p in the file), it must appear before any node and arc descriptor lines. +The problem line has three fields separated by spaces: the problem type (max or edge), the number of vertices, +and number of edges in the graph. +In MAX problems, exactly two node identification lines are expected (n), one for the source, and one for the target vertex. These have two fields: the ID of the vertex and the type of the vertex, either s ( = source) or t ( = target). Arc lines start with a and have three fields: the source vertex, the target vertex and the edge capacity. -In EDGE problems, there may be a node line (n) for each node. It specifies the node index and an -integer node label. Nodes for which no explicit label was specified will use their index as label. +In EDGE problems, there may be a node line (n) for each node. +It specifies the node index and an integer node label. +Nodes for which no explicit label was specified will use their index as label. In EDGE problems, each edge is specified as an edge line (e). \describe{ \item{directed}{Logical, whether to create a directed graph. Default is TRUE.} @@ -172,12 +166,14 @@ For igraph DL files are case sensitive, i.e. Larry and larry are not the same. \section{GML format}{ -GML is a quite general textual format. For the specifics of the implementation, see the linked documentation of the cClibrary. +GML is a quite general textual format. +For the specifics of the implementation, see the linked documentation of the cClibrary. } \section{GraphDB format}{ -This is a binary format, used in the ARG Graph Database for isomorphism testing. For more information, see \url{https://mivia.unisa.it/datasets/graph-database/arg-database/} +This is a binary format, used in the ARG Graph Database for isomorphism testing. +For more information, see \url{https://mivia.unisa.it/datasets/graph-database/arg-database/} \describe{ \item{directed}{Logical, whether to create a directed graph. Default is TRUE.} } diff --git a/man/realize_bipartite_degseq.Rd b/man/realize_bipartite_degseq.Rd index 6bc53424966..db33dcb5380 100644 --- a/man/realize_bipartite_degseq.Rd +++ b/man/realize_bipartite_degseq.Rd @@ -31,24 +31,20 @@ The new graph object. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} -Constructs a bipartite graph from the degree sequences of its partitions, -if one exists. This function uses a Havel-Hakimi style construction -algorithm. +Constructs a bipartite graph from the degree sequences of its partitions, if one exists. +This function uses a Havel-Hakimi style construction algorithm. } \details{ -The \sQuote{method} argument controls in which order the vertices are -selected during the course of the algorithm. +The \sQuote{method} argument controls in which order the vertices are selected during the course of the algorithm. -The \dQuote{smallest} method selects the vertex with the smallest remaining -degree, from either partition. The result is usually a graph with high -negative degree assortativity. In the undirected case, this method is -guaranteed to generate a connected graph, regardless of whether multi-edges -are allowed, provided that a connected realization exists. This is the -default method. +The \dQuote{smallest} method selects the vertex with the smallest remaining degree, from either partition. +The result is usually a graph with high negative degree assortativity. +In the undirected case, this method is guaranteed to generate a connected graph, regardless of whether multi-edges are allowed, +provided that a connected realization exists. +This is the default method. -The \dQuote{largest} method selects the vertex with the largest remaining -degree. The result is usually a graph with high positive degree -assortativity, and is often disconnected. +The \dQuote{largest} method selects the vertex with the largest remaining degree. +The result is usually a graph with high positive degree assortativity, and is often disconnected. The \dQuote{index} method selects the vertices in order of their index. } diff --git a/man/realize_degseq.Rd b/man/realize_degseq.Rd index fdf16227b7f..b4c62dc5f09 100644 --- a/man/realize_degseq.Rd +++ b/man/realize_degseq.Rd @@ -13,22 +13,21 @@ realize_degseq( ) } \arguments{ -\item{out.deg}{Numeric vector, the sequence of degrees (for undirected -graphs) or out-degrees (for directed graphs). For undirected graphs its sum -should be even. For directed graphs its sum should be the same as the sum of -\code{in.deg}.} +\item{out.deg}{Numeric vector, the sequence of degrees (for undirected graphs) or out-degrees (for directed graphs). +For undirected graphs its sum should be even. +For directed graphs its sum should be the same as the sum of \code{in.deg}.} -\item{in.deg}{For directed graph, the in-degree sequence. By default this is -\code{NULL} and an undirected graph is created.} +\item{in.deg}{For directed graph, the in-degree sequence. +By default this is \code{NULL} and an undirected graph is created.} \item{...}{These dots are for future extensions and must be empty.} \item{allowed.edge.types}{Character, specifies the types of allowed edges. \dQuote{simple} allows simple graphs only (no loops, no multiple edges). \dQuote{multiple} allows multiple edges but disallows loop. -\dQuote{loops} allows loop edges but disallows multiple edges (currently -unimplemented). \dQuote{all} allows all types of edges. The default is -\dQuote{simple}.} +\dQuote{loops} allows loop edges but disallows multiple edges (currently unimplemented). +\dQuote{all} allows all types of edges. +The default is \dQuote{simple}.} \item{method}{Character, the method for generating the graph; see below.} } @@ -36,30 +35,27 @@ unimplemented). \dQuote{all} allows all types of edges. The default is The new graph object. } \description{ -It is often useful to create a graph with given vertex degrees. This function -creates such a graph in a deterministic manner. +It is often useful to create a graph with given vertex degrees. +This function creates such a graph in a deterministic manner. } \details{ -Simple undirected graphs are constructed using the Havel-Hakimi algorithm -(undirected case), or the analogous Kleitman-Wang algorithm (directed case). -These algorithms work by choosing an arbitrary vertex and connecting all its -stubs to other vertices. This step is repeated until all degrees have been -connected up. +Simple undirected graphs are constructed using the Havel-Hakimi algorithm (undirected case), +or the analogous Kleitman-Wang algorithm (directed case). +These algorithms work by choosing an arbitrary vertex and connecting all its stubs to other vertices. +This step is repeated until all degrees have been connected up. -The \sQuote{method} argument controls in which order the vertices are -selected during the course of the algorithm. +The \sQuote{method} argument controls in which order the vertices are selected during the course of the algorithm. -The \dQuote{smallest} method selects the vertex with the smallest remaining -degree. The result is usually a graph with high negative degree assortativity. -In the undirected case, this method is guaranteed to generate a connected -graph, regardless of whether multi-edges are allowed, provided that a -connected realization exists. See Horvát and Modes (2021) for details. -In the directed case it tends to generate weakly connected graphs, but this -is not guaranteed. This is the default method. +The \dQuote{smallest} method selects the vertex with the smallest remaining degree. +The result is usually a graph with high negative degree assortativity. +In the undirected case, this method is guaranteed to generate a connected graph, regardless of whether multi-edges are allowed, +provided that a connected realization exists. +See Horvát and Modes (2021) for details. +In the directed case it tends to generate weakly connected graphs, but this is not guaranteed. +This is the default method. -The \dQuote{largest} method selects the vertex with the largest remaining -degree. The result is usually a graph with high positive degree assortativity, -and is often disconnected. +The \dQuote{largest} method selects the vertex with the largest remaining degree. +The result is usually a graph with high positive degree assortativity, and is often disconnected. The \dQuote{index} method selects the vertices in order of their index. } @@ -114,7 +110,6 @@ Connectedness matters: construction and exact random sampling of connected netwo \doi{10.1088/2632-072X/abced5} } \seealso{ -\code{\link[=sample_degseq]{sample_degseq()}} for a randomized variant that samples -from graphs with the given degree sequence. +\code{\link[=sample_degseq]{sample_degseq()}} for a randomized variant that samples from graphs with the given degree sequence. } \keyword{graphs} diff --git a/man/reciprocity.Rd b/man/reciprocity.Rd index 74d3a847b2c..f5526a055d6 100644 --- a/man/reciprocity.Rd +++ b/man/reciprocity.Rd @@ -22,20 +22,18 @@ A numeric scalar between zero and one. Calculates the reciprocity of a directed graph. } \details{ -The measure of reciprocity defines the proportion of mutual connections, in -a directed graph. It is most commonly defined as the probability that the -opposite counterpart of a directed edge is also included in the graph. Or in -adjacency matrix notation: +The measure of reciprocity defines the proportion of mutual connections, in a directed graph. +It is most commonly defined as the probability that the opposite counterpart of a directed edge is also included in the graph. +Or in adjacency matrix notation: \eqn{1 - \left(\sum_{i,j} |A_{ij} - A_{ji}|\right) / \left(2\sum_{i,j} A_{ij}\right)}{1 - (sum_ij |A_ij - A_ji|) / (2 sum_ij A_ij)}. This measure is calculated if the \code{mode} argument is \code{default}. -Prior to igraph version 0.6, another measure was implemented, defined as the -probability of mutual connection between a vertex pair, if we know that -there is a (possibly non-mutual) connection between them. In other words, -(unordered) vertex pairs are classified into three groups: (1) -not-connected, (2) non-reciprocally connected, (3) reciprocally connected. -The result is the size of group (3), divided by the sum of group sizes -(2)+(3). This measure is calculated if \code{mode} is \code{ratio}. +Prior to igraph version 0.6, another measure was implemented, defined as the probability of mutual connection between a vertex pair, +if we know that there is a (possibly non-mutual) connection between them. +In other words, (unordered) vertex pairs are classified into three groups: (1) not-connected, (2) non-reciprocally connected, +(3) reciprocally connected. +The result is the size of group (3), divided by the sum of group sizes (2)+(3). +This measure is calculated if \code{mode} is \code{ratio}. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_reciprocity}{\code{reciprocity()}} diff --git a/man/remove.edge.attribute.Rd b/man/remove.edge.attribute.Rd index fa1e894421c..d99d0016bf3 100644 --- a/man/remove.edge.attribute.Rd +++ b/man/remove.edge.attribute.Rd @@ -14,7 +14,6 @@ remove.edge.attribute(graph, name) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{remove.edge.attribute()} was renamed to \code{\link[=delete_edge_attr]{delete_edge_attr()}} to create a more -consistent API. +\code{remove.edge.attribute()} was renamed to \code{\link[=delete_edge_attr]{delete_edge_attr()}} to create a more consistent API. } \keyword{internal} diff --git a/man/remove.graph.attribute.Rd b/man/remove.graph.attribute.Rd index 209df829e2e..3fdc6796d68 100644 --- a/man/remove.graph.attribute.Rd +++ b/man/remove.graph.attribute.Rd @@ -14,7 +14,6 @@ remove.graph.attribute(graph, name) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{remove.graph.attribute()} was renamed to \code{\link[=delete_graph_attr]{delete_graph_attr()}} to create a more -consistent API. +\code{remove.graph.attribute()} was renamed to \code{\link[=delete_graph_attr]{delete_graph_attr()}} to create a more consistent API. } \keyword{internal} diff --git a/man/remove.vertex.attribute.Rd b/man/remove.vertex.attribute.Rd index d663f91e9cf..25fe5c05225 100644 --- a/man/remove.vertex.attribute.Rd +++ b/man/remove.vertex.attribute.Rd @@ -14,7 +14,6 @@ remove.vertex.attribute(graph, name) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{remove.vertex.attribute()} was renamed to \code{\link[=delete_vertex_attr]{delete_vertex_attr()}} to create a more -consistent API. +\code{remove.vertex.attribute()} was renamed to \code{\link[=delete_vertex_attr]{delete_vertex_attr()}} to create a more consistent API. } \keyword{internal} diff --git a/man/rep.igraph.Rd b/man/rep.igraph.Rd index 4ef1fdd6827..791757aa79a 100644 --- a/man/rep.igraph.Rd +++ b/man/rep.igraph.Rd @@ -15,15 +15,13 @@ \item{n}{Number of times to replicate it.} \item{mark}{Whether to mark the vertices with a \code{which} attribute, -an integer number denoting which replication the vertex is coming -from.} +an integer number denoting which replication the vertex is coming from.} \item{...}{Additional arguments to satisfy S3 requirements, currently ignored.} } \description{ -The new graph will contain the input graph the given number -of times, as unconnected components. +The new graph will contain the input graph the given number of times, as unconnected components. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/reverse_edges.Rd b/man/reverse_edges.Rd index f4d0cd085ff..73557fef2f1 100644 --- a/man/reverse_edges.Rd +++ b/man/reverse_edges.Rd @@ -12,20 +12,18 @@ reverse_edges(graph, eids = NULL) \arguments{ \item{graph}{The input graph.} -\item{eids}{The edge IDs of the edges to reverse. The default \code{NULL} -reverses all edges.} +\item{eids}{The edge IDs of the edges to reverse. +The default \code{NULL} reverses all edges.} \item{x}{The input graph.} } \value{ -The result graph where the direction of the edges with the given -IDs are reversed +The result graph where the direction of the edges with the given IDs are reversed } \description{ -The new graph will contain the same vertices, edges and attributes as -the original graph, except that the direction of the edges selected by -their edge IDs in the \code{eids} argument will be reversed. When reversing -all edges, this operation is also known as graph transpose. +The new graph will contain the same vertices, edges and attributes as the original graph, +except that the direction of the edges selected by their edge IDs in the \code{eids} argument will be reversed. +When reversing all edges, this operation is also known as graph transpose. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Operators.html#igraph_reverse_edges}{\code{reverse_edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/rglplot.Rd b/man/rglplot.Rd index e7310bd6bbd..cca9577b25b 100644 --- a/man/rglplot.Rd +++ b/man/rglplot.Rd @@ -10,21 +10,19 @@ rglplot(x, ...) \arguments{ \item{x}{The graph to plot.} -\item{\dots}{Additional arguments, see \link{igraph.plotting} for the -details} +\item{\dots}{Additional arguments, see \link{igraph.plotting} for the details} } \value{ \code{NULL}, invisibly. } \description{ -Using the \code{rgl} package, \code{rglplot()} plots a graph in 3D. The plot -can be zoomed, rotated, shifted, etc. but the coordinates of the vertices is -fixed. +Using the \code{rgl} package, \code{rglplot()} plots a graph in 3D. +The plot can be zoomed, rotated, shifted, etc. but the coordinates of the vertices is fixed. } \details{ -Note that \code{rglplot()} is considered to be highly experimental. It is not -very useful either. See \link{igraph.plotting} for the possible -arguments. +Note that \code{rglplot()} is considered to be highly experimental. +It is not very useful either. +See \link{igraph.plotting} for the possible arguments. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_edgelist}{\code{get_edgelist()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_is_directed}{\code{is_directed()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} @@ -40,8 +38,7 @@ rglplot(g, layout = coords) \dontshow{\}) # examplesIf} } \seealso{ -\link{igraph.plotting}, \code{\link[=plot.igraph]{plot.igraph()}} for the 2D -version, \code{\link[=tkplot]{tkplot()}} for interactive graph drawing in 2D. +\link{igraph.plotting}, \code{\link[=plot.igraph]{plot.igraph()}} for the 2D version, \code{\link[=tkplot]{tkplot()}} for interactive graph drawing in 2D. Other plot: \code{\link[=plot.igraph]{plot.igraph()}} diff --git a/man/running.mean.Rd b/man/running.mean.Rd index 9a18f326170..0a9a0580359 100644 --- a/man/running.mean.Rd +++ b/man/running.mean.Rd @@ -15,8 +15,7 @@ i.e. smaller than the length of \code{v}.} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{running.mean()} was renamed to \code{\link[=running_mean]{running_mean()}} to create a more -consistent API. +\code{running.mean()} was renamed to \code{\link[=running_mean]{running_mean()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Nongraph.html#igraph_running_mean}{\code{running_mean()}} diff --git a/man/running_mean.Rd b/man/running_mean.Rd index 9545acd9ffd..a1a78377507 100644 --- a/man/running_mean.Rd +++ b/man/running_mean.Rd @@ -16,14 +16,12 @@ i.e. smaller than the length of \code{v}.} A numeric vector of length \code{length(v)-binwidth+1} } \description{ -\code{running_mean()} calculates the running mean in a vector with the given -bin width. +\code{running_mean()} calculates the running mean in a vector with the given bin width. } \details{ -The running mean of \code{v} is a \code{w} vector of length -\code{length(v)-binwidth+1}. The first element of \code{w} ID the average of -the first \code{binwidth} elements of \code{v}, the second element of -\code{w} is the average of elements \code{2:(binwidth+1)}, etc. +The running mean of \code{v} is a \code{w} vector of length \code{length(v)-binwidth+1}. +The first element of \code{w} ID the average of the first \code{binwidth} elements of \code{v}, +the second element of \code{w} is the average of elements \code{2:(binwidth+1)}, etc. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Nongraph.html#igraph_running_mean}{\code{running_mean()}} diff --git a/man/sample_.Rd b/man/sample_.Rd index c4de74036ef..20b486651d5 100644 --- a/man/sample_.Rd +++ b/man/sample_.Rd @@ -18,15 +18,12 @@ For every graph constructor in igraph that has a \code{sample_} prefix, there is a corresponding function without the prefix: e.g. for \code{\link[=sample_pa]{sample_pa()}} there is also \code{\link[=pa]{pa()}}, etc. -The same is true for the deterministic graph samplers, i.e. for each -constructor with a \code{make_} prefix, there is a corresponding -function without that prefix. +The same is true for the deterministic graph samplers, i.e. for each constructor with a \code{make_} prefix, +there is a corresponding function without that prefix. These shorter forms can be used together with \code{sample_()}. -The advantage of this form is that the user can specify constructor -modifiers which work with all constructors. E.g. the -\code{\link[=with_vertex_]{with_vertex_()}} modifier adds vertex attributes -to the newly created graphs. +The advantage of this form is that the user can specify constructor modifiers which work with all constructors. +E.g. the \code{\link[=with_vertex_]{with_vertex_()}} modifier adds vertex attributes to the newly created graphs. See the examples and the various constructor modifiers below. } diff --git a/man/sample_bipartite.Rd b/man/sample_bipartite.Rd index efd94a3b519..98c7e6254ec 100644 --- a/man/sample_bipartite.Rd +++ b/man/sample_bipartite.Rd @@ -22,25 +22,25 @@ bipartite(..., type = NULL) \item{n2}{Integer scalar, the number of top vertices.} -\item{type}{Character scalar, the type of the graph, \sQuote{gnp} creates a -\eqn{G(n,p)} graph, \sQuote{gnm} creates a \eqn{G(n,m)} graph. See details below.} +\item{type}{Character scalar, the type of the graph, \sQuote{gnp} creates a \eqn{G(n,p)} graph, +\sQuote{gnm} creates a \eqn{G(n,m)} graph. +See details below.} -\item{p}{Real scalar, connection probability for \eqn{G(n,p)} graphs. Should not -be given for \eqn{G(n,m)} graphs.} +\item{p}{Real scalar, connection probability for \eqn{G(n,p)} graphs. +Should not be given for \eqn{G(n,m)} graphs.} -\item{m}{Integer scalar, the number of edges for \eqn{G(n,m)} graphs. Should not -be given for \eqn{G(n,p)} graphs.} +\item{m}{Integer scalar, the number of edges for \eqn{G(n,m)} graphs. +Should not be given for \eqn{G(n,p)} graphs.} -\item{directed}{Logical, whether to create a directed graph. See also -the \code{mode} argument.} +\item{directed}{Logical, whether to create a directed graph. +See also the \code{mode} argument.} -\item{mode}{Character scalar, specifies how to direct the edges in directed -graphs. If it is \sQuote{out}, then directed edges point from bottom -vertices to top vertices. If it is \sQuote{in}, edges point from top -vertices to bottom vertices. \sQuote{out} and \sQuote{in} do not generate -mutual edges. If this argument is \sQuote{all}, then each edge direction is -considered independently and mutual edges might be generated. This argument -is ignored for undirected graphs.} +\item{mode}{Character scalar, specifies how to direct the edges in directed graphs. +If it is \sQuote{out}, then directed edges point from bottom vertices to top vertices. +If it is \sQuote{in}, edges point from top vertices to bottom vertices. +\sQuote{out} and \sQuote{in} do not generate mutual edges. +If this argument is \sQuote{all}, then each edge direction is considered independently and mutual edges might be generated. +This argument is ignored for undirected graphs.} \item{...}{Passed to \code{sample_bipartite()}.} } diff --git a/man/sample_bipartite_gnm.Rd b/man/sample_bipartite_gnm.Rd index 486f62b5e61..a317bb1f2a3 100644 --- a/man/sample_bipartite_gnm.Rd +++ b/man/sample_bipartite_gnm.Rd @@ -38,16 +38,15 @@ sample_bipartite_gnp( \item{...}{These dots are for future extensions and must be empty.} -\item{directed}{Logical, whether to create a directed graph. See also -the \code{mode} argument.} +\item{directed}{Logical, whether to create a directed graph. +See also the \code{mode} argument.} -\item{mode}{Character scalar, specifies how to direct the edges in directed -graphs. If it is \sQuote{out}, then directed edges point from bottom -vertices to top vertices. If it is \sQuote{in}, edges point from top -vertices to bottom vertices. \sQuote{out} and \sQuote{in} do not generate -mutual edges. If this argument is \sQuote{all}, then each edge direction is -considered independently and mutual edges might be generated. This argument -is ignored for undirected graphs.} +\item{mode}{Character scalar, specifies how to direct the edges in directed graphs. +If it is \sQuote{out}, then directed edges point from bottom vertices to top vertices. +If it is \sQuote{in}, edges point from top vertices to bottom vertices. +\sQuote{out} and \sQuote{in} do not generate mutual edges. +If this argument is \sQuote{all}, then each edge direction is considered independently and mutual edges might be generated. +This argument is ignored for undirected graphs.} \item{p}{Real scalar, connection probability for \eqn{G(n,p)} graphs.} } @@ -55,11 +54,11 @@ is ignored for undirected graphs.} Generate bipartite graphs using the Erdős-Rényi model } \details{ -Similarly to unipartite (one-mode) networks, we can define the \eqn{G(n,p)}, and -\eqn{G(n,m)} graph classes for bipartite graphs, via their generating process. -In \eqn{G(n,p)} every possible edge between top and bottom vertices is realized -with probability \eqn{p}, independently of the rest of the edges. In \eqn{G(n,m)}, we -uniformly choose \eqn{m} edges to realize. +Similarly to unipartite (one-mode) networks, we can define the \eqn{G(n,p)}, and \eqn{G(n,m)} graph classes for bipartite graphs, +via their generating process. +In \eqn{G(n,p)} every possible edge between top and bottom vertices is realized with probability \eqn{p}, +independently of the rest of the edges. +In \eqn{G(n,m)}, we uniformly choose \eqn{m} edges to realize. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Bipartite.html#igraph_bipartite_game_gnm}{\code{bipartite_game_gnm()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Bipartite.html#igraph_bipartite_game_gnp}{\code{bipartite_game_gnp()}} diff --git a/man/sample_chung_lu.Rd b/man/sample_chung_lu.Rd index bd1095475bf..a1345fe7105 100644 --- a/man/sample_chung_lu.Rd +++ b/man/sample_chung_lu.Rd @@ -23,24 +23,20 @@ chung_lu( } \arguments{ \item{out.weights}{A vector of non-negative vertex weights (or out-weights). -In sparse graphs, these will be approximately equal to the expected -(out-)degrees.} +In sparse graphs, these will be approximately equal to the expected (out-)degrees.} -\item{in.weights}{A vector of non-negative in-weights, approximately equal to -the expected in-degrees in sparse graphs. May be set to \code{NULL}, in -which case undirected graphs are generated.} +\item{in.weights}{A vector of non-negative in-weights, approximately equal to the expected in-degrees in sparse graphs. +May be set to \code{NULL}, in which case undirected graphs are generated.} \item{...}{These dots are for future extensions and must be empty.} -\item{loops}{Logical, whether to allow the creation of self-loops. Since -vertex pairs are connected independently, setting this to \code{FALSE} is -equivalent to simply discarding self-loops from an existing loopy Chung-Lu -graph.} +\item{loops}{Logical, whether to allow the creation of self-loops. +Since vertex pairs are connected independently, +setting this to \code{FALSE} is equivalent to simply discarding self-loops from an existing loopy Chung-Lu graph.} -\item{variant}{The model variant to sample from, with different definitions -of the connection probability between vertices \eqn{i} and \eqn{j}. Given -\eqn{q_{ij} = \frac{w_i w_j}{S}}{q_ij = w_i w_j / S}, the following -formulations are available: +\item{variant}{The model variant to sample from, +with different definitions of the connection probability between vertices \eqn{i} and \eqn{j}. +Given \eqn{q_{ij} = \frac{w_i w_j}{S}}{q_ij = w_i w_j / S}, the following formulations are available: \describe{ \item{\dQuote{original}}{ the original Chung-Lu model, \eqn{p_{ij} = \min(q_{ij}, 1)}{p_ij = min(q_ij, 1)}. @@ -60,71 +56,51 @@ An igraph graph. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} -The Chung-Lu model is useful for generating random graphs with fixed expected -degrees. This function implements both the original model of Chung and Lu, as -well as some additional variants with useful properties. +The Chung-Lu model is useful for generating random graphs with fixed expected degrees. +This function implements both the original model of Chung and Lu, as well as some additional variants with useful properties. } \details{ -In the original Chung-Lu model, each pair of vertices \eqn{i} and \eqn{j} is -connected with independent probability +In the original Chung-Lu model, each pair of vertices \eqn{i} and \eqn{j} is connected with independent probability \deqn{p_{ij} = \frac{w_i w_j}{S},}{p_ij = w_i w_j / S,} where \eqn{w_i} is a weight associated with vertex \eqn{i} and \deqn{S = \sum_k w_k}{S = sum_k w_k} -is the sum of weights. In the directed variant, vertices have both -out-weights, \eqn{w^\text{out}}{w^out}, and in-weights, -\eqn{w^\text{in}}{w^in}, with equal sums, +is the sum of weights. +In the directed variant, vertices have both out-weights, \eqn{w^\text{out}}{w^out}, and in-weights, \eqn{w^\text{in}}{w^in}, +with equal sums, \deqn{S = \sum_k w^\text{out}_k = \sum_k w^\text{in}_k.}{S = sum_k w^out_k = sum_k w^in_k.} The connection probability between \eqn{i} and \eqn{j} is \deqn{p_{ij} = \frac{w^\text{out}_i w^\text{in}_j.}{S}}{p_ij = w^out_i w^in_j / S.} -This model is commonly used to create random graphs with a fixed -\emph{expected} degree sequence. The expected degree of vertex \eqn{i} is -approximately equal to the weight \eqn{w_i}. Specifically, if the graph is -directed and self-loops are allowed, then the expected out- and in-degrees -are precisely \eqn{w^\text{out}}{w^out} and \eqn{w^\text{in}}{w^in}. If -self-loops are disallowed, then the expected out- and in-degrees are -\eqn{\frac{w^\text{out} (S - w^\text{in})}{S}}{w^out (S - w^in) / S} -and -\eqn{\frac{w^\text{in} (S - w^\text{out})}{S}}{w^in (S - w^out) / S}, -respectively. If the graph is undirected, then the expected degrees with and -without self-loops are -\eqn{\frac{w (S + w)}{S}}{w (S + w) / S} -and -\eqn{\frac{w (S - w)}{S}}{w (S - w) / S}, -respectively. - -A limitation of the original Chung-Lu model is that when some of the weights -are large, the formula for \eqn{p_{ij}}{p_ij} yields values larger than 1. -Chung -and Lu's original paper excludes the use of such weights. When -\eqn{p_{ij} > 1}{p_ij > 1}, this function simply issues a warning and creates -a connection between \eqn{i} and \eqn{j}. However, in this case the expected -degrees will no longer relate to the weights in the manner stated above. Thus, -the original Chung-Lu model cannot produce certain (large) expected degrees. - -To overcome this limitation, this function implements additional variants of -the model, with modified expressions for the connection probability -\eqn{p_{ij}}{p_ij} between vertices \eqn{i} and \eqn{j}. Let -\eqn{q_{ij} = \frac{w_i w_j}{S}}{q_ij = w_i w_j / S}, or -\eqn{q_{ij} = \frac{w^\text{out}_i w^\text{in}_j}{S}}{q_ij = w^out_i w^in_j / S} -in the directed case. All model variants become equivalent in the limit of sparse -graphs where \eqn{q_{ij}} approaches zero. In the original Chung-Lu model, -selectable by setting \code{variant} to \dQuote{original}, \eqn{p_{ij} = -\min(q_{ij}, 1)}{p_ij = min(q_ij, 1)}. The \dQuote{maxent} variant, -sometimes referred to as the generalized random graph, uses \eqn{p_{ij} = -\frac{q_{ij}}{1 + q_{ij}}}{p_ij = q_ij / (1 + q_ij)}, and is equivalent to a -maximum entropy model (i.e., exponential random graph model) with a -constraint on expected degrees; -see Park and Newman (2004), Section B, setting \eqn{\exp(-\Theta_{ij}) = -\frac{w_i w_j}{S}}{exp(-Theta_ij) = w_i w_j / S}. This model is also discussed -by Britton, Deijfen, and Martin-Löf (2006). By virtue of being a -degree-constrained maximum entropy model, it generates graphs with the same -degree sequence with the same probability. A third variant can be requested -with \dQuote{nr}, and uses \eqn{p_{ij} = 1 - \exp(-q_{ij})}{p_ij = 1 - -exp(-q_ij)}. This is the underlying simple graph of a multigraph model -introduced by Norros and Reittu (2006). For a discussion of these three model -variants, see Section 16.4 of Bollobás, Janson, Riordan (2007), as well as -Van Der Hofstad (2013). +This model is commonly used to create random graphs with a fixed \emph{expected} degree sequence. +The expected degree of vertex \eqn{i} is approximately equal to the weight \eqn{w_i}. +Specifically, if the graph is directed and self-loops are allowed, +then the expected out- and in-degrees are precisely \eqn{w^\text{out}}{w^out} and \eqn{w^\text{in}}{w^in}. +If self-loops are disallowed, +then the expected out- and in-degrees are \eqn{\frac{w^\text{out} (S - w^\text{in})}{S}}{w^out (S - w^in) / S} and \eqn{\frac{w^\text{in} (S - w^\text{out})}{S}}{w^in (S - w^out) / S}, respectively. +If the graph is undirected, +then the expected degrees with and without self-loops are \eqn{\frac{w (S + w)}{S}}{w (S + w) / S} and \eqn{\frac{w (S - w)}{S}}{w (S - w) / S}, respectively. + +A limitation of the original Chung-Lu model is that when some of the weights are large, +the formula for \eqn{p_{ij}}{p_ij} yields values larger than 1. Chung and Lu's original paper excludes the use of such weights. +When \eqn{p_{ij} > 1}{p_ij > 1}, this function simply issues a warning and creates a connection between \eqn{i} and \eqn{j}. +However, in this case the expected degrees will no longer relate to the weights in the manner stated above. +Thus, the original Chung-Lu model cannot produce certain (large) expected degrees. + +To overcome this limitation, this function implements additional variants of the model, +with modified expressions for the connection probability \eqn{p_{ij}}{p_ij} between vertices \eqn{i} and \eqn{j}. +Let \eqn{q_{ij} = \frac{w_i w_j}{S}}{q_ij = w_i w_j / S}, or \eqn{q_{ij} = \frac{w^\text{out}_i w^\text{in}_j}{S}}{q_ij = w^out_i w^in_j / S} in the directed case. +All model variants become equivalent in the limit of sparse graphs where \eqn{q_{ij}} approaches zero. +In the original Chung-Lu model, selectable by setting \code{variant} to \dQuote{original}, +\eqn{p_{ij} = \min(q_{ij}, 1)}{p_ij = min(q_ij, 1)}. +The \dQuote{maxent} variant, sometimes referred to as the generalized random graph, uses \eqn{p_{ij} = \frac{q_{ij}}{1 + q_{ij}}}{p_ij = q_ij / (1 + q_ij)}, +and is equivalent to a maximum entropy model (i.e., exponential random graph model) with a constraint on expected degrees; see Park and Newman (2004), +Section B, setting \eqn{\exp(-\Theta_{ij}) = \frac{w_i w_j}{S}}{exp(-Theta_ij) = w_i w_j / S}. +This model is also discussed by Britton, Deijfen, and Martin-Löf (2006). +By virtue of being a degree-constrained maximum entropy model, +it generates graphs with the same degree sequence with the same probability. +A third variant can be requested with \dQuote{nr}, and uses \eqn{p_{ij} = 1 - \exp(-q_{ij})}{p_ij = 1 - exp(-q_ij)}. +This is the underlying simple graph of a multigraph model introduced by Norros and Reittu (2006). +For a discussion of these three model variants, see Section 16.4 of Bollobás, Janson, Riordan (2007), as well as Van Der Hofstad (2013). } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_chung_lu_game}{\code{chung_lu_game()}} @@ -172,10 +148,9 @@ graphs. Random Structures & Algorithms, 42, 480-508. \doi{10.1002/rsa.20450} } \seealso{ -\code{\link[=sample_fitness]{sample_fitness()}} implements a similar model with a sharp -constraint on the number of edges. \code{\link[=sample_degseq]{sample_degseq()}} samples random graphs -with sharply specified degrees. \code{\link[=sample_gnp]{sample_gnp()}} creates random graphs with a -fixed connection probability \eqn{p} between all vertex pairs. +\code{\link[=sample_fitness]{sample_fitness()}} implements a similar model with a sharp constraint on the number of edges. +\code{\link[=sample_degseq]{sample_degseq()}} samples random graphs with sharply specified degrees. +\code{\link[=sample_gnp]{sample_gnp()}} creates random graphs with a fixed connection probability \eqn{p} between all vertex pairs. Random graph models (games): \code{\link[=bipartite_gnm]{bipartite_gnm()}}, diff --git a/man/sample_correlated_gnp.Rd b/man/sample_correlated_gnp.Rd index 9c7e5c11f7c..26d0c58aa33 100644 --- a/man/sample_correlated_gnp.Rd +++ b/man/sample_correlated_gnp.Rd @@ -2,39 +2,34 @@ % Please edit documentation in R/games.R \name{sample_correlated_gnp} \alias{sample_correlated_gnp} -\title{Generate a new random graph from a given graph by randomly -adding/removing edges} +\title{Generate a new random graph from a given graph by randomly adding/removing edges} \usage{ sample_correlated_gnp(old.graph, corr, ..., p = NULL, permutation = NULL) } \arguments{ \item{old.graph}{The original graph.} -\item{corr}{A scalar in the unit interval, the target Pearson -correlation between the adjacency matrices of the original and the generated -graph (the adjacency matrix being used as a vector).} +\item{corr}{A scalar in the unit interval, +the target Pearson correlation between the adjacency matrices of the original and the generated graph (the adjacency matrix being used as a vector).} \item{...}{These dots are for future extensions and must be empty.} -\item{p}{A numeric scalar, the probability of an edge between two -vertices, it must in the open (0,1) interval. The default \code{NULL} uses the -empirical edge density of the graph. If you are resampling an Erdős-Rényi graph and -you know the original edge probability of the Erdős-Rényi model, you should -supply that explicitly.} +\item{p}{A numeric scalar, the probability of an edge between two vertices, it must in the open (0,1) interval. +The default \code{NULL} uses the empirical edge density of the graph. +If you are resampling an Erdős-Rényi graph and you know the original edge probability of the Erdős-Rényi model, +you should supply that explicitly.} -\item{permutation}{A numeric vector, a permutation vector that is -applied on the vertices of the first graph, to get the second graph. If -\code{NULL}, the vertices are not permuted.} +\item{permutation}{A numeric vector, a permutation vector that is applied on the vertices of the first graph, +to get the second graph. +If \code{NULL}, the vertices are not permuted.} } \value{ -An unweighted graph of the same size as \code{old.graph} such -that the correlation coefficient between the entries of the two -adjacency matrices is \code{corr}. Note each pair of corresponding -matrix entries is a pair of correlated Bernoulli random variables. +An unweighted graph of the same size as \code{old.graph} +such that the correlation coefficient between the entries of the two adjacency matrices is \code{corr}. +Note each pair of corresponding matrix entries is a pair of correlated Bernoulli random variables. } \description{ -Sample a new graph by perturbing the adjacency matrix of a given graph -and shuffling its vertices. +Sample a new graph by perturbing the adjacency matrix of a given graph and shuffling its vertices. } \details{ Please see the reference given below. diff --git a/man/sample_correlated_gnp_pair.Rd b/man/sample_correlated_gnp_pair.Rd index 6126b98548a..b9e413df475 100644 --- a/man/sample_correlated_gnp_pair.Rd +++ b/man/sample_correlated_gnp_pair.Rd @@ -9,27 +9,24 @@ sample_correlated_gnp_pair(n, corr, p, directed = FALSE, permutation = NULL) \arguments{ \item{n}{Numeric scalar, the number of vertices for the sampled graphs.} -\item{corr}{A scalar in the unit interval, the target Pearson correlation -between the adjacency matrices of the original the generated graph (the -adjacency matrix being used as a vector).} +\item{corr}{A scalar in the unit interval, +the target Pearson correlation between the adjacency matrices of the original the generated graph (the adjacency matrix being used as a vector).} \item{p}{A numeric scalar, the probability of an edge between two vertices, it must in the open (0,1) interval.} \item{directed}{Logical, whether to generate directed graphs.} -\item{permutation}{A numeric vector, a permutation vector that is applied on -the vertices of the first graph, to get the second graph. If \code{NULL}, -the vertices are not permuted.} +\item{permutation}{A numeric vector, a permutation vector that is applied on the vertices of the first graph, +to get the second graph. +If \code{NULL}, the vertices are not permuted.} } \value{ -A list of two igraph objects, named \code{graph1} and -\code{graph2}, which are two graphs whose adjacency matrix entries are -correlated with \code{corr}. +A list of two igraph objects, named \code{graph1} and \code{graph2}, +which are two graphs whose adjacency matrix entries are correlated with \code{corr}. } \description{ -Sample a new graph by perturbing the adjacency matrix of a given graph and -shuffling its vertices. +Sample a new graph by perturbing the adjacency matrix of a given graph and shuffling its vertices. } \details{ Please see the reference given below. diff --git a/man/sample_degseq.Rd b/man/sample_degseq.Rd index 6f58a0e040d..f49ef1be561 100644 --- a/man/sample_degseq.Rd +++ b/man/sample_degseq.Rd @@ -13,68 +13,58 @@ sample_degseq( ) } \arguments{ -\item{out.deg}{Numeric vector, the sequence of degrees (for undirected -graphs) or out-degrees (for directed graphs). For undirected graphs its sum -should be even. For directed graphs its sum should be the same as the sum of -\code{in.deg}.} +\item{out.deg}{Numeric vector, the sequence of degrees (for undirected graphs) or out-degrees (for directed graphs). +For undirected graphs its sum should be even. +For directed graphs its sum should be the same as the sum of \code{in.deg}.} -\item{in.deg}{For directed graph, the in-degree sequence. By default this is -\code{NULL} and an undirected graph is created.} +\item{in.deg}{For directed graph, the in-degree sequence. +By default this is \code{NULL} and an undirected graph is created.} \item{...}{These dots are for future extensions and must be empty.} -\item{method}{Character, the method for generating the graph. See Details.} +\item{method}{Character, the method for generating the graph. +See Details.} } \value{ The new graph object. } \description{ -It is often useful to create a graph with given vertex degrees. This function -creates such a graph in a randomized manner. +It is often useful to create a graph with given vertex degrees. +This function creates such a graph in a randomized manner. } \details{ -The \dQuote{configuration} method (formerly called "simple") implements the -configuration model. For undirected graphs, it puts all vertex IDs in a bag -such that the multiplicity of a vertex in the bag is the same as its degree. -Then it draws pairs from the bag until the bag becomes empty. This method may -generate both loop (self) edges and multiple edges. For directed graphs, -the algorithm is basically the same, but two separate bags are used -for the in- and out-degrees. Undirected graphs are generated -with probability proportional to \eqn{(\prod_{i Named arguments, where the names are the attributes} -\item{index}{An optional vertex sequence to set the attributes -of a subset of vertices. The default \code{NULL} selects all vertices.} +\item{index}{An optional vertex sequence to set the attributes of a subset of vertices. +The default \code{NULL} selects all vertices.} } \value{ The graph, with the vertex attributes added or set. diff --git a/man/shapes.Rd b/man/shapes.Rd index 6223055e10b..d5eb603ac0a 100644 --- a/man/shapes.Rd +++ b/man/shapes.Rd @@ -17,50 +17,41 @@ shape_noplot(coords, v = NULL, params) add_shape(shape, ..., clip = NULL, plot = NULL, parameters = list()) } \arguments{ -\item{shape}{Character scalar, name of a vertex shape. If it is -\code{NULL} for \code{shapes()}, then the names of all defined -vertex shapes are returned.} +\item{shape}{Character scalar, name of a vertex shape. +If it is \code{NULL} for \code{shapes()}, then the names of all defined vertex shapes are returned.} -\item{coords, el, params, end, v}{See parameters of the clipping/plotting -functions below.} +\item{coords, el, params, end, v}{See parameters of the clipping/plotting functions below.} \item{...}{These dots are for future extensions and must be empty.} -\item{clip}{An R function object, the clipping function. The default -\code{NULL} uses \code{shape_noclip}.} +\item{clip}{An R function object, the clipping function. +The default \code{NULL} uses \code{shape_noclip}.} -\item{plot}{An R function object, the plotting function. The default -\code{NULL} uses \code{shape_noplot}.} +\item{plot}{An R function object, the plotting function. +The default \code{NULL} uses \code{shape_noplot}.} -\item{parameters}{Named list, additional plot/vertex/edge -parameters. The element named define the new parameters, and the -elements themselves define their default values. -Vertex parameters should have a prefix -\sQuote{\code{vertex.}}, edge parameters a prefix -\sQuote{\code{edge.}}. Other general plotting parameters should have -a prefix \sQuote{\code{plot.}}. See Details below.} +\item{parameters}{Named list, additional plot/vertex/edge parameters. +The element named define the new parameters, and the elements themselves define their default values. +Vertex parameters should have a prefix \sQuote{\code{vertex.}}, edge parameters a prefix \sQuote{\code{edge.}}. +Other general plotting parameters should have a prefix \sQuote{\code{plot.}}. +See Details below.} } \value{ -\code{shapes()} returns a character vector if the -\code{shape} argument is \code{NULL}. It returns a named list with -entries named \sQuote{clip} and \sQuote{plot}, both of them R -functions. +\code{shapes()} returns a character vector if the \code{shape} argument is \code{NULL}. +It returns a named list with entries named \sQuote{clip} and \sQuote{plot}, both of them R functions. \code{add_shape()} returns \code{TRUE}, invisibly. -\code{shape_noclip()} returns the appropriate columns of its -\code{coords} argument. +\code{shape_noclip()} returns the appropriate columns of its \code{coords} argument. } \description{ -Starting from version 0.5.1 igraph supports different -vertex shapes when plotting graphs. +Starting from version 0.5.1 igraph supports different vertex shapes when plotting graphs. } \details{ -In igraph a vertex shape is defined by two functions: 1) provides -information about the size of the shape for clipping the edges and 2) -plots the shape if requested. These functions are called \dQuote{shape -functions} in the rest of this manual page. The first one is the -clipping function and the second is the plotting function. +In igraph a vertex shape is defined by two functions: 1) provides information about the size of the shape for clipping the edges and 2) plots the shape +if requested. +These functions are called \dQuote{shape functions} in the rest of this manual page. +The first one is the clipping function and the second is the plotting function. The clipping function has the following arguments: \describe{ @@ -87,11 +78,9 @@ If \dQuote{\code{from}} the function is expected to clip the first column in the } } -The clipping function should return a matrix -with the same number of rows as the \code{el} arguments. -If \code{end} is \code{both} then the matrix must have four -columns, otherwise two. The matrix contains the modified coordinates, -with the clipping applied. +The clipping function should return a matrix with the same number of rows as the \code{el} arguments. +If \code{end} is \code{both} then the matrix must have four columns, otherwise two. +The matrix contains the modified coordinates, with the clipping applied. The plotting function has the following arguments: \describe{ @@ -108,27 +97,20 @@ The same as for the clipping function, see above. The return value of the plotting function is not used. -\code{shapes()} can be used to list the names of all installed -vertex shapes, by calling it without arguments, or setting the -\code{shape} argument to \code{NULL}. If a shape name is given, then -the clipping and plotting functions of that shape are returned in a -named list. - -\code{add_shape()} can be used to add new vertex shapes to -igraph. For this one must give the clipping and plotting functions of -the new shape. It is also possible to list the plot/vertex/edge -parameters, in the \code{parameters} argument, that the clipping -and/or plotting functions can make use of. An example would be a -generic regular polygon shape, which can have a parameter for the -number of sides. - -\code{shape_noclip()} is a very simple clipping function that the -user can use in their own shape definitions. It does no clipping, the -edges will be drawn exactly until the listed vertex position -coordinates. - -\code{shape_noplot()} is a very simple (and probably not very -useful) plotting function, that does not plot anything. +\code{shapes()} can be used to list the names of all installed vertex shapes, by calling it without arguments, +or setting the \code{shape} argument to \code{NULL}. +If a shape name is given, then the clipping and plotting functions of that shape are returned in a named list. + +\code{add_shape()} can be used to add new vertex shapes to igraph. +For this one must give the clipping and plotting functions of the new shape. +It is also possible to list the plot/vertex/edge parameters, in the \code{parameters} argument, +that the clipping and/or plotting functions can make use of. +An example would be a generic regular polygon shape, which can have a parameter for the number of sides. + +\code{shape_noclip()} is a very simple clipping function that the user can use in their own shape definitions. +It does no clipping, the edges will be drawn exactly until the listed vertex position coordinates. + +\code{shape_noplot()} is a very simple (and probably not very useful) plotting function, that does not plot anything. } \examples{ # all vertex shapes, minus "raster", that might not be available diff --git a/man/shortest.paths.Rd b/man/shortest.paths.Rd index 041f8de75b4..fb3d9a56b1d 100644 --- a/man/shortest.paths.Rd +++ b/man/shortest.paths.Rd @@ -16,43 +16,39 @@ shortest.paths( \arguments{ \item{graph}{The graph to work on.} -\item{v}{Numeric vector, the vertices from which the shortest paths will be -calculated. The default \code{NULL} selects all vertices.} +\item{v}{Numeric vector, the vertices from which the shortest paths will be calculated. +The default \code{NULL} selects all vertices.} -\item{to}{Numeric vector, the vertices to which the shortest paths will be -calculated. The default \code{NULL} includes all vertices. Note that for -\code{distances()} every vertex must be included here at most once. (This -is not required for \code{shortest_paths()}.} +\item{to}{Numeric vector, the vertices to which the shortest paths will be calculated. +The default \code{NULL} includes all vertices. +Note that for \code{distances()} every vertex must be included here at most once. +(This is not required for \code{shortest_paths()}.} -\item{mode}{Character constant, gives whether the shortest paths to or from -the given vertices should be calculated for directed graphs. If \code{out} -then the shortest paths \emph{from} the vertex, if \verb{in} then \emph{to} -it will be considered. If \code{all}, the default, then the graph is treated -as undirected, i.e. edge directions are not taken into account. This -argument is ignored for undirected graphs.} +\item{mode}{Character constant, +gives whether the shortest paths to or from the given vertices should be calculated for directed graphs. +If \code{out} then the shortest paths \emph{from} the vertex, if \verb{in} then \emph{to} it will be considered. +If \code{all}, the default, then the graph is treated as undirected, i.e. edge directions are not taken into account. +This argument is ignored for undirected graphs.} -\item{weights}{Possibly a numeric vector giving edge weights. If this is -\code{NULL} and the graph has a \code{weight} edge attribute, then the -attribute is used. If this is \code{NA} then no weights are used (even if -the graph has a \code{weight} attribute). In a weighted graph, the length -of a path is the sum of the weights of its constituent edges.} +\item{weights}{Possibly a numeric vector giving edge weights. +If this is \code{NULL} and the graph has a \code{weight} edge attribute, then the attribute is used. +If this is \code{NA} then no weights are used (even if the graph has a \code{weight} attribute). +In a weighted graph, the length of a path is the sum of the weights of its constituent edges.} -\item{algorithm}{Which algorithm to use for the calculation. By default -igraph tries to select the fastest suitable algorithm. If there are no -weights, then an unweighted breadth-first search is used, otherwise if all -weights are positive, then Dijkstra's algorithm is used. If there are -negative weights and we do the calculation for more than 100 sources, then -Johnson's algorithm is used. Otherwise the Bellman-Ford algorithm is used. -You can override igraph's choice by explicitly giving this parameter. Note -that the igraph C core might still override your choice in obvious cases, -i.e. if there are no edge weights, then the unweighted algorithm will be -used, regardless of this argument.} +\item{algorithm}{Which algorithm to use for the calculation. +By default igraph tries to select the fastest suitable algorithm. +If there are no weights, then an unweighted breadth-first search is used, otherwise if all weights are positive, +then Dijkstra's algorithm is used. +If there are negative weights and we do the calculation for more than 100 sources, then Johnson's algorithm is used. +Otherwise the Bellman-Ford algorithm is used. +You can override igraph's choice by explicitly giving this parameter. +Note that the igraph C core might still override your choice in obvious cases, i.e. if there are no edge weights, +then the unweighted algorithm will be used, regardless of this argument.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{shortest.paths()} was renamed to \code{\link[=distances]{distances()}} to create a more -consistent API. +\code{shortest.paths()} was renamed to \code{\link[=distances]{distances()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_is_directed}{\code{is_directed()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/showtrace.Rd b/man/showtrace.Rd index d03777315bd..26c2b2bb7d7 100644 --- a/man/showtrace.Rd +++ b/man/showtrace.Rd @@ -9,7 +9,6 @@ showtrace(communities) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{showtrace()} was renamed to \code{\link[=show_trace]{show_trace()}} to create a more -consistent API. +\code{showtrace()} was renamed to \code{\link[=show_trace]{show_trace()}} to create a more consistent API. } \keyword{internal} diff --git a/man/similarity.Rd b/man/similarity.Rd index 505e887ec6d..488db80729f 100644 --- a/man/similarity.Rd +++ b/man/similarity.Rd @@ -16,8 +16,8 @@ similarity( \arguments{ \item{graph}{The input graph.} -\item{vids}{The vertex IDs for which the similarity is calculated. The -default \code{NULL} selects all vertices.} +\item{vids}{The vertex IDs for which the similarity is calculated. +The default \code{NULL} selects all vertices.} \item{...}{These dots are for future extensions and must be empty.} @@ -25,41 +25,34 @@ default \code{NULL} selects all vertices.} possible values: \sQuote{\code{out}}, \sQuote{\verb{in}}, \sQuote{\code{all}}.} -\item{loops}{Whether to include vertices themselves in the neighbor -sets.} +\item{loops}{Whether to include vertices themselves in the neighbor sets.} \item{method}{The method to use.} } \value{ -A \code{length(vids)} by \code{length(vids)} numeric matrix -containing the similarity scores. This argument is ignored by the -\code{invlogweighted} method. +A \code{length(vids)} by \code{length(vids)} numeric matrix containing the similarity scores. +This argument is ignored by the \code{invlogweighted} method. } \description{ -These functions calculates similarity scores for vertices based on their -connection patterns. +These functions calculates similarity scores for vertices based on their connection patterns. } \details{ -The Jaccard similarity coefficient of two vertices is the number of common -neighbors divided by the number of vertices that are neighbors of at least -one of the two vertices being considered. The \code{jaccard} method -calculates the pairwise Jaccard similarities for some (or all) of the -vertices. +The Jaccard similarity coefficient of two vertices is the number of common neighbors divided by the number of vertices that are neighbors of at least one of the two vertices being considered. +The \code{jaccard} method calculates the pairwise Jaccard similarities for some (or all) of the vertices. -The Dice similarity coefficient of two vertices is twice the number of -common neighbors divided by the sum of the degrees of the vertices. -Methof \code{dice} calculates the pairwise Dice similarities for some -(or all) of the vertices. +The Dice similarity coefficient of two vertices is twice the number of common neighbors divided by the sum of the degrees of the vertices. +Methof \code{dice} calculates the pairwise Dice similarities for some (or all) of the vertices. -The inverse log-weighted similarity of two vertices is the number of their -common neighbors, weighted by the inverse logarithm of their degrees. It is -based on the assumption that two vertices should be considered more similar -if they share a low-degree common neighbor, since high-degree common -neighbors are more likely to appear even by pure chance. Isolated vertices -will have zero similarity to any other vertex. Self-similarities are not -calculated. See the following paper for more details: Lada A. Adamic and -Eytan Adar: Friends and neighbors on the Web. Social Networks, -25(3):211-230, 2003. +The inverse log-weighted similarity of two vertices is the number of their common neighbors, +weighted by the inverse logarithm of their degrees. +It is based on the assumption that two vertices should be considered more similar +if they share a low-degree common neighbor, +since high-degree common neighbors are more likely to appear even by pure chance. +Isolated vertices will have zero similarity to any other vertex. +Self-similarities are not calculated. +See the following paper for more details: +Lada A. Adamic and Eytan Adar: Friends and neighbors on the Web. +Social Networks, 25(3):211-230, 2003. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_similarity_dice}{\code{similarity_dice()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_similarity_inverse_log_weighted}{\code{similarity_inverse_log_weighted()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_similarity_jaccard}{\code{similarity_jaccard()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/similarity.dice.Rd b/man/similarity.dice.Rd index eef1059ad76..4c05ea289ca 100644 --- a/man/similarity.dice.Rd +++ b/man/similarity.dice.Rd @@ -14,15 +14,14 @@ similarity.dice( \arguments{ \item{graph}{The input graph.} -\item{vids}{The vertex IDs for which the similarity is calculated. The -default \code{NULL} selects all vertices.} +\item{vids}{The vertex IDs for which the similarity is calculated. +The default \code{NULL} selects all vertices.} \item{mode}{The type of neighboring vertices to use for the calculation, possible values: \sQuote{\code{out}}, \sQuote{\verb{in}}, \sQuote{\code{all}}.} -\item{loops}{Whether to include vertices themselves in the neighbor -sets.} +\item{loops}{Whether to include vertices themselves in the neighbor sets.} } \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/similarity.invlogweighted.Rd b/man/similarity.invlogweighted.Rd index 8fbc142be0f..2db8a3c7b0f 100644 --- a/man/similarity.invlogweighted.Rd +++ b/man/similarity.invlogweighted.Rd @@ -13,8 +13,8 @@ similarity.invlogweighted( \arguments{ \item{graph}{The input graph.} -\item{vids}{The vertex IDs for which the similarity is calculated. The -default \code{NULL} selects all vertices.} +\item{vids}{The vertex IDs for which the similarity is calculated. +The default \code{NULL} selects all vertices.} \item{mode}{The type of neighboring vertices to use for the calculation, possible values: \sQuote{\code{out}}, \sQuote{\verb{in}}, diff --git a/man/similarity.jaccard.Rd b/man/similarity.jaccard.Rd index f28b381f80a..3c26143885b 100644 --- a/man/similarity.jaccard.Rd +++ b/man/similarity.jaccard.Rd @@ -14,15 +14,14 @@ similarity.jaccard( \arguments{ \item{graph}{The input graph.} -\item{vids}{The vertex IDs for which the similarity is calculated. The -default \code{NULL} selects all vertices.} +\item{vids}{The vertex IDs for which the similarity is calculated. +The default \code{NULL} selects all vertices.} \item{mode}{The type of neighboring vertices to use for the calculation, possible values: \sQuote{\code{out}}, \sQuote{\verb{in}}, \sQuote{\code{all}}.} -\item{loops}{Whether to include vertices themselves in the neighbor -sets.} +\item{loops}{Whether to include vertices themselves in the neighbor sets.} } \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/simple_cycles.Rd b/man/simple_cycles.Rd index a629cbc60bd..423709eb513 100644 --- a/man/simple_cycles.Rd +++ b/man/simple_cycles.Rd @@ -17,46 +17,45 @@ simple_cycles( \item{graph}{The input graph.} \item{mode}{Character constant specifying how to handle directed graphs. -\code{out} follows edge directions, \verb{in} follows edges in the reverse direction, -and \code{all} ignores edge directions. Ignored in undirected graphs.} +\code{out} follows edge directions, \verb{in} follows edges in the reverse direction, and \code{all} ignores edge directions. +Ignored in undirected graphs.} -\item{min}{Lower limit on cycle lengths to consider. \code{NULL} means no limit.} +\item{min}{Lower limit on cycle lengths to consider. +\code{NULL} means no limit.} -\item{max}{Upper limit on cycle lengths to consider. \code{NULL} means no limit.} +\item{max}{Upper limit on cycle lengths to consider. +\code{NULL} means no limit.} \item{...}{These dots are for future extensions and must be empty.} -\item{callback}{Optional function to call for each cycle found. If provided, -the function should accept two arguments: \code{vertices} (integer vector of vertex -IDs in the cycle) and \code{edges} (integer vector of edge IDs -in the cycle). The function should return \code{FALSE} to continue -the search or \code{TRUE} to stop it. If \code{NULL} (the default), all cycles are -collected and returned as a list. +\item{callback}{Optional function to call for each cycle found. +If provided, the function should accept two arguments: +\code{vertices} (integer vector of vertex IDs in the cycle) and \code{edges} (integer vector of edge IDs in the cycle). +The function should return \code{FALSE} to continue the search or \code{TRUE} to stop it. +If \code{NULL} (the default), all cycles are collected and returned as a list. -\strong{Important limitation:} Callback functions must NOT call any igraph -functions (including simple queries like \code{vcount()} or \code{ecount()}). Doing -so will cause R to crash due to nested \code{.Call()} state corruption. Extract -any needed graph information before calling the function with a callback, or -use collector mode (the default) and process results afterward.} +\strong{Important limitation:} Callback functions must NOT call any igraph functions (including simple queries like \code{vcount()} or \code{ecount()}). +Doing so will cause R to crash due to nested \code{.Call()} state corruption. +Extract any needed graph information before calling the function with a callback, +or use collector mode (the default) and process results afterward.} } \value{ -If \code{callback} is \code{NULL}, returns a list with two elements: \code{vertices} -(list of integer vectors with vertex IDs) and \code{edges} (list of integer vectors -with edge IDs). If \code{callback} is provided, returns \code{NULL} invisibly. +If \code{callback} is \code{NULL}, returns a list with two elements: +\code{vertices} (list of integer vectors with vertex IDs) and \code{edges} (list of integer vectors with edge IDs). +If \code{callback} is provided, returns \code{NULL} invisibly. -If \code{callback} is \code{NULL}, returns a list with two elements: \code{vertices} -(list of integer vectors with vertex IDs) and \code{edges} (list of integer vectors -with edge IDs). If \code{callback} is provided, returns \code{NULL} invisibly. +If \code{callback} is \code{NULL}, returns a list with two elements: +\code{vertices} (list of integer vectors with vertex IDs) and \code{edges} (list of integer vectors with edge IDs). +If \code{callback} is provided, returns \code{NULL} invisibly. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} -This function lists all simple cycles in a graph within a range of cycle -lengths. A cycle is called simple if it has no repeated vertices. +This function lists all simple cycles in a graph within a range of cycle lengths. +A cycle is called simple if it has no repeated vertices. -Multi-edges and self-loops are taken into account. Note that typical graphs -have exponentially many cycles and the presence of multi-edges exacerbates -this combinatorial explosion. +Multi-edges and self-loops are taken into account. +Note that typical graphs have exponentially many cycles and the presence of multi-edges exacerbates this combinatorial explosion. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Cycles.html#igraph_simple_cycles_callback}{\code{simple_cycles_callback()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Cycles.html#igraph_simple_cycles}{\code{simple_cycles()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/simplify.Rd b/man/simplify.Rd index 91a279f97b4..fe03ee0ef01 100644 --- a/man/simplify.Rd +++ b/man/simplify.Rd @@ -20,46 +20,39 @@ simplify_and_colorize(graph) \arguments{ \item{graph}{The graph to work on.} -\item{remove.multiple}{Logical, whether the multiple edges are to be -removed.} +\item{remove.multiple}{Logical, whether the multiple edges are to be 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 -\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. The default \code{NULL} uses -the \code{edge.attr.comb} igraph option.} +\item{edge.attr.comb}{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. +The default \code{NULL} uses the \code{edge.attr.comb} igraph option.} } \value{ -a graph object with the loop and/or multiple edges removed; the -input graph is returned unchanged if it is already simple. +a graph object with the loop and/or multiple edges removed; the input graph is returned unchanged if it is already simple. } \description{ Simple graphs are graphs which do not contain loop and multiple edges. } \details{ -A loop edge is an edge for which the two endpoints are the same -vertex. Two edges are multiple edges if they have exactly the same two -endpoints (for directed graphs order does matter). A graph is simple is -it does not contain loop edges and multiple edges. +A loop edge is an edge for which the two endpoints are the same vertex. +Two edges are multiple edges if they have exactly the same two endpoints (for directed graphs order does matter). +A graph is simple is it does not contain loop edges and multiple edges. \code{is_simple()} checks whether a graph is simple. -\code{simplify()} removes the loop and/or multiple edges from a graph. If -both \code{remove.loops} and \code{remove.multiple} are \code{TRUE} the -function returns a simple graph. If the graph is already simple, it is -returned unchanged. +\code{simplify()} removes the loop and/or multiple edges from a graph. +If both \code{remove.loops} and \code{remove.multiple} are \code{TRUE} the function returns a simple graph. +If the graph is already simple, it is returned unchanged. -\code{simplify_and_colorize()} constructs a new, simple graph from a graph and -also sets a \code{color} attribute on both the vertices and the edges. -The colors of the vertices represent the number of self-loops that were -originally incident on them, while the colors of the edges represent the -multiplicities of the same edges in the original graph. This allows one to -take into account the edge multiplicities and the number of loop edges in -the VF2 isomorphism algorithm. Other graph, vertex and edge attributes from -the original graph are discarded as the primary purpose of this function is -to facilitate the usage of multigraphs with the VF2 algorithm. +\code{simplify_and_colorize()} constructs a new, +simple graph from a graph and also sets a \code{color} attribute on both the vertices and the edges. +The colors of the vertices represent the number of self-loops that were originally incident on them, +while the colors of the edges represent the multiplicities of the same edges in the original graph. +This allows one to take into account the edge multiplicities and the number of loop edges in the VF2 isomorphism algorithm. +Other graph, +vertex and edge attributes from the original graph are discarded as the primary purpose of this function is to facilitate the usage of multigraphs with the VF2 algorithm. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Operators.html#igraph_simplify}{\code{simplify()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_simple}{\code{is_simple()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Isomorphism.html#igraph_simplify_and_colorize}{\code{simplify_and_colorize()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} @@ -74,9 +67,7 @@ is_simple(simplify(g, remove.multiple = FALSE)) is_simple(simplify(g)) } \seealso{ -\code{\link[=which_loop]{which_loop()}}, \code{\link[=which_multiple]{which_multiple()}} and -\code{\link[=count_multiple]{count_multiple()}}, \code{\link[=delete_edges]{delete_edges()}}, -\code{\link[=delete_vertices]{delete_vertices()}} +\code{\link[=which_loop]{which_loop()}}, \code{\link[=which_multiple]{which_multiple()}} and \code{\link[=count_multiple]{count_multiple()}}, \code{\link[=delete_edges]{delete_edges()}}, \code{\link[=delete_vertices]{delete_vertices()}} Other functions for manipulating graph structure: \code{\link[=+.igraph]{+.igraph()}}, diff --git a/man/sir.Rd b/man/sir.Rd index f01107a3f76..08e60e4465a 100644 --- a/man/sir.Rd +++ b/man/sir.Rd @@ -21,43 +21,41 @@ sir(graph, beta, gamma, ..., no.sim = 100) \arguments{ \item{x}{A \code{sir} object, returned by the \code{sir()} function.} -\item{\dots}{For \code{sir()} and \code{time_bins()}, these dots must be empty. For -\code{median.sir()} and \code{quantile.sir()}, unused, present for S3 method -consistency.} +\item{\dots}{For \code{sir()} and \code{time_bins()}, these dots must be empty. +For \code{median.sir()} and \code{quantile.sir()}, unused, present for S3 method consistency.} \item{middle}{Logical, whether to return the middle of the time bins, or the boundaries.} -\item{na.rm}{Logical, whether to ignore \code{NA} values. \code{sir} -objects do not contain any \code{NA} values currently, so this argument is -effectively ignored.} +\item{na.rm}{Logical, whether to ignore \code{NA} values. +\code{sir} objects do not contain any \code{NA} values currently, +so this argument is effectively ignored.} -\item{comp}{Character scalar. The component to calculate the quantile of. -\code{NI} is infected agents, \code{NS} is susceptibles, \code{NR} stands -for recovered.} +\item{comp}{Character scalar. +The component to calculate the quantile of. +\code{NI} is infected agents, \code{NS} is susceptibles, \code{NR} stands for recovered.} -\item{prob}{Numeric vector of probabilities, in [0,1], they specify the -quantiles to calculate.} +\item{prob}{Numeric vector of probabilities, in [0,1], they specify the quantiles to calculate.} -\item{graph}{The graph to run the model on. If directed, then edge -directions are ignored and a warning is given.} +\item{graph}{The graph to run the model on. +If directed, then edge directions are ignored and a warning is given.} -\item{beta}{Non-negative scalar. The rate of infection of an individual that -is susceptible and has a single infected neighbor. The infection rate of a -susceptible individual with n infected neighbors is n times beta. Formally -this is the rate parameter of an exponential distribution.} +\item{beta}{Non-negative scalar. +The rate of infection of an individual that is susceptible and has a single infected neighbor. +The infection rate of a susceptible individual with n infected neighbors is n times beta. +Formally this is the rate parameter of an exponential distribution.} -\item{gamma}{Positive scalar. The rate of recovery of an infected -individual. Formally, this is the rate parameter of an exponential -distribution.} +\item{gamma}{Positive scalar. +The rate of recovery of an infected individual. +Formally, this is the rate parameter of an exponential distribution.} \item{no.sim}{Integer scalar, the number simulation runs to perform.} } \value{ -For \code{sir()} the results are returned in an object of class -\sQuote{\code{sir}}, which is a list, with one element for each simulation. -Each simulation is itself a list with the following elements. They are all -numeric vectors, with equal length: +For \code{sir()} the results are returned in an object of class \sQuote{\code{sir}}, which is a list, +with one element for each simulation. +Each simulation is itself a list with the following elements. +They are all numeric vectors, with equal length: \describe{ \item{times}{ The times of the events. @@ -73,38 +71,31 @@ The number of recovered individuals in the population, over time. } } -Function \code{time_bins()} returns a numeric vector, the middle or the -boundaries of the time bins, depending on the \code{middle} argument. +Function \code{time_bins()} returns a numeric vector, the middle or the boundaries of the time bins, depending on the \code{middle} argument. -\code{median} returns a list of three named numeric vectors, \code{NS}, -\code{NI} and \code{NR}. The names within the vectors are created from the -time bins. +\code{median} returns a list of three named numeric vectors, \code{NS}, \code{NI} and \code{NR}. +The names within the vectors are created from the time bins. -\code{quantile} returns the same vector as \code{median} (but only one, the -one requested) if only one quantile is requested. If multiple quantiles are -requested, then a list of these vectors is returned, one for each quantile. +\code{quantile} returns the same vector as \code{median} (but only one, the one requested) if only one quantile is requested. +If multiple quantiles are requested, then a list of these vectors is returned, one for each quantile. } \description{ -Run simulations for an SIR (susceptible-infected-recovered) model, on a -graph +Run simulations for an SIR (susceptible-infected-recovered) model, on a graph } \details{ -The SIR model is a simple model from epidemiology. The individuals of the -population might be in three states: susceptible, infected and recovered. -Recovered people are assumed to be immune to the disease. Susceptibles -become infected with a rate that depends on their number of infected -neighbors. Infected people become recovered with a constant rate. - -The function \code{sir()} simulates the model. This function runs multiple -simulations, all starting with a single uniformly randomly chosen infected -individual. A simulation is stopped when no infected individuals are left. - -Function \code{time_bins()} bins the simulation steps, using the -Freedman-Diaconis heuristics to determine the bin width. - -Function \code{median} and \code{quantile} calculate the median and -quantiles of the results, respectively, in bins calculated with -\code{time_bins()}. +The SIR model is a simple model from epidemiology. +The individuals of the population might be in three states: susceptible, infected and recovered. +Recovered people are assumed to be immune to the disease. +Susceptibles become infected with a rate that depends on their number of infected neighbors. +Infected people become recovered with a constant rate. + +The function \code{sir()} simulates the model. +This function runs multiple simulations, all starting with a single uniformly randomly chosen infected individual. +A simulation is stopped when no infected individuals are left. + +Function \code{time_bins()} bins the simulation steps, using the Freedman-Diaconis heuristics to determine the bin width. + +Function \code{median} and \code{quantile} calculate the median and quantiles of the results, respectively, in bins calculated with \code{time_bins()}. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Spatial-Games.html#igraph_sir}{\code{sir()}} diff --git a/man/spectrum.Rd b/man/spectrum.Rd index 2ada26141d0..0fd0cc0d410 100644 --- a/man/spectrum.Rd +++ b/man/spectrum.Rd @@ -15,15 +15,15 @@ spectrum( \arguments{ \item{graph}{The input graph, can be directed or undirected.} -\item{algorithm}{The algorithm to use. Currently only \code{arpack} is -implemented, which uses the ARPACK solver. See also \code{\link[=arpack]{arpack()}}.} +\item{algorithm}{The algorithm to use. +Currently only \code{arpack} is implemented, which uses the ARPACK solver. +See also \code{\link[=arpack]{arpack()}}.} -\item{which}{A list to specify which eigenvalues and eigenvectors to -calculate. By default the leading (i.e. largest magnitude) eigenvalue and -the corresponding eigenvector is calculated.} +\item{which}{A list to specify which eigenvalues and eigenvectors to calculate. +By default the leading (i.e. largest magnitude) eigenvalue and the corresponding eigenvector is calculated.} -\item{options}{Options for the ARPACK solver. See -\code{\link[=arpack_defaults]{arpack_defaults()}}.} +\item{options}{Options for the ARPACK solver. +See \code{\link[=arpack_defaults]{arpack_defaults()}}.} } \value{ Depends on the algorithm used. @@ -42,12 +42,10 @@ Numeric matrix, with the eigenvectors as columns. } } \description{ -Calculate selected eigenvalues and eigenvectors of a (supposedly sparse) -graph. +Calculate selected eigenvalues and eigenvectors of a (supposedly sparse) graph. } \details{ -The \code{which} argument is a list and it specifies which eigenvalues and -corresponding eigenvectors to calculate: There are eight options: +The \code{which} argument is a list and it specifies which eigenvalues and corresponding eigenvectors to calculate: There are eight options: \enumerate{ \item Eigenvalues with the largest magnitude. Set \code{pos} to \code{LM}, and \code{howmany} to the number of eigenvalues you want. \item Eigenvalues with the smallest magnitude. Set \code{pos} to \code{SM} and diff --git a/man/spinglass.community.Rd b/man/spinglass.community.Rd index e04e60c98e1..12db6f74af0 100644 --- a/man/spinglass.community.Rd +++ b/man/spinglass.community.Rd @@ -20,75 +20,65 @@ spinglass.community( ) } \arguments{ -\item{graph}{The input graph. Edge directions are ignored in directed graphs.} +\item{graph}{The input graph. +Edge directions are ignored in directed graphs.} -\item{weights}{The weights of the edges. It must be a positive numeric vector, -\code{NULL} or \code{NA}. If it is \code{NULL} and the input graph has a -\sQuote{weight} edge attribute, then that attribute will be used. If -\code{NULL} and no such attribute is present, then the edges will have equal -weights. Set this to \code{NA} if the graph was a \sQuote{weight} edge -attribute, but you don't want to use it for community detection. A larger -edge weight means a stronger connection for this function.} +\item{weights}{The weights of the edges. +It must be a positive numeric vector, \code{NULL} or \code{NA}. +If it is \code{NULL} and the input graph has a \sQuote{weight} edge attribute, then that attribute will be used. +If \code{NULL} and no such attribute is present, then the edges will have equal weights. +Set this to \code{NA} if the graph was a \sQuote{weight} edge attribute, but you don't want to use it for community detection. +A larger edge weight means a stronger connection for this function.} -\item{vertex}{This parameter can be used to calculate the community of a -given vertex without calculating all communities. Note that if this argument -is present then some other arguments are ignored.} +\item{vertex}{This parameter can be used to calculate the community of a given vertex without calculating all communities. +Note that if this argument is present then some other arguments are ignored.} -\item{spins}{Integer constant, the number of spins to use. This is the upper -limit for the number of communities. It is not a problem to supply a -(reasonably) big number here, in which case some spin states will be -unpopulated.} +\item{spins}{Integer constant, the number of spins to use. +This is the upper limit for the number of communities. +It is not a problem to supply a (reasonably) big number here, in which case some spin states will be unpopulated.} -\item{parupdate}{Logical, whether to update the spins of the -vertices in parallel (synchronously) or not. This argument is ignored if the -second form of the function is used (i.e. the \sQuote{\code{vertex}} argument -is present). It is also not implemented in the \dQuote{neg} implementation.} +\item{parupdate}{Logical, whether to update the spins of the vertices in parallel (synchronously) or not. +This argument is ignored if the second form of the function is used (i.e. the \sQuote{\code{vertex}} argument is present). +It is also not implemented in the \dQuote{neg} implementation.} -\item{start.temp}{Real constant, the start temperature. This argument is -ignored if the second form of the function is used (i.e. the -\sQuote{\code{vertex}} argument is present).} +\item{start.temp}{Real constant, +the start temperature. +This argument is ignored if the second form of the function is used (i.e. the \sQuote{\code{vertex}} argument is present).} -\item{stop.temp}{Real constant, the stop temperature. The simulation -terminates if the temperature lowers below this level. This argument is -ignored if the second form of the function is used (i.e. the -\sQuote{\code{vertex}} argument is present).} +\item{stop.temp}{Real constant, the stop temperature. +The simulation terminates if the temperature lowers below this level. +This argument is ignored if the second form of the function is used (i.e. the \sQuote{\code{vertex}} argument is present).} -\item{cool.fact}{Cooling factor for the simulated annealing. This argument -is ignored if the second form of the function is used (i.e. the -\sQuote{\code{vertex}} argument is present).} +\item{cool.fact}{Cooling factor for the simulated annealing. +This argument is ignored +if the second form of the function is used (i.e. the \sQuote{\code{vertex}} argument is present).} -\item{update.rule}{Character constant giving the \sQuote{null-model} of the -simulation. Possible values: \dQuote{simple} and \dQuote{config}. -\dQuote{simple} uses a random graph with the same number of edges as the -baseline probability and \dQuote{config} uses a random graph with the same -vertex degrees as the input graph.} +\item{update.rule}{Character constant giving the \sQuote{null-model} of the simulation. +Possible values: \dQuote{simple} and \dQuote{config}. +\dQuote{simple} uses a random graph with the same number of edges as the baseline probability and \dQuote{config} uses a random graph with the same vertex degrees as the input graph.} -\item{gamma}{Real constant, the gamma argument of the algorithm. This -specifies the balance between the importance of present and non-present -edges in a community. Roughly, a comunity is a set of vertices having many -edges inside the community and few edges outside the community. The default -1.0 value makes existing and non-existing links equally important. Smaller -values make the existing links, greater values the missing links more -important.} +\item{gamma}{Real constant, the gamma argument of the algorithm. +This specifies the balance between the importance of present and non-present edges in a community. +Roughly, a comunity is a set of vertices having many edges inside the community and few edges outside the community. +The default 1.0 value makes existing and non-existing links equally important. +Smaller values make the existing links, greater values the missing links more important.} -\item{implementation}{Character scalar. Currently igraph contains two -implementations for the Spin-glass community finding algorithm. The faster -original implementation is the default. The other implementation, that takes -into account negative weights, can be chosen by supplying \sQuote{neg} here.} +\item{implementation}{Character scalar. +Currently igraph contains two implementations for the Spin-glass community finding algorithm. +The faster original implementation is the default. +The other implementation, that takes into account negative weights, can be chosen by supplying \sQuote{neg} here.} -\item{gamma.minus}{Real constant, the gamma.minus parameter of the -algorithm. This specifies the balance between the importance of present and -non-present negative weighted edges in a community. Smaller values of -gamma.minus, leads to communities with lesser negative intra-connectivity. -If this argument is set to zero, the algorithm reduces to a graph coloring -algorithm, using the number of spins as the number of colors. This argument -is ignored if the \sQuote{orig} implementation is chosen.} +\item{gamma.minus}{Real constant, the gamma.minus parameter of the algorithm. +This specifies the balance between the importance of present and non-present negative weighted edges in a community. +Smaller values of gamma.minus, leads to communities with lesser negative intra-connectivity. +If this argument is set to zero, the algorithm reduces to a graph coloring algorithm, +using the number of spins as the number of colors. +This argument is ignored if the \sQuote{orig} implementation is chosen.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{spinglass.community()} was renamed to \code{\link[=cluster_spinglass]{cluster_spinglass()}} to create a more -consistent API. +\code{spinglass.community()} was renamed to \code{\link[=cluster_spinglass]{cluster_spinglass()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/split_join_distance.Rd b/man/split_join_distance.Rd index 2736fefffbd..6726960d903 100644 --- a/man/split_join_distance.Rd +++ b/man/split_join_distance.Rd @@ -15,25 +15,18 @@ split_join_distance(comm1, comm2) Two integer numbers, see details below. } \description{ -The split-join distance between partitions A and B is the sum of the -projection distance of A from B and the projection distance of B from -A. The projection distance is an asymmetric measure and it is defined as -follows: +The split-join distance between partitions A and B is the sum of the projection distance of A from B and the projection distance of B from A. The projection distance is an asymmetric measure and it is defined as follows: } \details{ -First, each set in partition A is evaluated against all sets in -partition B. For each set in partition A, the best matching set in -partition B is found and the overlap size is calculated. (Matching is -quantified by the size of the overlap between the two sets). Then, the -maximal overlap sizes for each set in A are summed together and -subtracted from the number of elements in A. +First, each set in partition A is evaluated against all sets in partition B. +For each set in partition A, the best matching set in partition B is found and the overlap size is calculated. +(Matching is quantified by the size of the overlap between the two sets). +Then, the maximal overlap sizes for each set in A are summed together and subtracted from the number of elements in A. -The split-join distance will be returned as two numbers, the first is -the projection distance of the first partition from the -second, while the second number is the projection distance of the second -partition from the first. This makes it easier to detect whether a -partition is a subpartition of the other, since in this case, the -corresponding distance will be zero. +The split-join distance will be returned as two numbers, the first is the projection distance of the first partition from the second, +while the second number is the projection distance of the second partition from the first. +This makes it easier to detect whether a partition is a subpartition of the other, since in this case, +the corresponding distance will be zero. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Community.html#igraph_split_join_distance}{\code{split_join_distance()}} diff --git a/man/stCuts.Rd b/man/stCuts.Rd index 437d55c739f..68cacde140e 100644 --- a/man/stCuts.Rd +++ b/man/stCuts.Rd @@ -7,7 +7,8 @@ stCuts(graph, source, target) } \arguments{ -\item{graph}{The input graph. It must be directed.} +\item{graph}{The input graph. +It must be directed.} \item{source}{The source vertex.} @@ -16,8 +17,7 @@ stCuts(graph, source, target) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{stCuts()} was renamed to \code{\link[=st_cuts]{st_cuts()}} to create a more -consistent API. +\code{stCuts()} was renamed to \code{\link[=st_cuts]{st_cuts()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Flows.html#igraph_all_st_cuts}{\code{all_st_cuts()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/stMincuts.Rd b/man/stMincuts.Rd index 855722247d1..a78a7a25eac 100644 --- a/man/stMincuts.Rd +++ b/man/stMincuts.Rd @@ -7,23 +7,21 @@ stMincuts(graph, source, target, capacity = NULL) } \arguments{ -\item{graph}{The input graph. It must be directed.} +\item{graph}{The input graph. +It must be directed.} \item{source}{The ID of the source vertex.} \item{target}{The ID of the target vertex.} -\item{capacity}{Numeric vector giving the edge capacities. If this is -\code{NULL} and the graph has a \code{weight} edge attribute, then this -attribute defines the edge capacities. For forcing unit edge capacities, -even for graphs that have a \code{weight} edge attribute, supply \code{NA} -here.} +\item{capacity}{Numeric vector giving the edge capacities. +If this is \code{NULL} and the graph has a \code{weight} edge attribute, then this attribute defines the edge capacities. +For forcing unit edge capacities, even for graphs that have a \code{weight} edge attribute, supply \code{NA} here.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{stMincuts()} was renamed to \code{\link[=st_min_cuts]{st_min_cuts()}} to create a more -consistent API. +\code{stMincuts()} was renamed to \code{\link[=st_min_cuts]{st_min_cuts()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Flows.html#igraph_all_st_mincuts}{\code{all_st_mincuts()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/st_cuts.Rd b/man/st_cuts.Rd index 1a19298155f..c8f6dddff8d 100644 --- a/man/st_cuts.Rd +++ b/man/st_cuts.Rd @@ -7,7 +7,8 @@ st_cuts(graph, source, target) } \arguments{ -\item{graph}{The input graph. It must be directed.} +\item{graph}{The input graph. +It must be directed.} \item{source}{The source vertex.} @@ -32,10 +33,8 @@ generates the cut that contains exactly the edges that go from \eqn{X} to \eqn{V List all (s,t)-cuts in a directed graph. } \details{ -Given a \eqn{G} directed graph and two, different and non-ajacent vertices, -\eqn{s} and \eqn{t}, an \eqn{(s,t)}-cut is a set of edges, such that after -removing these edges from \eqn{G} there is no directed path from \eqn{s} to -\eqn{t}. +Given a \eqn{G} directed graph and two, different and non-ajacent vertices, \eqn{s} and \eqn{t}, an \eqn{(s,t)}-cut is a set of edges, +such that after removing these edges from \eqn{G} there is no directed path from \eqn{s} to \eqn{t}. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Flows.html#igraph_all_st_cuts}{\code{all_st_cuts()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/st_min_cuts.Rd b/man/st_min_cuts.Rd index 9f0bbba1dcd..dafbf231acd 100644 --- a/man/st_min_cuts.Rd +++ b/man/st_min_cuts.Rd @@ -7,7 +7,8 @@ st_min_cuts(graph, source, target, ..., capacity = NULL) } \arguments{ -\item{graph}{The input graph. It must be directed.} +\item{graph}{The input graph. +It must be directed.} \item{source}{The ID of the source vertex.} @@ -15,11 +16,9 @@ st_min_cuts(graph, source, target, ..., capacity = NULL) \item{...}{These dots are for future extensions and must be empty.} -\item{capacity}{Numeric vector giving the edge capacities. If this is -\code{NULL} and the graph has a \code{weight} edge attribute, then this -attribute defines the edge capacities. For forcing unit edge capacities, -even for graphs that have a \code{weight} edge attribute, supply \code{NA} -here.} +\item{capacity}{Numeric vector giving the edge capacities. +If this is \code{NULL} and the graph has a \code{weight} edge attribute, then this attribute defines the edge capacities. +For forcing unit edge capacities, even for graphs that have a \code{weight} edge attribute, supply \code{NA} here.} } \value{ A list with entries: @@ -40,18 +39,14 @@ generates the cut that contains exactly the edges that go from \eqn{X} to \eqn{V } } \description{ -Listing all minimum \eqn{(s,t)}-cuts of a directed graph, for given \eqn{s} -and \eqn{t}. +Listing all minimum \eqn{(s,t)}-cuts of a directed graph, for given \eqn{s} and \eqn{t}. } \details{ -Given a \eqn{G} directed graph and two, different and non-ajacent vertices, -\eqn{s} and \eqn{t}, an \eqn{(s,t)}-cut is a set of edges, such that after -removing these edges from \eqn{G} there is no directed path from \eqn{s} to -\eqn{t}. +Given a \eqn{G} directed graph and two, different and non-ajacent vertices, \eqn{s} and \eqn{t}, an \eqn{(s,t)}-cut is a set of edges, +such that after removing these edges from \eqn{G} there is no directed path from \eqn{s} to \eqn{t}. -The size of an \eqn{(s,t)}-cut is defined as the sum of the capacities (or -weights) in the cut. For unweighted (=equally weighted) graphs, this is -simply the number of edges. +The size of an \eqn{(s,t)}-cut is defined as the sum of the capacities (or weights) in the cut. +For unweighted (=equally weighted) graphs, this is simply the number of edges. An \eqn{(s,t)}-cut is minimum if it is of the smallest possible size. } diff --git a/man/static.fitness.game.Rd b/man/static.fitness.game.Rd index ebbe3322ae5..f113981e991 100644 --- a/man/static.fitness.game.Rd +++ b/man/static.fitness.game.Rd @@ -24,14 +24,12 @@ Default: \code{NULL}, the generated graph will be undirected.} \item{loops}{Logical, whether to allow loop edges in the graph.} -\item{multiple}{Logical, whether to allow multiple edges in the -graph.} +\item{multiple}{Logical, whether to allow multiple edges in the graph.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{static.fitness.game()} was renamed to \code{\link[=sample_fitness]{sample_fitness()}} to create a more -consistent API. +\code{static.fitness.game()} was renamed to \code{\link[=sample_fitness]{sample_fitness()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_static_fitness_game}{\code{static_fitness_game()}} diff --git a/man/static.power.law.game.Rd b/man/static.power.law.game.Rd index 77f359c4acd..b0e943bc001 100644 --- a/man/static.power.law.game.Rd +++ b/man/static.power.law.game.Rd @@ -19,29 +19,25 @@ static.power.law.game( \item{no.of.edges}{The number of edges in the generated graph.} -\item{exponent.out}{Numeric scalar, the power law exponent of the degree -distribution. For directed graphs, this specifies the exponent of the -out-degree distribution. It must be greater than or equal to 2. If you pass -\code{Inf} here, you will get back an Erdős-Rényi random network.} +\item{exponent.out}{Numeric scalar, the power law exponent of the degree distribution. +For directed graphs, this specifies the exponent of the out-degree distribution. +It must be greater than or equal to 2. If you pass \code{Inf} here, you will get back an Erdős-Rényi random network.} -\item{exponent.in}{Numeric scalar. If negative, the generated graph will be -undirected. If greater than or equal to 2, this argument specifies the -exponent of the in-degree distribution. If non-negative but less than 2, an -error will be generated.} +\item{exponent.in}{Numeric scalar. +If negative, the generated graph will be undirected. +If greater than or equal to 2, this argument specifies the exponent of the in-degree distribution. +If non-negative but less than 2, an error will be generated.} \item{loops}{Logical, whether to allow loop edges in the graph.} -\item{multiple}{Logical, whether to allow multiple edges in the -graph.} +\item{multiple}{Logical, whether to allow multiple edges in the graph.} -\item{finite.size.correction}{Logical, whether to use the proposed -finite size correction of Cho et al., see references below.} +\item{finite.size.correction}{Logical, whether to use the proposed finite size correction of Cho et al., see references below.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{static.power.law.game()} was renamed to \code{\link[=sample_fitness_pl]{sample_fitness_pl()}} to create a more -consistent API. +\code{static.power.law.game()} was renamed to \code{\link[=sample_fitness_pl]{sample_fitness_pl()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_static_power_law_game}{\code{static_power_law_game()}} diff --git a/man/stochastic_matrix.Rd b/man/stochastic_matrix.Rd index 3c1ad6b6e19..c6e581b7286 100644 --- a/man/stochastic_matrix.Rd +++ b/man/stochastic_matrix.Rd @@ -7,32 +7,30 @@ stochastic_matrix(graph, ..., column.wise = FALSE, sparse = NULL) } \arguments{ -\item{graph}{The input graph. Must be of class \code{igraph}.} +\item{graph}{The input graph. +Must be of class \code{igraph}.} \item{...}{These dots are for future extensions and must be empty.} -\item{column.wise}{If \code{FALSE}, then the rows of the stochastic matrix -sum up to one; otherwise it is the columns.} +\item{column.wise}{If \code{FALSE}, then the rows of the stochastic matrix sum up to one; otherwise it is the columns.} -\item{sparse}{Logical, whether to return a sparse matrix. The -\code{Matrix} package is needed for sparse matrices. The default \code{NULL} uses -the \code{sparsematrices} igraph option.} +\item{sparse}{Logical, whether to return a sparse matrix. +The \code{Matrix} package is needed for sparse matrices. +The default \code{NULL} uses the \code{sparsematrices} igraph option.} } \value{ -A regular matrix or a matrix of class \code{Matrix} if a -\code{sparse} argument was \code{TRUE}. +A regular matrix or a matrix of class \code{Matrix} if a \code{sparse} argument was \code{TRUE}. } \description{ Retrieves the stochastic matrix of a graph of class \code{igraph}. } \details{ -Let \eqn{M} be an \eqn{n \times n}{n x n} adjacency matrix with real -non-negative entries. Let us define \eqn{D = \textrm{diag}(\sum_{i}M_{1i}, +Let \eqn{M} be an \eqn{n \times n}{n x n} adjacency matrix with real non-negative entries. +Let us define \eqn{D = \textrm{diag}(\sum_{i}M_{1i}, \dots, \sum_{i}M_{ni})}{D=diag( sum(M[1,i], i), ..., sum(M[n,i], i) )} -The (row) stochastic matrix is defined as \deqn{W = D^{-1}M,}{W = inv(D) M,} -where it is assumed that \eqn{D} is non-singular. Column stochastic -matrices are defined in a symmetric way. +The (row) stochastic matrix is defined as \deqn{W = D^{-1}M,}{W = inv(D) M,} where it is assumed that \eqn{D} is non-singular. +Column stochastic matrices are defined in a symmetric way. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_stochastic}{\code{get_stochastic()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_stochastic_sparse}{\code{get_stochastic_sparse()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/strength.Rd b/man/strength.Rd index cf0e0765c59..69448d86a83 100644 --- a/man/strength.Rd +++ b/man/strength.Rd @@ -21,17 +21,15 @@ The default \code{NULL} selects all vertices.} \item{...}{These dots are for future extensions and must be empty.} -\item{mode}{Character string, \dQuote{out} for out-degree, \dQuote{in} for -in-degree or \dQuote{all} for the sum of the two. For undirected graphs this -argument is ignored.} +\item{mode}{Character string, \dQuote{out} for out-degree, \dQuote{in} for in-degree or \dQuote{all} for the sum of the two. +For undirected graphs this argument is ignored.} \item{loops}{Logical; whether the loop edges are also counted.} -\item{weights}{Weight vector. If the graph has a \code{weight} edge -attribute, then this is used by default. If the graph does not have a -\code{weight} edge attribute and this argument is \code{NULL}, then a -\code{\link[=degree]{degree()}} is called. If this is \code{NA}, then no edge weights are used -(even if the graph has a \code{weight} edge attribute).} +\item{weights}{Weight vector. +If the graph has a \code{weight} edge attribute, then this is used by default. +If the graph does not have a \code{weight} edge attribute and this argument is \code{NULL}, then a \code{\link[=degree]{degree()}} is called. +If this is \code{NA}, then no edge weights are used (even if the graph has a \code{weight} edge attribute).} } \value{ A numeric vector giving the strength of the vertices. diff --git a/man/sub-.igraph.Rd b/man/sub-.igraph.Rd index 3f19eec0626..aa6990c2abb 100644 --- a/man/sub-.igraph.Rd +++ b/man/sub-.igraph.Rd @@ -20,27 +20,27 @@ \arguments{ \item{x}{The graph.} -\item{i}{Index. Vertex IDs or names or logical vectors. See details -below.} +\item{i}{Index. +Vertex IDs or names or logical vectors. +See details below.} -\item{j}{Index. Vertex IDs or names or logical vectors. See details -below.} +\item{j}{Index. +Vertex IDs or names or logical vectors. +See details below.} \item{...}{Currently ignored.} -\item{from}{A numeric or character vector giving vertex IDs or -names. Together with the \code{to} argument, it can be used to -query/set a sequence of edges. See details below. This argument cannot -be present together with any of the \code{i} and \code{j} arguments -and if it is present, then the \code{to} argument must be present as -well.} +\item{from}{A numeric or character vector giving vertex IDs or names. +Together with the \code{to} argument, it can be used to query/set a sequence of edges. +See details below. +This argument cannot be present together with any of the \code{i} and \code{j} arguments and if it is present, +then the \code{to} argument must be present as well.} -\item{to}{A numeric or character vector giving vertex IDs or -names. Together with the \code{from} argument, it can be used to -query/set a sequence of edges. See details below. This argument cannot -be present together with any of the \code{i} and \code{j} arguments -and if it is present, then the \code{from} argument must be present as -well.} +\item{to}{A numeric or character vector giving vertex IDs or names. +Together with the \code{from} argument, it can be used to query/set a sequence of edges. +See details below. +This argument cannot be present together with any of the \code{i} and \code{j} arguments and if it is present, +then the \code{from} argument must be present as well.} \item{sparse}{Logical, whether to return sparse matrices.} @@ -48,18 +48,20 @@ well.} \item{drop}{Ignored.} -\item{attr}{Name of an edge attribute. This attribute is queried and returned. +\item{attr}{Name of an edge attribute. +This attribute is queried and returned. Default: \code{NULL}.} } \value{ -A scalar or matrix. See details below. +A scalar or matrix. +See details below. } \description{ Query and manipulate a graph as it were an adjacency matrix } \details{ -The single bracket indexes the (possibly weighted) adjacency matrix of -the graph. Here is what you can do with it: +The single bracket indexes the (possibly weighted) adjacency matrix of the graph. +Here is what you can do with it: \enumerate{ \item Check whether there is an edge between two vertices (\eqn{v} @@ -72,17 +74,15 @@ graph[1:3,5:6] graph[c(1,3,5),]} The first variants returns the full adjacency matrix, the other two return part of it. -\item The \code{from} and \code{to} arguments can be used to check -the existence of many edges. In this case, both \code{from} and -\code{to} must be present and they must have the same length. They -must contain vertex IDs or names. A numeric vector is returned, of -the same length as \code{from} and \code{to}, it contains ones -for existing edges edges and zeros for non-existing ones. +\item The \code{from} and \code{to} arguments can be used to check the existence of many edges. +In this case, both \code{from} and \code{to} must be present and they must have the same length. +They must contain vertex IDs or names. +A numeric vector is returned, of the same length as \code{from} and \code{to}, it contains ones for existing edges edges +and zeros for non-existing ones. Example: \preformatted{ graph[from=1:3, to=c(2,3,5)]}. -\item For weighted graphs, the \code{[} operator returns the edge -weights. For non-esistent edges zero weights are returned. Other -edge attributes can be queried as well, by giving the \code{attr} -argument. +\item For weighted graphs, the \code{[} operator returns the edge weights. +For non-esistent edges zero weights are returned. +Other edge attributes can be queried as well, by giving the \code{attr} argument. \item Querying edge IDs instead of the existance of edges or edge attributes. E.g. \preformatted{ graph[1, 2, edges=TRUE]} returns the ID of the edge between vertices 1 and 2, or zero if @@ -98,10 +98,8 @@ i.e. no multiple edges are created. contains the name of the edge attribute to set, so it does not have to be \sQuote{weight}: \preformatted{ graph[1, 2, attr="weight"]<- 5 graph[from=1:3, to=c(2,3,5)] <- c(1,-1,4)} -If an edge is already present in the network, then only its -weights or other attribute are updated. If the graph is already -weighted, then the \code{attr="weight"} setting is implicit, and -one does not need to give it explicitly. +If an edge is already present in the network, then only its weights or other attribute are updated. +If the graph is already weighted, then the \code{attr="weight"} setting is implicit, and one does not need to give it explicitly. \item Deleting edges. The replacement syntax allow the deletion of edges, by specifying \code{FALSE} or \code{NULL} as the replacement value: \preformatted{ graph[v, w] <- FALSE} @@ -120,8 +118,7 @@ G[-1,1] <- TRUE} creates a star graph. Of course, the indexing operators support vertex names, -so instead of a numeric vertex ID a vertex can also be given to -\sQuote{\code{[}} and \sQuote{\code{[[}}. +so instead of a numeric vertex ID a vertex can also be given to \sQuote{\code{[}} and \sQuote{\code{[[}}. } \seealso{ Other structural queries: diff --git a/man/sub-sub-.igraph.Rd b/man/sub-sub-.igraph.Rd index 18a46757e5d..ba4c1da8de9 100644 --- a/man/sub-sub-.igraph.Rd +++ b/man/sub-sub-.igraph.Rd @@ -13,24 +13,22 @@ \item{j}{Index, integer, character or logical, see details below.} -\item{from}{A numeric or character vector giving vertex IDs or -names. Together with the \code{to} argument, it can be used to -query/set a sequence of edges. See details below. This argument cannot -be present together with any of the \code{i} and \code{j} arguments -and if it is present, then the \code{to} argument must be present as -well.} +\item{from}{A numeric or character vector giving vertex IDs or names. +Together with the \code{to} argument, it can be used to query/set a sequence of edges. +See details below. +This argument cannot be present together with any of the \code{i} and \code{j} arguments and if it is present, +then the \code{to} argument must be present as well.} -\item{to}{A numeric or character vector giving vertex IDs or -names. Together with the \code{from} argument, it can be used to -query/set a sequence of edges. See details below. This argument cannot -be present together with any of the \code{i} and \code{j} arguments -and if it is present, then the \code{from} argument must be present as -well.} +\item{to}{A numeric or character vector giving vertex IDs or names. +Together with the \code{from} argument, it can be used to query/set a sequence of edges. +See details below. +This argument cannot be present together with any of the \code{i} and \code{j} arguments and if it is present, +then the \code{from} argument must be present as well.} \item{...}{Additional arguments are not used currently.} -\item{directed}{Logical, whether to consider edge directions -in directed graphs. It is ignored for undirected graphs.} +\item{directed}{Logical, whether to consider edge directions in directed graphs. +It is ignored for undirected graphs.} \item{edges}{Logical, whether to return edge IDs.} @@ -40,8 +38,8 @@ in directed graphs. It is ignored for undirected graphs.} Query and manipulate a graph as it were an adjacency list } \details{ -The double bracket operator indexes the (imaginary) adjacency list -of the graph. This can used for the following operations: +The double bracket operator indexes the (imaginary) adjacency list of the graph. +This can used for the following operations: \enumerate{ \item Querying the adjacent vertices for one or more vertices: \preformatted{ graph[[1:3,]] @@ -58,16 +56,13 @@ gives the edge IDs of all the edges that exist from vertices \eqn{v} to vertices \eqn{w}. } -The alternative argument names \code{from} and \code{to} can be used -instead of the usual \code{i} and \code{j}, to make the code more +The alternative argument names \code{from} and \code{to} can be used instead of the usual \code{i} and \code{j}, to make the code more readable: \preformatted{ graph[[from = 1:3]] graph[[from = v, to = w, edges = TRUE]]} -\sQuote{\code{[[}} operators allows logical indices and negative indices -as well, with the usual R semantics. +\sQuote{\code{[[}} operators allows logical indices and negative indices as well, with the usual R semantics. -Vertex names are also supported, so instead of a numeric vertex ID a -vertex can also be given to \sQuote{\code{[}} and \sQuote{\code{[[}}. +Vertex names are also supported, so instead of a numeric vertex ID a vertex can also be given to \sQuote{\code{[}} and \sQuote{\code{[[}}. } \seealso{ Other structural queries: diff --git a/man/subcomponent.Rd b/man/subcomponent.Rd index cd4092391cd..c80f28501b7 100644 --- a/man/subcomponent.Rd +++ b/man/subcomponent.Rd @@ -13,19 +13,18 @@ subcomponent(graph, v, ..., mode = c("all", "out", "in")) \item{...}{These dots are for future extensions and must be empty.} -\item{mode}{Character string, either \dQuote{in}, \dQuote{out} or -\dQuote{all}. If \dQuote{in} all vertices from which \code{v} is reachable -are listed. If \dQuote{out} all vertices reachable from \code{v} are -returned. If \dQuote{all} returns the union of these. It is ignored for -undirected graphs.} +\item{mode}{Character string, either \dQuote{in}, \dQuote{out} or \dQuote{all}. +If \dQuote{in} all vertices from which \code{v} is reachable are listed. +If \dQuote{out} all vertices reachable from \code{v} are returned. +If \dQuote{all} returns the union of these. +It is ignored for undirected graphs.} } \value{ -Numeric vector, the IDs of the vertices in the same component as -\code{v}. +Numeric vector, the IDs of the vertices in the same component as \code{v}. } \description{ -Finds all vertices reachable from a given vertex, or the opposite: all -vertices from which a given vertex is reachable via a directed path. +Finds all vertices reachable from a given vertex, or the opposite: +all vertices from which a given vertex is reachable via a directed path. } \details{ A breadth-first search is conducted starting from vertex \code{v}. diff --git a/man/subgraph.Rd b/man/subgraph.Rd index fd06736e8e7..4dfbc1dd999 100644 --- a/man/subgraph.Rd +++ b/man/subgraph.Rd @@ -20,45 +20,37 @@ subgraph_from_edges(graph, eids, ..., delete.vertices = TRUE) \arguments{ \item{graph}{The original graph.} -\item{vids}{Numeric vector, the vertices of the original graph which will -form the subgraph.} +\item{vids}{Numeric vector, the vertices of the original graph which will form the subgraph.} \item{...}{These dots are for future extensions and must be empty.} -\item{impl}{Character scalar, to choose between two implementation of the -subgraph calculation. \sQuote{\code{copy_and_delete}} copies the graph -first, and then deletes the vertices and edges that are not included in the -result graph. \sQuote{\code{create_from_scratch}} searches for all vertices -and edges that must be kept and then uses them to create the graph from -scratch. \sQuote{\code{auto}} chooses between the two implementations -automatically, using heuristics based on the size of the original and the -result graph.} +\item{impl}{Character scalar, to choose between two implementation of the subgraph calculation. +\sQuote{\code{copy_and_delete}} copies the graph first, and then deletes the vertices and edges that are not included in the result graph. +\sQuote{\code{create_from_scratch}} searches for all vertices and edges that must be kept and then uses them to create the graph from scratch. +\sQuote{\code{auto}} chooses between the two implementations automatically, +using heuristics based on the size of the original and the result graph.} \item{eids}{The edge IDs of the edges that will be kept in the result graph.} -\item{delete.vertices}{Logical, whether to remove vertices that do -not have any adjacent edges in \code{eids}.} +\item{delete.vertices}{Logical, whether to remove vertices that do not have any adjacent edges in \code{eids}.} } \value{ A new graph object. } \description{ -\code{subgraph()} creates a subgraph of a graph, containing only the specified -vertices and all the edges among them. +\code{subgraph()} creates a subgraph of a graph, containing only the specified vertices and all the edges among them. } \details{ -\code{induced_subgraph()} calculates the induced subgraph of a set of vertices -in a graph. This means that exactly the specified vertices and all the edges -between them will be kept in the result graph. +\code{induced_subgraph()} calculates the induced subgraph of a set of vertices in a graph. +This means that exactly the specified vertices and all the edges between them will be kept in the result graph. -\code{subgraph_from_edges()} calculates the subgraph of a graph. For this function -one can specify the vertices and edges to keep. This function will be -renamed to \code{subgraph()} in the next major version of igraph. +\code{subgraph_from_edges()} calculates the subgraph of a graph. +For this function one can specify the vertices and edges to keep. +This function will be renamed to \code{subgraph()} in the next major version of igraph. -The \code{subgraph()} function currently does the same as \code{induced_subgraph()} -(assuming \sQuote{\code{auto}} as the \code{impl} argument), but this behaviour -is deprecated. In the next major version, \code{subgraph()} will overtake the -functionality of \code{subgraph_from_edges()}. +The \code{subgraph()} function currently does the same as \code{induced_subgraph()} (assuming \sQuote{\code{auto}} as the \code{impl} argument), +but this behaviour is deprecated. +In the next major version, \code{subgraph()} will overtake the functionality of \code{subgraph_from_edges()}. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Operators.html#igraph_induced_subgraph}{\code{induced_subgraph()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Operators.html#igraph_subgraph_from_edges}{\code{subgraph_from_edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/subgraph.centrality.Rd b/man/subgraph.centrality.Rd index ae93e36ddcb..09a215c4797 100644 --- a/man/subgraph.centrality.Rd +++ b/man/subgraph.centrality.Rd @@ -7,17 +7,16 @@ subgraph.centrality(graph, diag = FALSE) } \arguments{ -\item{graph}{The input graph. It will be treated as undirected.} +\item{graph}{The input graph. +It will be treated as undirected.} -\item{diag}{Logical, whether to include the diagonal of the adjacency -matrix in the analysis. Giving \code{FALSE} here effectively eliminates the -loops edges from the graph before the calculation.} +\item{diag}{Logical, whether to include the diagonal of the adjacency matrix in the analysis. +Giving \code{FALSE} here effectively eliminates the loops edges from the graph before the calculation.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{subgraph.centrality()} was renamed to \code{\link[=subgraph_centrality]{subgraph_centrality()}} to create a more -consistent API. +\code{subgraph.centrality()} was renamed to \code{\link[=subgraph_centrality]{subgraph_centrality()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_is_directed}{\code{is_directed()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_adjacency}{\code{get_adjacency()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_adjacency_sparse}{\code{get_adjacency_sparse()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/subgraph.edges.Rd b/man/subgraph.edges.Rd index 903f76914bf..46e9e07889a 100644 --- a/man/subgraph.edges.Rd +++ b/man/subgraph.edges.Rd @@ -11,14 +11,12 @@ subgraph.edges(graph, eids, delete.vertices = TRUE) \item{eids}{The edge IDs of the edges that will be kept in the result graph.} -\item{delete.vertices}{Logical, whether to remove vertices that do -not have any adjacent edges in \code{eids}.} +\item{delete.vertices}{Logical, whether to remove vertices that do not have any adjacent edges in \code{eids}.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{subgraph.edges()} was renamed to \code{\link[=subgraph_from_edges]{subgraph_from_edges()}} to create a more -consistent API. +\code{subgraph.edges()} was renamed to \code{\link[=subgraph_from_edges]{subgraph_from_edges()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Operators.html#igraph_subgraph_from_edges}{\code{subgraph_from_edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/subgraph_centrality.Rd b/man/subgraph_centrality.Rd index 6b41cffc902..bc4ee2fe36f 100644 --- a/man/subgraph_centrality.Rd +++ b/man/subgraph_centrality.Rd @@ -7,29 +7,26 @@ subgraph_centrality(graph, ..., diag = FALSE) } \arguments{ -\item{graph}{The input graph. It will be treated as undirected.} +\item{graph}{The input graph. +It will be treated as undirected.} \item{...}{These dots are for future extensions and must be empty.} -\item{diag}{Logical, whether to include the diagonal of the adjacency -matrix in the analysis. Giving \code{FALSE} here effectively eliminates the -loops edges from the graph before the calculation.} +\item{diag}{Logical, whether to include the diagonal of the adjacency matrix in the analysis. +Giving \code{FALSE} here effectively eliminates the loops edges from the graph before the calculation.} } \value{ A numeric vector, the subgraph centrality scores of the vertices. } \description{ -Subgraph centrality of a vertex measures the number of subgraphs a vertex -participates in, weighting them according to their size. +Subgraph centrality of a vertex measures the number of subgraphs a vertex participates in, weighting them according to their size. } \details{ -The subgraph centrality of a vertex is defined as the number of closed walks -originating at the vertex, where longer walks are downweighted by the -factorial of their length. +The subgraph centrality of a vertex is defined as the number of closed walks originating at the vertex, +where longer walks are downweighted by the factorial of their length. -Currently the calculation is performed by explicitly calculating all -eigenvalues and eigenvectors of the adjacency matrix of the graph. This -effectively means that the measure can only be calculated for small graphs. +Currently the calculation is performed by explicitly calculating all eigenvalues and eigenvectors of the adjacency matrix of the graph. +This effectively means that the measure can only be calculated for small graphs. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_is_directed}{\code{is_directed()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_adjacency}{\code{get_adjacency()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_get_adjacency_sparse}{\code{get_adjacency_sparse()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/subgraph_isomorphic.Rd b/man/subgraph_isomorphic.Rd index 9e94afaaea9..7ae25ab58af 100644 --- a/man/subgraph_isomorphic.Rd +++ b/man/subgraph_isomorphic.Rd @@ -17,36 +17,33 @@ is_subgraph_isomorphic_to( ) } \arguments{ -\item{pattern}{The smaller graph, it might be directed or -undirected. Undirected graphs are treated as directed graphs with -mutual edges.} +\item{pattern}{The smaller graph, it might be directed or undirected. +Undirected graphs are treated as directed graphs with mutual edges.} -\item{target}{The bigger graph, it might be directed or -undirected. Undirected graphs are treated as directed graphs with -mutual edges.} +\item{target}{The bigger graph, it might be directed or undirected. +Undirected graphs are treated as directed graphs with mutual edges.} -\item{method}{The method to use. Possible values: \sQuote{auto}, -\sQuote{lad}, \sQuote{vf2}. See their details below.} +\item{method}{The method to use. +Possible values: \sQuote{auto}, \sQuote{lad}, \sQuote{vf2}. +See their details below.} \item{...}{Additional arguments, passed to the various methods.} } \value{ -Logical scalar, \code{TRUE} if the \code{pattern} is -isomorphic to a (possibly induced) subgraph of \code{target}. +Logical scalar, \code{TRUE} if the \code{pattern} is isomorphic to a (possibly induced) subgraph of \code{target}. } \description{ Decide if a graph is subgraph isomorphic to another one } \section{\sQuote{auto} method}{ -This method currently selects \sQuote{lad}, always, as it seems -to be superior on most graphs. +This method currently selects \sQuote{lad}, always, as it seems to be superior on most graphs. } \section{\sQuote{lad} method}{ -This is the LAD algorithm by Solnon, see the reference below. It has -the following extra arguments: +This is the LAD algorithm by Solnon, see the reference below. +It has the following extra arguments: \describe{ \item{domains}{ Matching restrictions. @@ -68,9 +65,8 @@ It defaults to \code{Inf}, which means no limit. \section{\sQuote{vf2} method}{ -This method uses the VF2 algorithm by Cordella, Foggia et al., see -references below. It supports vertex and edge colors and have the -following extra arguments: +This method uses the VF2 algorithm by Cordella, Foggia et al., see references below. +It supports vertex and edge colors and have the following extra arguments: \describe{ \item{vertex.color1, vertex.color2}{ Optional integer vectors giving the colors of the vertices for colored graph isomorphism. diff --git a/man/subgraph_isomorphisms.Rd b/man/subgraph_isomorphisms.Rd index 15a9c99fa2a..03e97138de4 100644 --- a/man/subgraph_isomorphisms.Rd +++ b/man/subgraph_isomorphisms.Rd @@ -14,45 +14,42 @@ subgraph_isomorphisms( ) } \arguments{ -\item{pattern}{The smaller graph, it might be directed or -undirected. Undirected graphs are treated as directed graphs with -mutual edges.} +\item{pattern}{The smaller graph, it might be directed or undirected. +Undirected graphs are treated as directed graphs with mutual edges.} -\item{target}{The bigger graph, it might be directed or -undirected. Undirected graphs are treated as directed graphs with -mutual edges.} +\item{target}{The bigger graph, it might be directed or undirected. +Undirected graphs are treated as directed graphs with mutual edges.} -\item{method}{The method to use. Possible values: \sQuote{auto}, -\sQuote{lad}, \sQuote{vf2}. See their details below.} +\item{method}{The method to use. +Possible values: \sQuote{auto}, \sQuote{lad}, \sQuote{vf2}. +See their details below.} \item{...}{Additional arguments, passed to the various methods.} \item{callback}{Optional callback function to call for each subisomorphism found. -If provided, the function should accept two arguments: \code{map12} (integer vector -mapping vertex IDs from pattern to target, 1-based indexing) and \code{map21} -(integer vector mapping vertex IDs from target to pattern, 1-based indexing). +If provided, the function should accept two arguments: +\code{map12} (integer vector mapping vertex IDs from pattern to target, 1-based indexing) and \code{map21} (integer vector mapping vertex IDs from target to pattern, 1-based indexing). The function should return \code{FALSE} to continue the search or \code{TRUE} to stop it. If \code{NULL} (the default), all subisomorphisms are collected and returned as a list. Only supported for \code{method = "vf2"}. -\strong{Important limitation:} Callback functions must NOT call any igraph -functions (including simple queries like \code{vcount()} or \code{ecount()}). Doing -so will cause R to crash due to reentrancy issues. Extract -any needed graph information before calling the function with a callback, or -use collector mode (the default) and process results afterward.} +\strong{Important limitation:} Callback functions must NOT call any igraph functions (including simple queries like \code{vcount()} or \code{ecount()}). +Doing so will cause R to crash due to reentrancy issues. +Extract any needed graph information before calling the function with a callback, +or use collector mode (the default) and process results afterward.} } \value{ -If \code{callback} is \code{NULL}, returns a list of vertex sequences, corresponding -to all mappings from the pattern graph to the target graph. If \code{callback} is -provided, returns \code{NULL} invisibly. +If \code{callback} is \code{NULL}, returns a list of vertex sequences, +corresponding to all mappings from the pattern graph to the target graph. +If \code{callback} is provided, returns \code{NULL} invisibly. } \description{ All isomorphic mappings between a graph and subgraphs of another graph } \section{\sQuote{lad} method}{ -This is the LAD algorithm by Solnon, see the reference below. It has -the following extra arguments: +This is the LAD algorithm by Solnon, see the reference below. +It has the following extra arguments: \describe{ \item{domains}{ Matching restrictions. @@ -74,9 +71,8 @@ It defaults to \code{Inf}, which means no limit. \section{\sQuote{vf2} method}{ -This method uses the VF2 algorithm by Cordella, Foggia et al., see -references below. It supports vertex and edge colors and have the -following extra arguments: +This method uses the VF2 algorithm by Cordella, Foggia et al., see references below. +It supports vertex and edge colors and have the following extra arguments: \describe{ \item{vertex.color1, vertex.color2}{ Optional integer vectors giving the colors of the vertices for colored graph isomorphism. diff --git a/man/tail_of.Rd b/man/tail_of.Rd index 91f16cab2a1..c223e227805 100644 --- a/man/tail_of.Rd +++ b/man/tail_of.Rd @@ -15,9 +15,8 @@ tail_of(graph, es) A vertex sequence with the tail(s) of the edge(s). } \description{ -For undirected graphs, head and tail is not defined. In this case -\code{tail_of()} returns vertices incident to the supplied edges, and -\code{head_of()} returns the other end(s) of the edge(s). +For undirected graphs, head and tail is not defined. +In this case \code{tail_of()} returns vertices incident to the supplied edges, and \code{head_of()} returns the other end(s) of the edge(s). } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/tkplot.Rd b/man/tkplot.Rd index a7f79ec88ad..246243c5fff 100644 --- a/man/tkplot.Rd +++ b/man/tkplot.Rd @@ -41,9 +41,8 @@ tk_canvas(tkp.id) \item{canvas.width, canvas.height}{The size of the tkplot drawing area.} -\item{\dots}{For \code{tkplot()}, additional plotting parameters, see -\link{igraph.plotting} for the complete list. For \code{tk_close()}, \code{tk_fit()}, -\code{tk_coords()} and \code{tk_rotate()}, these dots must be empty.} +\item{\dots}{For \code{tkplot()}, additional plotting parameters, see \link{igraph.plotting} for the complete list. +For \code{tk_close()}, \code{tk_fit()}, \code{tk_coords()} and \code{tk_rotate()}, these dots must be empty.} \item{tkp.id}{The ID of the tkplot window to close/reshape/etc.} @@ -59,92 +58,75 @@ tk_canvas(tkp.id) \item{norm}{Logical, should we norm the coordinates.} -\item{coords}{Two-column numeric matrix, the new coordinates of the -vertices, in absolute coordinates.} +\item{coords}{Two-column numeric matrix, the new coordinates of the vertices, in absolute coordinates.} \item{degree}{The degree to rotate the plot.} \item{rad}{The degree to rotate the plot, in radian.} } \value{ -\code{tkplot()} returns an integer, the ID of the plot, this can be -used to manipulate it from the command line. +\code{tkplot()} returns an integer, the ID of the plot, this can be used to manipulate it from the command line. \code{tk_canvas()} returns \code{tkwin} object, the Tk canvas. \code{tk_coords()} returns a matrix with the coordinates. -\code{tk_close()}, \code{tk_off()}, \code{tk_fit()}, -\code{tk_reshape()}, \code{tk_postscript()}, \code{tk_center()} -and \code{tk_rotate()} return \code{NULL} invisibly. +\code{tk_close()}, \code{tk_off()}, \code{tk_fit()}, \code{tk_reshape()}, \code{tk_postscript()}, \code{tk_center()} and \code{tk_rotate()} return \code{NULL} invisibly. } \description{ -\code{tkplot()} and its companion functions serve as an interactive graph -drawing facility. Not all parameters of the plot can be changed -interactively right now though, e.g. the colors of vertices, edges, and also -others have to be pre-defined. +\code{tkplot()} and its companion functions serve as an interactive graph drawing facility. +Not all parameters of the plot can be changed interactively right now though, e.g. the colors of vertices, edges, +and also others have to be pre-defined. } \details{ -\code{tkplot()} is an interactive graph drawing facility. It is not very well -developed at this stage, but it should be still useful. +\code{tkplot()} is an interactive graph drawing facility. +It is not very well developed at this stage, but it should be still useful. -It's handling should be quite straightforward most of the time, here are -some remarks and hints. +It's handling should be quite straightforward most of the time, here are some remarks and hints. -There are different popup menus, activated by the right mouse button, for -vertices and edges. Both operate on the current selection if the vertex/edge -under the cursor is part of the selection and operate on the vertex/edge -under the cursor if it is not. +There are different popup menus, activated by the right mouse button, for vertices and edges. +Both operate on the current selection +if the vertex/edge under the cursor is part of the selection and operate on the vertex/edge under the cursor if it is not. One selection can be active at a time, either a vertex or an edge selection. -A vertex/edge can be added to a selection by holding the \code{control} key -while clicking on it with the left mouse button. Doing this again deselect -the vertex/edge. +A vertex/edge can be added to a selection by holding the \code{control} key while clicking on it with the left mouse button. +Doing this again deselect the vertex/edge. -Selections can be made also from the "Select" menu. The "Select some -vertices" dialog allows to give an expression for the vertices to be -selected: this can be a list of numeric R expessions separated by commas, -like \verb{1,2:10,12,14,15} for example. Similarly in the "Select some -edges" dialog two such lists can be given and all edges connecting a vertex -in the first list to one in the second list will be selected. +Selections can be made also from the "Select" menu. +The "Select some vertices" dialog allows to give an expression for the vertices to be selected: +this can be a list of numeric R expessions separated by commas, like \verb{1,2:10,12,14,15} for example. +Similarly in the "Select some edges" dialog two such lists can be given and all edges connecting a vertex in the first list to one in the second list will be selected. -In the color dialog a color name like 'orange' or RGB notation can also be -used. +In the color dialog a color name like 'orange' or RGB notation can also be used. -The \code{tkplot()} command creates a new Tk window with the graphical -representation of \code{graph}. The command returns an integer number, the -tkplot ID. The other commands utilize this ID to be able to query or -manipulate the plot. +The \code{tkplot()} command creates a new Tk window with the graphical representation of \code{graph}. +The command returns an integer number, the tkplot ID. +The other commands utilize this ID to be able to query or manipulate the plot. \code{tk_close()} closes the Tk plot with ID \code{tkp.id}. \code{tk_off()} closes all Tk plots. -\code{tk_fit()} fits the plot to the given rectangle -(\code{width} and \code{height}), if some of these are \code{NULL} the -actual physical width od height of the plot window is used. +\code{tk_fit()} fits the plot to the given rectangle (\code{width} and \code{height}), +if some of these are \code{NULL} the actual physical width od height of the plot window is used. -\code{tk_reshape()} applies a new layout to the plot, its optional -parameters will be collected to a list analogous to \code{layout.par}. +\code{tk_reshape()} applies a new layout to the plot, its optional parameters will be collected to a list analogous to \code{layout.par}. -\code{tk_postscript()} creates a dialog window for saving the plot -in postscript format. +\code{tk_postscript()} creates a dialog window for saving the plot in postscript format. -\code{tk_canvas()} returns the Tk canvas object that belongs to a graph -plot. The canvas can be directly manipulated then, e.g. labels can be added, -it could be saved to a file programmatically, etc. See an example below. +\code{tk_canvas()} returns the Tk canvas object that belongs to a graph plot. +The canvas can be directly manipulated then, e.g. labels can be added, it could be saved to a file programmatically, +etc. See an example below. \code{tk_coords()} returns the coordinates of the vertices in a matrix. Each row corresponds to one vertex. -\code{tk_set_coords()} sets the coordinates of the vertices. A two-column -matrix specifies the new positions, with each row corresponding to a single -vertex. +\code{tk_set_coords()} sets the coordinates of the vertices. +A two-column matrix specifies the new positions, with each row corresponding to a single vertex. \code{tk_center()} shifts the figure to the center of its plot window. -\code{tk_rotate()} rotates the figure, its parameter can be given either -in degrees or in radians. +\code{tk_rotate()} rotates the figure, its parameter can be given either in degrees or in radians. tkplot.center tkplot.rotate } diff --git a/man/tkplot.canvas.Rd b/man/tkplot.canvas.Rd index 6ee21351d17..47746d770db 100644 --- a/man/tkplot.canvas.Rd +++ b/man/tkplot.canvas.Rd @@ -12,7 +12,6 @@ tkplot.canvas(tkp.id) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{tkplot.canvas()} was renamed to \code{\link[=tk_canvas]{tk_canvas()}} to create a more -consistent API. +\code{tkplot.canvas()} was renamed to \code{\link[=tk_canvas]{tk_canvas()}} to create a more consistent API. } \keyword{internal} diff --git a/man/tkplot.center.Rd b/man/tkplot.center.Rd index 9fe440e3c9b..c8c9d4e0792 100644 --- a/man/tkplot.center.Rd +++ b/man/tkplot.center.Rd @@ -12,8 +12,7 @@ tkplot.center(tkp.id) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{tkplot.center()} was renamed to \code{\link[=tk_center]{tk_center()}} to create a more -consistent API. +\code{tkplot.center()} was renamed to \code{\link[=tk_center]{tk_center()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/tkplot.close.Rd b/man/tkplot.close.Rd index a5d92bbd8e2..9be00b66c45 100644 --- a/man/tkplot.close.Rd +++ b/man/tkplot.close.Rd @@ -14,7 +14,6 @@ tkplot.close(tkp.id, window.close = TRUE) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{tkplot.close()} was renamed to \code{\link[=tk_close]{tk_close()}} to create a more -consistent API. +\code{tkplot.close()} was renamed to \code{\link[=tk_close]{tk_close()}} to create a more consistent API. } \keyword{internal} diff --git a/man/tkplot.export.postscript.Rd b/man/tkplot.export.postscript.Rd index 36da79e6d99..13f65d47363 100644 --- a/man/tkplot.export.postscript.Rd +++ b/man/tkplot.export.postscript.Rd @@ -12,7 +12,6 @@ tkplot.export.postscript(tkp.id) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{tkplot.export.postscript()} was renamed to \code{\link[=tk_postscript]{tk_postscript()}} to create a more -consistent API. +\code{tkplot.export.postscript()} was renamed to \code{\link[=tk_postscript]{tk_postscript()}} to create a more consistent API. } \keyword{internal} diff --git a/man/tkplot.fit.to.screen.Rd b/man/tkplot.fit.to.screen.Rd index 6c9f51f648c..362d70c9bc6 100644 --- a/man/tkplot.fit.to.screen.Rd +++ b/man/tkplot.fit.to.screen.Rd @@ -16,8 +16,7 @@ tkplot.fit.to.screen(tkp.id, width = NULL, height = NULL) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{tkplot.fit.to.screen()} was renamed to \code{\link[=tk_fit]{tk_fit()}} to create a more -consistent API. +\code{tkplot.fit.to.screen()} was renamed to \code{\link[=tk_fit]{tk_fit()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/tkplot.getcoords.Rd b/man/tkplot.getcoords.Rd index e764d774690..17b84e26a35 100644 --- a/man/tkplot.getcoords.Rd +++ b/man/tkplot.getcoords.Rd @@ -14,7 +14,6 @@ tkplot.getcoords(tkp.id, norm = FALSE) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{tkplot.getcoords()} was renamed to \code{\link[=tk_coords]{tk_coords()}} to create a more -consistent API. +\code{tkplot.getcoords()} was renamed to \code{\link[=tk_coords]{tk_coords()}} to create a more consistent API. } \keyword{internal} diff --git a/man/tkplot.off.Rd b/man/tkplot.off.Rd index edfe4b355cc..ea50d5c905a 100644 --- a/man/tkplot.off.Rd +++ b/man/tkplot.off.Rd @@ -9,7 +9,6 @@ tkplot.off() \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{tkplot.off()} was renamed to \code{\link[=tk_off]{tk_off()}} to create a more -consistent API. +\code{tkplot.off()} was renamed to \code{\link[=tk_off]{tk_off()}} to create a more consistent API. } \keyword{internal} diff --git a/man/tkplot.reshape.Rd b/man/tkplot.reshape.Rd index 564dd470eb2..162e1e3bcc6 100644 --- a/man/tkplot.reshape.Rd +++ b/man/tkplot.reshape.Rd @@ -11,17 +11,15 @@ tkplot.reshape(tkp.id, newlayout, ..., params) \item{newlayout}{The new layout, see the \code{layout} parameter of tkplot.} -\item{...}{For \code{tkplot()}, additional plotting parameters, see -\link{igraph.plotting} for the complete list. For \code{tk_close()}, \code{tk_fit()}, -\code{tk_coords()} and \code{tk_rotate()}, these dots must be empty.} +\item{...}{For \code{tkplot()}, additional plotting parameters, see \link{igraph.plotting} for the complete list. +For \code{tk_close()}, \code{tk_fit()}, \code{tk_coords()} and \code{tk_rotate()}, these dots must be empty.} \item{params}{Extra parameters in a list, to pass to the layout function.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{tkplot.reshape()} was renamed to \code{\link[=tk_reshape]{tk_reshape()}} to create a more -consistent API. +\code{tkplot.reshape()} was renamed to \code{\link[=tk_reshape]{tk_reshape()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/tkplot.rotate.Rd b/man/tkplot.rotate.Rd index ef92c9b4af1..fb767757912 100644 --- a/man/tkplot.rotate.Rd +++ b/man/tkplot.rotate.Rd @@ -16,8 +16,7 @@ tkplot.rotate(tkp.id, degree = NULL, rad = NULL) \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{tkplot.rotate()} was renamed to \code{\link[=tk_rotate]{tk_rotate()}} to create a more -consistent API. +\code{tkplot.rotate()} was renamed to \code{\link[=tk_rotate]{tk_rotate()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/tkplot.setcoords.Rd b/man/tkplot.setcoords.Rd index 00209725b48..945c9ee08c2 100644 --- a/man/tkplot.setcoords.Rd +++ b/man/tkplot.setcoords.Rd @@ -9,14 +9,12 @@ tkplot.setcoords(tkp.id, coords) \arguments{ \item{tkp.id}{The ID of the tkplot window to close/reshape/etc.} -\item{coords}{Two-column numeric matrix, the new coordinates of the -vertices, in absolute coordinates.} +\item{coords}{Two-column numeric matrix, the new coordinates of the vertices, in absolute coordinates.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{tkplot.setcoords()} was renamed to \code{\link[=tk_set_coords]{tk_set_coords()}} to create a more -consistent API. +\code{tkplot.setcoords()} was renamed to \code{\link[=tk_set_coords]{tk_set_coords()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/to_prufer.Rd b/man/to_prufer.Rd index dda6a1e6f37..f019acc2e46 100644 --- a/man/to_prufer.Rd +++ b/man/to_prufer.Rd @@ -10,18 +10,16 @@ to_prufer(graph) \item{graph}{The graph to convert to a Prüfer sequence} } \value{ -The Prüfer sequence of the graph, represented as a numeric vector of -vertex IDs in the sequence. +The Prüfer sequence of the graph, represented as a numeric vector of vertex IDs in the sequence. } \description{ \code{to_prufer()} converts a tree graph into its Prüfer sequence. } \details{ -The Prüfer sequence of a tree graph with n labeled vertices is a sequence of -n-2 numbers, constructed as follows. If the graph has more than two vertices, -find a vertex with degree one, remove it from the tree and add the label of -the vertex that it was connected to to the sequence. Repeat until there are -only two vertices in the remaining graph. +The Prüfer sequence of a tree graph with n labeled vertices is a sequence of n-2 numbers, constructed as follows. +If the graph has more than two vertices, find a vertex with degree one, +remove it from the tree and add the label of the vertex that it was connected to to the sequence. +Repeat until there are only two vertices in the remaining graph. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_to_prufer}{\code{to_prufer()}} @@ -34,8 +32,7 @@ to_prufer(g) } \seealso{ -\code{\link[=make_from_prufer]{make_from_prufer()}} to construct a graph from its -Prüfer sequence +\code{\link[=make_from_prufer]{make_from_prufer()}} to construct a graph from its Prüfer sequence Other trees: \code{\link[=is_forest]{is_forest()}}, diff --git a/man/topo_sort.Rd b/man/topo_sort.Rd index 99086fc5197..1ad3f903b73 100644 --- a/man/topo_sort.Rd +++ b/man/topo_sort.Rd @@ -11,26 +11,23 @@ topo_sort(graph, ..., mode = c("out", "all", "in")) \item{...}{These dots are for future extensions and must be empty.} -\item{mode}{Specifies how to use the direction of the edges. For -\dQuote{\code{out}}, the sorting order ensures that each node comes before -all nodes to which it has edges, so nodes with no incoming edges go first. -For \dQuote{\verb{in}}, it is quite the opposite: each node comes before all -nodes from which it receives edges. Nodes with no outgoing edges go first.} +\item{mode}{Specifies how to use the direction of the edges. +For \dQuote{\code{out}}, +the sorting order ensures that each node comes before all nodes to which it has edges, so nodes with no incoming edges go first. +For \dQuote{\verb{in}}, it is quite the opposite: each node comes before all nodes from which it receives edges. +Nodes with no outgoing edges go first.} } \value{ -A vertex sequence (by default, but see the \code{return.vs.es} -option of \code{\link[=igraph_options]{igraph_options()}}) containing vertices in -topologically sorted order. +A vertex sequence (by default, but see the \code{return.vs.es} option of \code{\link[=igraph_options]{igraph_options()}}) containing vertices in topologically sorted order. } \description{ -A topological sorting of a directed acyclic graph is a linear ordering of -its nodes where each node comes before all nodes to which it has edges. +A topological sorting of a directed acyclic graph is a linear ordering of its nodes +where each node comes before all nodes to which it has edges. } \details{ -Every DAG has at least one topological sort, and may have many. This -function returns a possible topological sort among them. If the graph is not -acyclic (it has at least one cycle), a partial topological sort is returned -and a warning is issued. +Every DAG has at least one topological sort, and may have many. +This function returns a possible topological sort among them. +If the graph is not acyclic (it has at least one cycle), a partial topological sort is returned and a warning is issued. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_topological_sorting}{\code{topological_sorting()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/topological.sort.Rd b/man/topological.sort.Rd index bcf2cdbe477..b6bbdb084f0 100644 --- a/man/topological.sort.Rd +++ b/man/topological.sort.Rd @@ -9,17 +9,16 @@ topological.sort(graph, mode = c("out", "all", "in")) \arguments{ \item{graph}{The input graph, should be directed} -\item{mode}{Specifies how to use the direction of the edges. For -\dQuote{\code{out}}, the sorting order ensures that each node comes before -all nodes to which it has edges, so nodes with no incoming edges go first. -For \dQuote{\verb{in}}, it is quite the opposite: each node comes before all -nodes from which it receives edges. Nodes with no outgoing edges go first.} +\item{mode}{Specifies how to use the direction of the edges. +For \dQuote{\code{out}}, +the sorting order ensures that each node comes before all nodes to which it has edges, so nodes with no incoming edges go first. +For \dQuote{\verb{in}}, it is quite the opposite: each node comes before all nodes from which it receives edges. +Nodes with no outgoing edges go first.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{topological.sort()} was renamed to \code{\link[=topo_sort]{topo_sort()}} to create a more -consistent API. +\code{topological.sort()} was renamed to \code{\link[=topo_sort]{topo_sort()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_topological_sorting}{\code{topological_sorting()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/transitive_closure.Rd b/man/transitive_closure.Rd index ed0978c75f4..088d6756100 100644 --- a/man/transitive_closure.Rd +++ b/man/transitive_closure.Rd @@ -18,16 +18,12 @@ The returned graph will have the same directedness as the input. \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} Computes the transitive closure of a graph. -The resulting graph will have an edge from vertex \eqn{i} to vertex \eqn{j} -if \eqn{j} is reachable from \eqn{i} in the original graph. +The resulting graph will have an edge from vertex \eqn{i} to vertex \eqn{j} if \eqn{j} is reachable from \eqn{i} in the original graph. -The transitive closure of a graph is a new graph where there is an edge -between any two vertices if there is a path between them in the original -graph. -For directed graphs, an edge from \eqn{i} to \eqn{j} is added if there is -a directed path from \eqn{i} to \eqn{j}. -For undirected graphs, this is equivalent to connecting all vertices that -are in the same connected component. +The transitive closure of a graph is a new graph where there is an edge between any two vertices +if there is a path between them in the original graph. +For directed graphs, an edge from \eqn{i} to \eqn{j} is added if there is a directed path from \eqn{i} to \eqn{j}. +For undirected graphs, this is equivalent to connecting all vertices that are in the same connected component. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_transitive_closure}{\code{transitive_closure()}} diff --git a/man/transitivity.Rd b/man/transitivity.Rd index e40240a408c..4d338b69dc8 100644 --- a/man/transitivity.Rd +++ b/man/transitivity.Rd @@ -17,7 +17,8 @@ transitivity( \arguments{ \item{graph}{The graph to analyze.} -\item{type}{The type of the transitivity to calculate. Possible values: +\item{type}{The type of the transitivity to calculate. +Possible values: \describe{ \item{"global"}{ The global transitivity of an undirected graph. @@ -51,59 +52,47 @@ The same as \code{barrat}. \item{...}{These dots are for future extensions and must be empty.} \item{vids}{The vertex IDs for the local transitivity will be calculated. -This will be ignored for global transitivity types. The default value is -\code{NULL}, in this case all vertices are considered. It is slightly faster -to supply \code{NULL} here than \code{V(graph)}.} - -\item{weights}{Optional weights for weighted transitivity. It is ignored for -other transitivity measures. If it is \code{NULL} (the default) and the -graph has a \code{weight} edge attribute, then it is used automatically.} - -\item{isolates}{Character scalar, for local versions of transitivity, it -defines how to treat vertices with degree zero and one. -If it is \sQuote{\code{NaN}} then their local transitivity is -reported as \code{NaN} and they are not included in the averaging, for the -transitivity types that calculate an average. If there are no vertices with -degree two or higher, then the averaging will still result \code{NaN}. If it -is \sQuote{\code{zero}}, then we report 0 transitivity for them, and they -are included in the averaging, if an average is calculated. -For the global transitivity, it controls how to handle graphs with -no connected triplets: \code{NaN} or zero will be returned according to -the respective setting.} +This will be ignored for global transitivity types. +The default value is \code{NULL}, in this case all vertices are considered. +It is slightly faster to supply \code{NULL} here than \code{V(graph)}.} + +\item{weights}{Optional weights for weighted transitivity. +It is ignored for other transitivity measures. +If it is \code{NULL} (the default) and the graph has a \code{weight} edge attribute, then it is used automatically.} + +\item{isolates}{Character scalar, for local versions of transitivity, it defines how to treat vertices with degree zero and one. +If it is \sQuote{\code{NaN}} then their local transitivity is reported as \code{NaN} and they are not included in the averaging, +for the transitivity types that calculate an average. +If there are no vertices with degree two or higher, then the averaging will still result \code{NaN}. +If it is \sQuote{\code{zero}}, then we report 0 transitivity for them, and they are included in the averaging, if an average is calculated. +For the global transitivity, it controls how to handle graphs with no connected triplets: +\code{NaN} or zero will be returned according to the respective setting.} } \value{ -For \sQuote{\code{global}} a single number, or \code{NaN} if there -are no connected triples in the graph. +For \sQuote{\code{global}} a single number, or \code{NaN} if there are no connected triples in the graph. -For \sQuote{\code{local}} a vector of transitivity scores, one for each -vertex in \sQuote{\code{vids}}. +For \sQuote{\code{local}} a vector of transitivity scores, one for each vertex in \sQuote{\code{vids}}. } \description{ -Transitivity measures the probability that the adjacent vertices of a vertex -are connected. This is sometimes also called the clustering coefficient. +Transitivity measures the probability that the adjacent vertices of a vertex are connected. +This is sometimes also called the clustering coefficient. } \details{ -Note that there are essentially two classes of transitivity measures, one is -a vertex-level, the other a graph level property. +Note that there are essentially two classes of transitivity measures, one is a vertex-level, the other a graph level property. -There are several generalizations of transitivity to weighted graphs, here -we use the definition by A. Barrat, this is a local vertex-level quantity, -its formula is +There are several generalizations of transitivity to weighted graphs, here we use the definition by A. Barrat, +this is a local vertex-level quantity, its formula is \deqn{C_i^w=\frac{1}{s_i(k_i-1)}\sum_{j,h}\frac{w_{ij}+w_{ih}}{2}a_{ij}a_{ih}a_{jh}}{ weighted C_i = 1/s_i 1/(k_i-1) sum( (w_ij+w_ih)/2 a_ij a_ih a_jh, j, h)} -\eqn{s_i}{s_i} is the strength of vertex \eqn{i}{i}, see -\code{\link[=strength]{strength()}}, \eqn{a_{ij}}{a_ij} are elements of the -adjacency matrix, \eqn{k_i}{k_i} is the vertex degree, \eqn{w_{ij}}{w_ij} -are the weights. +\eqn{s_i}{s_i} is the strength of vertex \eqn{i}{i}, see \code{\link[=strength]{strength()}}, \eqn{a_{ij}}{a_ij} are elements of the adjacency matrix, +\eqn{k_i}{k_i} is the vertex degree, \eqn{w_{ij}}{w_ij} are the weights. -This formula gives back the normal not-weighted local transitivity if all -the edge weights are the same. +This formula gives back the normal not-weighted local transitivity if all the edge weights are the same. -The \code{barrat} type of transitivity does not work for graphs with -multiple and/or loop edges. If you want to calculate it for a directed -graph, call \code{\link[=as_undirected]{as_undirected()}} with the \code{collapse} mode first. +The \code{barrat} type of transitivity does not work for graphs with multiple and/or loop edges. +If you want to calculate it for a directed graph, call \code{\link[=as_undirected]{as_undirected()}} with the \code{collapse} mode first. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_transitivity_avglocal_undirected}{\code{transitivity_avglocal_undirected()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_transitivity_barrat}{\code{transitivity_barrat()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_transitivity_local_undirected}{\code{transitivity_local_undirected()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_transitivity_undirected}{\code{transitivity_undirected()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/triad.census.Rd b/man/triad.census.Rd index 9f2b4568f7d..a3513dd6d5a 100644 --- a/man/triad.census.Rd +++ b/man/triad.census.Rd @@ -7,14 +7,13 @@ triad.census(graph) } \arguments{ -\item{graph}{The input graph, it should be directed. An undirected graph -results a warning, and undefined results.} +\item{graph}{The input graph, it should be directed. +An undirected graph results a warning, and undefined results.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{triad.census()} was renamed to \code{\link[=triad_census]{triad_census()}} to create a more -consistent API. +\code{triad.census()} was renamed to \code{\link[=triad_census]{triad_census()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Motifs.html#igraph_triad_census}{\code{triad_census()}} diff --git a/man/triad_census.Rd b/man/triad_census.Rd index c5a87dbcf76..e6dc7923eee 100644 --- a/man/triad_census.Rd +++ b/man/triad_census.Rd @@ -7,21 +7,18 @@ triad_census(graph) } \arguments{ -\item{graph}{The input graph, it should be directed. An undirected graph -results a warning, and undefined results.} +\item{graph}{The input graph, it should be directed. +An undirected graph results a warning, and undefined results.} } \value{ -A numeric vector, the subgraph counts, in the order given in the -above description. +A numeric vector, the subgraph counts, in the order given in the above description. } \description{ -This function counts the different induced subgraphs of three vertices in -a graph. +This function counts the different induced subgraphs of three vertices in a graph. } \details{ Triad census was defined by David and Leinhardt (see References below). -Every triple of vertices (A, B, C) are classified into the 16 possible -states: +Every triple of vertices (A, B, C) are classified into the 16 possible states: \describe{ \item{003}{ A,B,C, the empty graph. @@ -73,8 +70,7 @@ A<->B<->C, A<->C, the complete graph. } } -This functions uses the RANDESU motif finder algorithm to find and count the -subgraphs, see \code{\link[=motifs]{motifs()}}. +This functions uses the RANDESU motif finder algorithm to find and count the subgraphs, see \code{\link[=motifs]{motifs()}}. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Motifs.html#igraph_triad_census}{\code{triad_census()}} diff --git a/man/unfold.tree.Rd b/man/unfold.tree.Rd index 98cbf56a6eb..b888fe76d0f 100644 --- a/man/unfold.tree.Rd +++ b/man/unfold.tree.Rd @@ -9,19 +9,17 @@ unfold.tree(graph, mode = c("all", "out", "in", "total"), roots) \arguments{ \item{graph}{The input graph, it can be either directed or undirected.} -\item{mode}{Character string, defined the types of the paths used for the -breadth-first search. \dQuote{out} follows the outgoing, \dQuote{in} the -incoming edges, \dQuote{all} and \dQuote{total} both of them. This argument -is ignored for undirected graphs.} +\item{mode}{Character string, defined the types of the paths used for the breadth-first search. +\dQuote{out} follows the outgoing, \dQuote{in} the incoming edges, \dQuote{all} and \dQuote{total} both of them. +This argument is ignored for undirected graphs.} -\item{roots}{A vector giving the vertices from which the breadth-first -search is performed. Typically it contains one vertex per component.} +\item{roots}{A vector giving the vertices from which the breadth-first search is performed. +Typically it contains one vertex per component.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{unfold.tree()} was renamed to \code{\link[=unfold_tree]{unfold_tree()}} to create a more -consistent API. +\code{unfold.tree()} was renamed to \code{\link[=unfold_tree]{unfold_tree()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_unfold_tree}{\code{unfold_tree()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/unfold_tree.Rd b/man/unfold_tree.Rd index 31ed269582a..5daa6c7aeb2 100644 --- a/man/unfold_tree.Rd +++ b/man/unfold_tree.Rd @@ -11,13 +11,12 @@ unfold_tree(graph, ..., mode = c("all", "out", "in", "total"), roots) \item{...}{These dots are for future extensions and must be empty.} -\item{mode}{Character string, defined the types of the paths used for the -breadth-first search. \dQuote{out} follows the outgoing, \dQuote{in} the -incoming edges, \dQuote{all} and \dQuote{total} both of them. This argument -is ignored for undirected graphs.} +\item{mode}{Character string, defined the types of the paths used for the breadth-first search. +\dQuote{out} follows the outgoing, \dQuote{in} the incoming edges, \dQuote{all} and \dQuote{total} both of them. +This argument is ignored for undirected graphs.} -\item{roots}{A vector giving the vertices from which the breadth-first -search is performed. Typically it contains one vertex per component.} +\item{roots}{A vector giving the vertices from which the breadth-first search is performed. +Typically it contains one vertex per component.} } \value{ A list with two components: @@ -31,14 +30,12 @@ A numeric vector, it gives a mapping from the vertices of the new graph to the v } } \description{ -Perform a breadth-first search on a graph and convert it into a tree or -forest by replicating vertices that were found more than once. +Perform a breadth-first search on a graph and convert it into a tree or forest by replicating vertices that were found more than once. } \details{ A forest is a graph, whose components are trees. -The \code{roots} vector can be calculated by simply doing a topological sort -in all components of the graph, see the examples below. +The \code{roots} vector can be calculated by simply doing a topological sort in all components of the graph, see the examples below. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_unfold_tree}{\code{unfold_tree()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/union.Rd b/man/union.Rd index 4f68ad5d9c0..d0b6e81365a 100644 --- a/man/union.Rd +++ b/man/union.Rd @@ -7,19 +7,16 @@ union(...) } \arguments{ -\item{...}{Arguments, their number and interpretation depends on -the function that implements \code{union()}.} +\item{...}{Arguments, their number and interpretation depends on the function that implements \code{union()}.} } \value{ Depends on the function that implements this method. } \description{ -This is an S3 generic function. See \code{methods("union")} -for the actual implementations for various S3 classes. Initially -it is implemented for igraph graphs and igraph vertex and edge -sequences. See -\code{\link[=union.igraph]{union.igraph()}}, and -\code{\link[=union.igraph.vs]{union.igraph.vs()}}. +This is an S3 generic function. +See \code{methods("union")} for the actual implementations for various S3 classes. +Initially it is implemented for igraph graphs and igraph vertex and edge sequences. +See \code{\link[=union.igraph]{union.igraph()}}, and \code{\link[=union.igraph.vs]{union.igraph.vs()}}. } \seealso{ Other functions for manipulating graph structure: diff --git a/man/union.igraph.Rd b/man/union.igraph.Rd index f75202bc1d8..7bcb4641cd3 100644 --- a/man/union.igraph.Rd +++ b/man/union.igraph.Rd @@ -16,50 +16,43 @@ \arguments{ \item{\dots}{Graph objects or lists of graph objects.} -\item{byname}{A Logical, or the character scalar \code{auto}. Whether -to perform the operation based on symbolic vertex names. If it is -\code{auto}, that means \code{TRUE} if all graphs are named and \code{FALSE} -otherwise. A warning is generated if \code{auto} and some (but not all) -graphs are named.} +\item{byname}{A Logical, or the character scalar \code{auto}. +Whether to perform the operation based on symbolic vertex names. +If it is \code{auto}, that means \code{TRUE} if all graphs are named and \code{FALSE} 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 -\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.} +\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 \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.} } \value{ A new graph object. } \description{ -The union of two or more graphs are created. The graphs may have identical -or overlapping vertex sets. +The union of two or more graphs are created. +The graphs may have identical or overlapping vertex sets. } \details{ -\code{union()} creates the union of two or more graphs. Edges which are -included in at least one graph will be part of the new graph. This function -can be also used via the \verb{\%u\%} operator. +\code{union()} creates the union of two or more graphs. +Edges which are included in at least one graph will be part of the new graph. +This function can be also used via the \verb{\%u\%} operator. -If the \code{byname} argument is \code{TRUE} (or \code{auto} and all graphs -are named), then the operation is performed on symbolic vertex names instead -of the internal numeric vertex IDs. +If the \code{byname} argument is \code{TRUE} (or \code{auto} and all graphs are named), +then the operation is performed on symbolic vertex names instead 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 -instead, e.g. by summing or by taking the first non-\code{NA} value. See -\link{igraph-attribute-combination} for the available combiners. +\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 instead, +e.g. by summing or by taking the first non-\code{NA} value. +See \link{igraph-attribute-combination} for the available combiners. -The \code{name} vertex attribute is treated specially if the operation is -performed based on symbolic vertex names. In this case \code{name} must be -present in all graphs, and it is not renamed in the result graph. +The \code{name} vertex attribute is treated specially if the operation is performed based on symbolic vertex names. +In this case \code{name} must be present in all graphs, and it is not renamed in the result graph. -An error is generated if some input graphs are directed and others are -undirected. +An error is generated if some input graphs are directed and others are undirected. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Isomorphism.html#igraph_permute_vertices}{\code{permute_vertices()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/union.igraph.es.Rd b/man/union.igraph.es.Rd index 0a93e7cbfe8..1f4234223d9 100644 --- a/man/union.igraph.es.Rd +++ b/man/union.igraph.es.Rd @@ -10,17 +10,15 @@ \item{...}{The edge sequences to take the union of.} } \value{ -An edge sequence that contains all edges in the given -sequences, exactly once. +An edge sequence that contains all edges in the given sequences, exactly once. } \description{ Union of edge sequences } \details{ -They must belong to the same graph. Note that this function has -\sQuote{set} semantics and the multiplicity of edges is lost in the -result. (This is to match the behavior of the based \code{unique} -function.) +They must belong to the same graph. +Note that this function has \sQuote{set} semantics and the multiplicity of edges is lost in the result. +(This is to match the behavior of the based \code{unique} function.) } \examples{ g <- make_(ring(10), with_vertex_(name = LETTERS[1:10])) diff --git a/man/union.igraph.vs.Rd b/man/union.igraph.vs.Rd index 4d06d337e3b..f45c1190701 100644 --- a/man/union.igraph.vs.Rd +++ b/man/union.igraph.vs.Rd @@ -10,17 +10,15 @@ \item{...}{The vertex sequences to take the union of.} } \value{ -A vertex sequence that contains all vertices in the given -sequences, exactly once. +A vertex sequence that contains all vertices in the given sequences, exactly once. } \description{ Union of vertex sequences } \details{ -They must belong to the same graph. Note that this function has -\sQuote{set} semantics and the multiplicity of vertices is lost in the -result. (This is to match the behavior of the based \code{unique} -function.) +They must belong to the same graph. +Note that this function has \sQuote{set} semantics and the multiplicity of vertices is lost in the result. +(This is to match the behavior of the based \code{unique} function.) } \examples{ g <- make_(ring(10), with_vertex_(name = LETTERS[1:10])) diff --git a/man/unique.igraph.es.Rd b/man/unique.igraph.es.Rd index dcbe287fa8b..9b7623cbc62 100644 --- a/man/unique.igraph.es.Rd +++ b/man/unique.igraph.es.Rd @@ -10,7 +10,8 @@ \item{x}{An edge sequence.} \item{incomparables}{a vector of values that cannot be compared. -Passed to base function \code{duplicated}. See details there.} +Passed to base function \code{duplicated}. +See details there.} \item{...}{Passed to base function \code{duplicated()}.} } diff --git a/man/unique.igraph.vs.Rd b/man/unique.igraph.vs.Rd index 86b096745c4..e404d94f6ca 100644 --- a/man/unique.igraph.vs.Rd +++ b/man/unique.igraph.vs.Rd @@ -10,7 +10,8 @@ \item{x}{A vertex sequence.} \item{incomparables}{a vector of values that cannot be compared. -Passed to base function \code{duplicated}. See details there.} +Passed to base function \code{duplicated}. +See details there.} \item{...}{Passed to base function \code{duplicated()}.} } diff --git a/man/upgrade_graph.Rd b/man/upgrade_graph.Rd index 3d6c45a4078..3a67456d600 100644 --- a/man/upgrade_graph.Rd +++ b/man/upgrade_graph.Rd @@ -13,25 +13,21 @@ upgrade_graph(graph) The graph in the current format. } \description{ -igraph's internal data representation changes sometimes between -versions. This means that it is not possible to use igraph objects -that were created (and possibly saved to a file) with an older -igraph version. +igraph's internal data representation changes sometimes between versions. +This means that it is not possible to use igraph objects that were created (and possibly saved to a file) with an older igraph version. } \details{ \code{\link[=graph_version]{graph_version()}} queries the current data format, or the data format of a possibly older igraph graph. -\code{upgrade_graph()} can convert an older data format -to the current one. +\code{upgrade_graph()} can convert an older data format to the current one. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} } \seealso{ -graph_version to check the current data format version -or the version of a graph. +graph_version to check the current data format version or the version of a graph. Other versions: \code{\link[=graph_version]{graph_version()}} diff --git a/man/vertex.Rd b/man/vertex.Rd index 75407eadee0..1375b1e6217 100644 --- a/man/vertex.Rd +++ b/man/vertex.Rd @@ -13,23 +13,19 @@ vertices(...) \item{...}{See details below.} } \value{ -A special object that can be used with together with -igraph graphs and the plus and minus operators. +A special object that can be used with together with igraph graphs and the plus and minus operators. } \description{ -This is a helper function that simplifies adding and deleting -vertices to/from graphs. +This is a helper function that simplifies adding and deleting vertices to/from graphs. } \details{ \code{vertices()} is an alias for \code{vertex()}. -When adding vertices via \code{+}, all unnamed arguments are interpreted -as vertex names of the new vertices. Named arguments are interpreted as -vertex attributes for the new vertices. +When adding vertices via \code{+}, all unnamed arguments are interpreted as vertex names of the new vertices. +Named arguments are interpreted as vertex attributes for the new vertices. -When deleting vertices via \code{-}, all arguments of \code{vertex()} (or -\code{vertices()}) are concatenated via \code{c()} and passed to -\code{\link[=delete_vertices]{delete_vertices()}}. +When deleting vertices via \code{-}, +all arguments of \code{vertex()} (or \code{vertices()}) are concatenated via \code{c()} and passed to \code{\link[=delete_vertices]{delete_vertices()}}. } \examples{ g <- make_(ring(10), with_vertex_(name = LETTERS[1:10])) + diff --git a/man/vertex.connectivity.Rd b/man/vertex.connectivity.Rd index 1f0d02c964b..5d23ee3bc4e 100644 --- a/man/vertex.connectivity.Rd +++ b/man/vertex.connectivity.Rd @@ -7,25 +7,21 @@ vertex.connectivity(graph, source = NULL, target = NULL, checks = TRUE) } \arguments{ -\item{source}{The ID of the source vertex, for \code{vertex_connectivity()} it -can be \code{NULL}, see details below.} +\item{source}{The ID of the source vertex, for \code{vertex_connectivity()} it can be \code{NULL}, see details below.} -\item{target}{The ID of the target vertex, for \code{vertex_connectivity()} it -can be \code{NULL}, see details below.} +\item{target}{The ID of the target vertex, for \code{vertex_connectivity()} it can be \code{NULL}, see details below.} -\item{checks}{Logical. Whether to check that the graph is connected -and also the degree of the vertices. If the graph is not (strongly) -connected then the connectivity is obviously zero. Otherwise if the minimum -degree is one then the vertex connectivity is also one. It is a good idea to -perform these checks, as they can be done quickly compared to the -connectivity calculation itself. They were suggested by Peter McMahan, -thanks Peter.} +\item{checks}{Logical. +Whether to check that the graph is connected and also the degree of the vertices. +If the graph is not (strongly) connected then the connectivity is obviously zero. +Otherwise if the minimum degree is one then the vertex connectivity is also one. +It is a good idea to perform these checks, as they can be done quickly compared to the connectivity calculation itself. +They were suggested by Peter McMahan, thanks Peter.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{vertex.connectivity()} was renamed to \code{\link[=vertex_connectivity]{vertex_connectivity()}} to create a more -consistent API. +\code{vertex.connectivity()} was renamed to \code{\link[=vertex_connectivity]{vertex_connectivity()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Flows.html#igraph_st_vertex_connectivity}{\code{st_vertex_connectivity()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Flows.html#igraph_vertex_connectivity}{\code{vertex_connectivity()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/vertex.disjoint.paths.Rd b/man/vertex.disjoint.paths.Rd index 10c65429b87..16e2f605f4a 100644 --- a/man/vertex.disjoint.paths.Rd +++ b/man/vertex.disjoint.paths.Rd @@ -7,17 +7,14 @@ vertex.disjoint.paths(graph, source = NULL, target = NULL) } \arguments{ -\item{source}{The ID of the source vertex, for \code{vertex_connectivity()} it -can be \code{NULL}, see details below.} +\item{source}{The ID of the source vertex, for \code{vertex_connectivity()} it can be \code{NULL}, see details below.} -\item{target}{The ID of the target vertex, for \code{vertex_connectivity()} it -can be \code{NULL}, see details below.} +\item{target}{The ID of the target vertex, for \code{vertex_connectivity()} it can be \code{NULL}, see details below.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{vertex.disjoint.paths()} was renamed to \code{\link[=vertex_disjoint_paths]{vertex_disjoint_paths()}} to create a more -consistent API. +\code{vertex.disjoint.paths()} was renamed to \code{\link[=vertex_disjoint_paths]{vertex_disjoint_paths()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Flows.html#igraph_vertex_disjoint_paths}{\code{vertex_disjoint_paths()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}} diff --git a/man/vertex.shape.pie.Rd b/man/vertex.shape.pie.Rd index 915e9f3d448..9dc5b0ac431 100644 --- a/man/vertex.shape.pie.Rd +++ b/man/vertex.shape.pie.Rd @@ -4,14 +4,12 @@ \alias{vertex.shape.pie} \title{Using pie charts as vertices in graph plots} \description{ -More complex vertex images can be used to express addtional information -about vertices. E.g. pie charts can be used as vertices, to denote vertex -classes, fuzzy classification of vertices, etc. +More complex vertex images can be used to express addtional information about vertices. +E.g. pie charts can be used as vertices, to denote vertex classes, fuzzy classification of vertices, etc. } \details{ -The vertex shape \sQuote{pie} makes igraph draw a pie chart for every -vertex. There are some extra graphical vertex parameters that specify how -the pie charts will look like: +The vertex shape \sQuote{pie} makes igraph draw a pie chart for every vertex. +There are some extra graphical vertex parameters that specify how the pie charts will look like: \describe{ \item{pie}{ Numeric vector, gives the sizes of the pie slices. diff --git a/man/vertex.shapes.Rd b/man/vertex.shapes.Rd index 054c1b577f2..c3474628d25 100644 --- a/man/vertex.shapes.Rd +++ b/man/vertex.shapes.Rd @@ -7,14 +7,12 @@ vertex.shapes(shape = NULL) } \arguments{ -\item{shape}{Character scalar, name of a vertex shape. If it is -\code{NULL} for \code{shapes()}, then the names of all defined -vertex shapes are returned.} +\item{shape}{Character scalar, name of a vertex shape. +If it is \code{NULL} for \code{shapes()}, then the names of all defined vertex shapes are returned.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{vertex.shapes()} was renamed to \code{\link[=shapes]{shapes()}} to create a more -consistent API. +\code{vertex.shapes()} was renamed to \code{\link[=shapes]{shapes()}} to create a more consistent API. } \keyword{internal} diff --git a/man/vertex_attr-set.Rd b/man/vertex_attr-set.Rd index 817c5abfe5c..275bf3e7d08 100644 --- a/man/vertex_attr-set.Rd +++ b/man/vertex_attr-set.Rd @@ -10,15 +10,13 @@ vertex_attr(graph, name, index = NULL) <- value \arguments{ \item{graph}{The graph.} -\item{name}{The name of the vertex attribute to set. If missing, -then \code{value} must be a named list, and its entries are -set as vertex attributes.} +\item{name}{The name of the vertex attribute to set. +If missing, then \code{value} must be a named list, and its entries are set as vertex attributes.} -\item{index}{An optional vertex sequence to set the attributes -of a subset of vertices. The default \code{NULL} selects all vertices.} +\item{index}{An optional vertex sequence to set the attributes of a subset of vertices. +The default \code{NULL} selects all vertices.} -\item{value}{The new value of the attribute(s) for all -(or \code{index}) vertices.} +\item{value}{The new value of the attribute(s) for all (or \code{index}) vertices.} } \value{ The graph, with the vertex attribute(s) added or set. diff --git a/man/vertex_attr.Rd b/man/vertex_attr.Rd index 5a864092fef..6c2ed468304 100644 --- a/man/vertex_attr.Rd +++ b/man/vertex_attr.Rd @@ -10,15 +10,14 @@ vertex_attr(graph, name, index = NULL) \arguments{ \item{graph}{The graph.} -\item{name}{Name of the attribute to query. If missing, then -all vertex attributes are returned in a list.} +\item{name}{Name of the attribute to query. +If missing, then all vertex attributes are returned in a list.} -\item{index}{An optional vertex sequence to query the attribute only -for these vertices. The default \code{NULL} selects all vertices.} +\item{index}{An optional vertex sequence to query the attribute only for these vertices. +The default \code{NULL} selects all vertices.} } \value{ -The value of the vertex attribute, or the list of -all vertex attributes, if \code{name} is missing. +The value of the vertex attribute, or the list of all vertex attributes, if \code{name} is missing. } \description{ Query vertex attributes of a graph diff --git a/man/vertex_connectivity.Rd b/man/vertex_connectivity.Rd index 08451ddbf76..c6a45602846 100644 --- a/man/vertex_connectivity.Rd +++ b/man/vertex_connectivity.Rd @@ -16,65 +16,47 @@ vertex_disjoint_paths(graph, source = NULL, target = NULL) \arguments{ \item{graph, x}{The input graph.} -\item{source}{The ID of the source vertex, for \code{vertex_connectivity()} it -can be \code{NULL}, see details below.} +\item{source}{The ID of the source vertex, for \code{vertex_connectivity()} it can be \code{NULL}, see details below.} -\item{target}{The ID of the target vertex, for \code{vertex_connectivity()} it -can be \code{NULL}, see details below.} +\item{target}{The ID of the target vertex, for \code{vertex_connectivity()} it can be \code{NULL}, see details below.} -\item{\dots}{For \code{vertex_connectivity()}, these dots must be empty. For -\code{cohesion()}, unused, present for S3 method consistency but may be used -by other methods that implement it.} +\item{\dots}{For \code{vertex_connectivity()}, these dots must be empty. +For \code{cohesion()}, unused, present for S3 method consistency but may be used by other methods that implement it.} -\item{checks}{Logical. Whether to check that the graph is connected -and also the degree of the vertices. If the graph is not (strongly) -connected then the connectivity is obviously zero. Otherwise if the minimum -degree is one then the vertex connectivity is also one. It is a good idea to -perform these checks, as they can be done quickly compared to the -connectivity calculation itself. They were suggested by Peter McMahan, -thanks Peter.} +\item{checks}{Logical. +Whether to check that the graph is connected and also the degree of the vertices. +If the graph is not (strongly) connected then the connectivity is obviously zero. +Otherwise if the minimum degree is one then the vertex connectivity is also one. +It is a good idea to perform these checks, as they can be done quickly compared to the connectivity calculation itself. +They were suggested by Peter McMahan, thanks Peter.} } \value{ A scalar real value. } \description{ -The vertex connectivity of a graph or two vertices, this is recently also -called group cohesion. +The vertex connectivity of a graph or two vertices, this is recently also called group cohesion. } \details{ -The vertex connectivity of two vertices (\code{source} and \code{target}) in -a graph is the minimum number of vertices that must be deleted to -eliminate all (directed) paths from \code{source} to \code{target}. -\code{vertex_connectivity()} calculates this quantity if both the -\code{source} and \code{target} arguments are given and they're not -\code{NULL}. +The vertex connectivity of two vertices (\code{source} and \code{target}) in a graph is the minimum number of vertices that must be deleted to eliminate all (directed) paths from \code{source} to \code{target}. +\code{vertex_connectivity()} calculates this quantity if both the \code{source} and \code{target} arguments are given and they're not \code{NULL}. -The vertex connectivity of a pair is the same as the number -of different (i.e. node-independent) paths from source to -target, assuming no direct edges between them. +The vertex connectivity of a pair is the same as the number of different (i.e. node-independent) paths from source to target, +assuming no direct edges between them. -The vertex connectivity of a graph is the minimum vertex connectivity of all -(ordered) pairs of vertices in the graph. In other words this is the minimum -number of vertices needed to remove to make the graph not strongly -connected. (If the graph is not strongly connected then this is zero.) -\code{vertex_connectivity()} calculates this quantity if neither the -\code{source} nor \code{target} arguments are given. (I.e. they are both -\code{NULL}.) +The vertex connectivity of a graph is the minimum vertex connectivity of all (ordered) pairs of vertices in the graph. +In other words this is the minimum number of vertices needed to remove to make the graph not strongly connected. +(If the graph is not strongly connected then this is zero.) +\code{vertex_connectivity()} calculates this quantity if neither the \code{source} nor \code{target} arguments are given. +(I.e. they are both \code{NULL}.) -A set of vertex disjoint directed paths from \code{source} to \code{vertex} -is a set of directed paths between them whose vertices do not contain common -vertices (apart from \code{source} and \code{target}). The maximum number of -vertex disjoint paths between two vertices is the same as their vertex -connectivity in most cases (if the two vertices are not connected by an -edge). +A set of vertex disjoint directed paths from \code{source} to \code{vertex} is a set of directed paths between them whose vertices do not contain common vertices (apart from \code{source} and \code{target}). +The maximum number of vertex disjoint paths between two vertices is the same as their vertex connectivity in most cases (if the two vertices are not connected by an edge). -The cohesion of a graph (as defined by White and Harary, see references), is -the vertex connectivity of the graph. This is calculated by -\code{cohesion()}. +The cohesion of a graph (as defined by White and Harary, see references), is the vertex connectivity of the graph. +This is calculated by \code{cohesion()}. -These three functions essentially calculate the same measure(s), more -precisely \code{vertex_connectivity()} is the most general, the other two are -included only for the ease of using more descriptive function names. +These three functions essentially calculate the same measure(s), more precisely \code{vertex_connectivity()} is the most general, +the other two are included only for the ease of using more descriptive function names. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Flows.html#igraph_st_vertex_connectivity}{\code{st_vertex_connectivity()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Flows.html#igraph_vertex_connectivity}{\code{vertex_connectivity()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Flows.html#igraph_vertex_disjoint_paths}{\code{vertex_disjoint_paths()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Flows.html#igraph_cohesion}{\code{cohesion()}} diff --git a/man/voronoi_cells.Rd b/man/voronoi_cells.Rd index c48fcba3787..30789b8aafe 100644 --- a/man/voronoi_cells.Rd +++ b/man/voronoi_cells.Rd @@ -20,21 +20,18 @@ voronoi_cells( \item{...}{These dots are for future extensions and must be empty.} -\item{weights}{Possibly a numeric vector giving edge weights. If this is -\code{NULL} and the graph has a \code{weight} edge attribute, then the -attribute is used. If this is \code{NA} then no weights are used (even if -the graph has a \code{weight} attribute). In a weighted graph, the length -of a path is the sum of the weights of its constituent edges.} +\item{weights}{Possibly a numeric vector giving edge weights. +If this is \code{NULL} and the graph has a \code{weight} edge attribute, then the attribute is used. +If this is \code{NA} then no weights are used (even if the graph has a \code{weight} attribute). +In a weighted graph, the length of a path is the sum of the weights of its constituent edges.} -\item{mode}{Character string. In directed graphs, whether to compute -distances from generator vertices to other vertices (\code{"out"}), to -generator vertices from other vertices (\code{"in"}), or ignore edge -directions entirely (\code{"all"}). Ignored in undirected graphs.} +\item{mode}{Character string. +In directed graphs, whether to compute distances from generator vertices to other vertices (\code{"out"}), +to generator vertices from other vertices (\code{"in"}), or ignore edge directions entirely (\code{"all"}). +Ignored in undirected graphs.} -\item{tiebreaker}{Character string that specifies what to do when a vertex -is at the same distance from multiple generators. \code{"random"} assigns -a minimal-distance generator randomly, \code{"first"} takes the first one, -and \code{"last"} takes the last one.} +\item{tiebreaker}{Character string that specifies what to do when a vertex is at the same distance from multiple generators. +\code{"random"} assigns a minimal-distance generator randomly, \code{"first"} takes the first one, and \code{"last"} takes the last one.} } \value{ A named list with two components: @@ -50,9 +47,8 @@ numeric vector giving the distance of each vertex from its generator \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} -This function partitions the vertices of a graph based on a set of generator -vertices. Each vertex is assigned to the generator vertex from (or to) which -it is closest. +This function partitions the vertices of a graph based on a set of generator vertices. +Each vertex is assigned to the generator vertex from (or to) which it is closest. \code{\link[=groups]{groups()}} may be used on the output of this function. } diff --git a/man/walktrap.community.Rd b/man/walktrap.community.Rd index 6f96f8022b3..a9949a4a019 100644 --- a/man/walktrap.community.Rd +++ b/man/walktrap.community.Rd @@ -14,35 +14,30 @@ walktrap.community( ) } \arguments{ -\item{graph}{The input graph. Edge directions are ignored in directed -graphs.} +\item{graph}{The input graph. +Edge directions are ignored in directed graphs.} -\item{weights}{The weights of the edges. It must be a positive numeric vector, -\code{NULL} or \code{NA}. If it is \code{NULL} and the input graph has a -\sQuote{weight} edge attribute, then that attribute will be used. If -\code{NULL} and no such attribute is present, then the edges will have equal -weights. Set this to \code{NA} if the graph was a \sQuote{weight} edge -attribute, but you don't want to use it for community detection. Larger edge -weights increase the probability that an edge is selected by the random -walker. In other words, larger edge weights correspond to stronger connections.} +\item{weights}{The weights of the edges. +It must be a positive numeric vector, \code{NULL} or \code{NA}. +If it is \code{NULL} and the input graph has a \sQuote{weight} edge attribute, then that attribute will be used. +If \code{NULL} and no such attribute is present, then the edges will have equal weights. +Set this to \code{NA} if the graph was a \sQuote{weight} edge attribute, but you don't want to use it for community detection. +Larger edge weights increase the probability that an edge is selected by the random walker. +In other words, larger edge weights correspond to stronger connections.} \item{steps}{The length of the random walks to perform.} -\item{merges}{Logical, whether to include the merge matrix in the -result.} +\item{merges}{Logical, whether to include the merge matrix in the result.} -\item{modularity}{Logical, whether to include the vector of the -modularity scores in the result. If the \code{membership} argument is true, -then it will always be calculated.} +\item{modularity}{Logical, whether to include the vector of the modularity scores in the result. +If the \code{membership} argument is true, then it will always be calculated.} -\item{membership}{Logical, whether to calculate the membership vector -for the split corresponding to the highest modularity value.} +\item{membership}{Logical, whether to calculate the membership vector for the split corresponding to the highest modularity value.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{walktrap.community()} was renamed to \code{\link[=cluster_walktrap]{cluster_walktrap()}} to create a more -consistent API. +\code{walktrap.community()} was renamed to \code{\link[=cluster_walktrap]{cluster_walktrap()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/watts.strogatz.game.Rd b/man/watts.strogatz.game.Rd index a3946533b33..510cece5667 100644 --- a/man/watts.strogatz.game.Rd +++ b/man/watts.strogatz.game.Rd @@ -11,22 +11,18 @@ watts.strogatz.game(dim, size, nei, p, loops = FALSE, multiple = FALSE) \item{size}{Integer constant, the size of the lattice along each dimension.} -\item{nei}{Integer constant, the neighborhood within which the vertices of -the lattice will be connected.} +\item{nei}{Integer constant, the neighborhood within which the vertices of the lattice will be connected.} \item{p}{Real constant between zero and one, the rewiring probability.} -\item{loops}{Logical, whether loops edges are allowed in the -generated graph.} +\item{loops}{Logical, whether loops edges are allowed in the generated graph.} -\item{multiple}{Logical, whether multiple edges are allowed int the -generated graph.} +\item{multiple}{Logical, whether multiple edges are allowed int the generated graph.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{watts.strogatz.game()} was renamed to \code{\link[=sample_smallworld]{sample_smallworld()}} to create a more -consistent API. +\code{watts.strogatz.game()} was renamed to \code{\link[=sample_smallworld]{sample_smallworld()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Generators.html#igraph_watts_strogatz_game}{\code{watts_strogatz_game()}} diff --git a/man/weighted_cliques.Rd b/man/weighted_cliques.Rd index b9f03e0bd94..d88a98cb283 100644 --- a/man/weighted_cliques.Rd +++ b/man/weighted_cliques.Rd @@ -14,16 +14,14 @@ weighted_cliques( ) } \arguments{ -\item{graph}{The input graph, directed graphs will be considered as -undirected ones, multiple edges and loops are ignored.} +\item{graph}{The input graph, directed graphs will be considered as undirected ones, multiple edges and loops are ignored.} \item{...}{These dots are for future extensions and must be empty.} -\item{vertex.weights}{Vertex weight vector. If the graph has a \code{weight} -vertex attribute, then this is used by default. If the graph does not have a -\code{weight} vertex attribute and this argument is \code{NULL}, then every -vertex is assumed to have a weight of 1. Note that the current implementation -of the weighted clique finder supports positive integer weights only.} +\item{vertex.weights}{Vertex weight vector. +If the graph has a \code{weight} vertex attribute, then this is used by default. +If the graph does not have a \code{weight} vertex attribute and this argument is \code{NULL}, +then every vertex is assumed to have a weight of 1. Note that the current implementation of the weighted clique finder supports positive integer weights only.} \item{min.weight}{Numeric constant, lower limit on the weight of the cliques to find. \code{NULL} means no limit, i.e. it is the same as 0.} @@ -31,29 +29,24 @@ of the weighted clique finder supports positive integer weights only.} \item{max.weight}{Numeric constant, upper limit on the weight of the cliques to find. \code{NULL} means no limit.} -\item{maximal}{Specifies whether to look for all weighted cliques (\code{FALSE}) -or only the maximal ones (\code{TRUE}).} +\item{maximal}{Specifies whether to look for all weighted cliques (\code{FALSE}) or only the maximal ones (\code{TRUE}).} } \value{ -\code{weighted_cliques()} and \code{largest_weighted_cliques()} return a -list containing numeric vectors of vertex IDs. Each list element is a weighted -clique, i.e. a vertex sequence of class \link[=V]{igraph.vs}. +\code{weighted_cliques()} and \code{largest_weighted_cliques()} return a list containing numeric vectors of vertex IDs. +Each list element is a weighted clique, i.e. a vertex sequence of class \link[=V]{igraph.vs}. \code{weighted_clique_num()} returns an integer scalar. } \description{ -These functions find all, the largest or all the maximal weighted cliques in -an undirected graph. The weight of a clique is the sum of the weights of its -vertices. +These functions find all, the largest or all the maximal weighted cliques in an undirected graph. +The weight of a clique is the sum of the weights of its vertices. } \details{ \code{weighted_cliques()} finds all complete subgraphs in the input graph, -obeying the weight limitations given in the \code{min} and \code{max} -arguments. +obeying the weight limitations given in the \code{min} and \code{max} arguments. -\code{largest_weighted_cliques()} finds all largest weighted cliques in the -input graph. A clique is largest if there is no other clique whose total -weight is larger than the weight of this clique. +\code{largest_weighted_cliques()} finds all largest weighted cliques in the input graph. +A clique is largest if there is no other clique whose total weight is larger than the weight of this clique. \code{weighted_clique_num()} calculates the weight of the largest weighted clique(s). } diff --git a/man/which_multiple.Rd b/man/which_multiple.Rd index a705616f7d6..6f7a2ec002a 100644 --- a/man/which_multiple.Rd +++ b/man/which_multiple.Rd @@ -24,8 +24,8 @@ count_loops(graph) \arguments{ \item{graph}{The input graph.} -\item{eids}{The edges to which the query is restricted. The default -\code{NULL} selects all edges.} +\item{eids}{The edges to which the query is restricted. +The default \code{NULL} selects all edges.} } \value{ \code{any_loop()} and \code{any_multiple()} return a Logical. @@ -34,9 +34,9 @@ count_loops(graph) \code{count_multiple()} returns a numeric vector. } \description{ -A loop edge is an edge from a vertex to itself. An edge is a multiple edge -if it has exactly the same head and tail vertices as another edge. A graph -without multiple and loop edges is called a simple graph. +A loop edge is an edge from a vertex to itself. +An edge is a multiple edge if it has exactly the same head and tail vertices as another edge. +A graph without multiple and loop edges is called a simple graph. } \details{ \code{any_loop()} decides whether the graph has any loop edges. @@ -47,19 +47,16 @@ without multiple and loop edges is called a simple graph. \code{any_multiple()} decides whether the graph has any multiple edges. -\code{which_multiple()} decides whether the edges of the graph are multiple -edges. +\code{which_multiple()} decides whether the edges of the graph are multiple edges. \code{count_multiple()} counts the multiplicity of each edge of a graph. -Note that the semantics for \code{which_multiple()} and \code{count_multiple()} is -different. \code{which_multiple()} gives \code{TRUE} for all occurrences of a -multiple edge except for one. I.e. if there are three \code{i-j} edges in the -graph then \code{which_multiple()} returns \code{TRUE} for only two of them while -\code{count_multiple()} returns \sQuote{3} for all three. +Note that the semantics for \code{which_multiple()} and \code{count_multiple()} is different. +\code{which_multiple()} gives \code{TRUE} for all occurrences of a multiple edge except for one. +I.e. if there are three \code{i-j} edges in the graph then \code{which_multiple()} returns \code{TRUE} for only two of them +while \code{count_multiple()} returns \sQuote{3} for all three. -See the examples for getting rid of multiple edges while keeping their -original multiplicity as an edge attribute. +See the examples for getting rid of multiple edges while keeping their original multiplicity as an edge attribute. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_multiple}{\code{is_multiple()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_has_multiple}{\code{has_multiple()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_count_multiple}{\code{count_multiple()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_is_loop}{\code{is_loop()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_has_loop}{\code{has_loop()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Structural.html#igraph_count_loops}{\code{count_loops()}} diff --git a/man/which_mutual.Rd b/man/which_mutual.Rd index 46346529c75..e663f7ff24e 100644 --- a/man/which_mutual.Rd +++ b/man/which_mutual.Rd @@ -9,8 +9,8 @@ which_mutual(graph, eids = NULL, ..., loops = TRUE) \arguments{ \item{graph}{The input graph.} -\item{eids}{Edge sequence, the edges that will be probed. The default -\code{NULL} includes all edges in the order of their IDs.} +\item{eids}{Edge sequence, the edges that will be probed. +The default \code{NULL} includes all edges in the order of their IDs.} \item{...}{These dots are for future extensions and must be empty.} @@ -23,12 +23,10 @@ A logical vector of the same length as the number of edges supplied. This function checks the reciprocal pair of the supplied edges. } \details{ -In a directed graph an (A,B) edge is mutual if the graph also includes a -(B,A) directed edge. +In a directed graph an (A,B) edge is mutual if the graph also includes a (B,A) directed edge. -Note that multi-graphs are not handled properly, i.e. if the graph contains -two copies of (A,B) and one copy of (B,A), then these three edges are -considered to be mutual. +Note that multi-graphs are not handled properly, i.e. if the graph contains two copies of (A,B) and one copy of (B,A), +then these three edges are considered to be mutual. Undirected graphs contain only mutual edges by definition. } @@ -45,8 +43,7 @@ which_mutual(g) sum(which_mutual(g)) / 2 == dyad_census(g)$mut } \seealso{ -\code{\link[=reciprocity]{reciprocity()}}, \code{\link[=dyad_census]{dyad_census()}} if you just -want some statistics about mutual edges. +\code{\link[=reciprocity]{reciprocity()}}, \code{\link[=dyad_census]{dyad_census()}} if you just want some statistics about mutual edges. Other structural.properties: \code{\link[=bfs]{bfs()}}, diff --git a/man/with_edge_.Rd b/man/with_edge_.Rd index 650cd360871..b56a3e06a7e 100644 --- a/man/with_edge_.Rd +++ b/man/with_edge_.Rd @@ -7,7 +7,8 @@ with_edge_(...) } \arguments{ -\item{...}{The attributes to add. They must be named.} +\item{...}{The attributes to add. +They must be named.} } \description{ Constructor modifier to add edge attributes diff --git a/man/with_graph_.Rd b/man/with_graph_.Rd index bc0b3c0a999..0e9352b794f 100644 --- a/man/with_graph_.Rd +++ b/man/with_graph_.Rd @@ -7,7 +7,8 @@ with_graph_(...) } \arguments{ -\item{...}{The attributes to add. They must be named.} +\item{...}{The attributes to add. +They must be named.} } \description{ Constructor modifier to add graph attributes diff --git a/man/with_vertex_.Rd b/man/with_vertex_.Rd index e1b6d04fc06..80a015a8f99 100644 --- a/man/with_vertex_.Rd +++ b/man/with_vertex_.Rd @@ -7,7 +7,8 @@ with_vertex_(...) } \arguments{ -\item{...}{The attributes to add. They must be named.} +\item{...}{The attributes to add. +They must be named.} } \description{ Constructor modifier to add vertex attributes diff --git a/man/write.graph.Rd b/man/write.graph.Rd index 2dffc81a7ad..e0ee7878d4e 100644 --- a/man/write.graph.Rd +++ b/man/write.graph.Rd @@ -15,21 +15,18 @@ write.graph( \arguments{ \item{graph}{The graph to export.} -\item{file}{A connection or a string giving the file name to write the graph -to.} +\item{file}{A connection or a string giving the file name to write the graph to.} -\item{format}{Character string giving the file format. Right now -\code{pajek}, \code{graphml}, \code{dot}, \code{gml}, \code{edgelist}, -\code{lgl}, \code{ncol}, \code{leda} and \code{dimacs} are implemented. As of igraph 0.4 -this argument is case insensitive.} +\item{format}{Character string giving the file format. +Right now \code{pajek}, \code{graphml}, \code{dot}, \code{gml}, \code{edgelist}, \code{lgl}, \code{ncol}, \code{leda} and \code{dimacs} are implemented. +As of igraph 0.4 this argument is case insensitive.} \item{...}{Other, format specific arguments, see below.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\code{write.graph()} was renamed to \code{\link[=write_graph]{write_graph()}} to create a more -consistent API. +\code{write.graph()} was renamed to \code{\link[=write_graph]{write_graph()}} to create a more consistent API. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Foreign.html#igraph_write_graph_edgelist}{\code{write_graph_edgelist()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Foreign.html#igraph_write_graph_pajek}{\code{write_graph_pajek()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Foreign.html#igraph_write_graph_graphml}{\code{write_graph_graphml()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Foreign.html#igraph_write_graph_gml}{\code{write_graph_gml()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Foreign.html#igraph_write_graph_dot}{\code{write_graph_dot()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Foreign.html#igraph_write_graph_leda}{\code{write_graph_leda()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_edges}{\code{edges()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_get_eids}{\code{get_eids()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_vcount}{\code{vcount()}}, \href{https://igraph.org/c/html/0.10.17/igraph-Basic.html#igraph_ecount}{\code{ecount()}} diff --git a/man/write_graph.Rd b/man/write_graph.Rd index 05758654e8a..e129d70ced7 100644 --- a/man/write_graph.Rd +++ b/man/write_graph.Rd @@ -15,13 +15,11 @@ write_graph( \arguments{ \item{graph}{The graph to export.} -\item{file}{A connection or a string giving the file name to write the graph -to.} +\item{file}{A connection or a string giving the file name to write the graph to.} -\item{format}{Character string giving the file format. Right now -\code{pajek}, \code{graphml}, \code{dot}, \code{gml}, \code{edgelist}, -\code{lgl}, \code{ncol}, \code{leda} and \code{dimacs} are implemented. As of igraph 0.4 -this argument is case insensitive.} +\item{format}{Character string giving the file format. +Right now \code{pajek}, \code{graphml}, \code{dot}, \code{gml}, \code{edgelist}, \code{lgl}, \code{ncol}, \code{leda} and \code{dimacs} are implemented. +As of igraph 0.4 this argument is case insensitive.} \item{\dots}{Other, format specific arguments, see below.} } @@ -29,21 +27,22 @@ this argument is case insensitive.} A `NULL``, invisibly. } \description{ -\code{write_graph()} is a general function for exporting graphs to foreign -file formats. The recommended formats for data exchange are GraphML and GML. +\code{write_graph()} is a general function for exporting graphs to foreign file formats. +The recommended formats for data exchange are GraphML and GML. } \section{Edge list format}{ The \code{edgelist} format is a simple text file, -with one edge per line, the two zero-based numerical vertex IDs separated -by a space character. Note that vertices are indexed starting with zero. -The file is sorted by the first and the second column. This format has no -additional arguments. +with one edge per line, the two zero-based numerical vertex IDs separated by a space character. +Note that vertices are indexed starting with zero. +The file is sorted by the first and the second column. +This format has no additional arguments. } \section{NCOL format}{ This format is a plain text edge list in which vertices -are referred to by name rather than numerical ID. Edge weights may be -optionally written. Additional parameters: +are referred to by name rather than numerical ID. +Edge weights may be optionally written. +Additional parameters: \describe{ \item{names}{ The name of a vertex attribute to take vertex names from or @@ -58,13 +57,14 @@ The name of an edge attribute to take edge weights from or \section{Pajek format}{ The \code{pajek} format is provided for interoperability -with the Pajek software only. Since the format does not have a formal -specification, it is not recommended for general data exchange or archival. +with the Pajek software only. +Since the format does not have a formal specification, it is not recommended for general data exchange or archival. } \section{LGL format}{ -The .lgl format is used by the Large Graph Layout visualization software (\url{https://lgl.sourceforge.net}), it can describe undirected optionally weighted graphs. +The .lgl format is used by the Large Graph Layout visualization software (\url{https://lgl.sourceforge.net}), +it can describe undirected optionally weighted graphs. \describe{ \item{names}{The name of a vertex attribute to use for vertex names, or NULL to use numeric IDs.} @@ -80,15 +80,15 @@ Default is FALSE.} This is a line-oriented text file (ASCII) format. The first character of each line defines the type of the line. If the first character is c the line is a comment line and it is ignored. -There is one problem line (p in the file), -it must appear before any node and arc descriptor lines. -The problem line has three fields separated by spaces: the problem type (max or edge), -the number of vertices, and number of edges in the graph. In MAX problems, -exactly two node identification lines are expected (n), one for the source, and one for the target vertex. +There is one problem line (p in the file), it must appear before any node and arc descriptor lines. +The problem line has three fields separated by spaces: the problem type (max or edge), the number of vertices, +and number of edges in the graph. +In MAX problems, exactly two node identification lines are expected (n), one for the source, and one for the target vertex. These have two fields: the ID of the vertex and the type of the vertex, either s ( = source) or t ( = target). Arc lines start with a and have three fields: the source vertex, the target vertex and the edge capacity. -In EDGE problems, there may be a node line (n) for each node. It specifies the node index and an -integer node label. Nodes for which no explicit label was specified will use their index as label. +In EDGE problems, there may be a node line (n) for each node. +It specifies the node index and an integer node label. +Nodes for which no explicit label was specified will use their index as label. In EDGE problems, each edge is specified as an edge line (e). \describe{ \item{source}{Numeric ID of the source vertex.} @@ -111,8 +111,9 @@ GML is a quite general textual format. GraphML is an XML-based file format for representing various types of graphs. When a numerical attribute value is NaN, it will be omitted from the file. -This function assumes that non-ASCII characters in attribute names and string -attribute values are UTF-8 encoded. If this is not the case, the resulting XML file will be invalid. Control characters, i.e. character codes up to and including 31 (with the exception of tab, cr and lf), are not allowed. +This function assumes that non-ASCII characters in attribute names and string attribute values are UTF-8 encoded. +If this is not the case, the resulting XML file will be invalid. +Control characters, i.e. character codes up to and including 31 (with the exception of tab, cr and lf), are not allowed. \describe{ \item{prefixAttr}{Logical, whether to prefix attribute names to ensure uniqueness across vertex/edge/graph attributes. Default is TRUE.} @@ -123,8 +124,9 @@ uniqueness across vertex/edge/graph attributes. Default is TRUE.} This function writes a graph to an output stream in LEDA format. See \url{https://www.algorithmic-solutions.info/leda_guide/graphs/leda_native_graph_fileformat.html}. -The support for the LEDA format is very basic at the moment; igraph writes only the LEDA graph section which supports one selected vertex and edge -attribute and no layout information or visual attributes. +The support for the LEDA format is very basic at the moment; +igraph writes only the LEDA graph section +which supports one selected vertex and edge attribute and no layout information or visual attributes. \describe{ \item{vertex.attr}{Name of vertex attribute to include in the file.} \item{edge.attr}{Name of edge attribute to include in the file.} @@ -136,8 +138,8 @@ attribute and no layout information or visual attributes. DOT is the format used by the widely known GraphViz software, see \url{https://www.graphviz.org} for details. The grammar of the DOT format can be found here: \url{https://www.graphviz.org/doc/info/lang.html}. This is only a preliminary implementation, no visualization information is written. -This format is meant solely for interoperability with Graphviz. It is not recommended for -data exchange or archival. +This format is meant solely for interoperability with Graphviz. +It is not recommended for data exchange or archival. } \section{Related documentation in the C library}{ diff --git a/vignettes/articles/deprecated-dot-case.Rmd b/vignettes/articles/deprecated-dot-case.Rmd index 27ae5b23c2a..dc5e220f688 100644 --- a/vignettes/articles/deprecated-dot-case.Rmd +++ b/vignettes/articles/deprecated-dot-case.Rmd @@ -13,9 +13,8 @@ To provide a more consistent interface, igraph functions that have a dot case na like `add.edges()`, will be deprecated in favor of functions with a snake case name, like `add_edges()`. -Currently, for each function both alternatives work, but we'll incrementally remove the -dot case functions, first emitting deprecation messages when they are used, then in a further version warnings, -until they actually result in an error. +Currently, for each function both alternatives work, but we'll incrementally remove the dot case functions, +first emitting deprecation messages when they are used, then in a further version warnings, until they actually result in an error. Therefore, we'd like to ask you to update your codebases, be they packages or scripts. Thank you for your cooperation! diff --git a/vignettes/articles/installation-troubleshooting.Rmd b/vignettes/articles/installation-troubleshooting.Rmd index 98cf8e93589..7e0b4ce8bb4 100644 --- a/vignettes/articles/installation-troubleshooting.Rmd +++ b/vignettes/articles/installation-troubleshooting.Rmd @@ -8,7 +8,9 @@ knitr::opts_chunk$set( comment = "#>" ) ``` -This page details common problems encountered when trying to install igraph. If you did not find an answer to your problem here, feel free to ask for help on https://igraph.discourse.group/. When you do so, be sure to state: +This page details common problems encountered when trying to install igraph. +If you did not find an answer to your problem here, feel free to ask for help on https://igraph.discourse.group/. +When you do so, be sure to state: 1. the output of `sessionInfo()` 2. where you obtained R from @@ -16,9 +18,13 @@ This page details common problems encountered when trying to install igraph. If ## Cannot compile igraph from sources on Windows or macOS -Do not compile igraph from sources, unless you know what you are doing! It is much more convenient to use the binaries from CRAN instead. These can be installed using `install.packages("igraph")`. +Do not compile igraph from sources, unless you know what you are doing! +It is much more convenient to use the binaries from CRAN instead. +These can be installed using `install.packages("igraph")`. -Usually, it takes a few days for binary releases to become available on CRAN after each new igraph source release. During this period, `install.packages()` will give you a choice about using the latest source release or the previous binary release. Just choose to use the binary release, i.e. respond "no" to "Do you want to install from sources?" +Usually, it takes a few days for binary releases to become available on CRAN after each new igraph source release. +During this period, `install.packages()` will give you a choice about using the latest source release or the previous binary release. +Just choose to use the binary release, i.e. respond "no" to "Do you want to install from sources?" ``` > install.packages('igraph') @@ -31,51 +37,85 @@ igraph 1.2.7 1.2.8 TRUE Do you want to install from sources the package which needs compilation? (Yes/no/cancel) no ``` -CRAN provides Windows and macOS binaries only for the last two minor releases of R (e.g. 4.5 and 4.4), but not for older ones (e.g. 4.3). Make sure that you are using one of these supported R versions. Refer to https://r-project.org/ to find out what the latest R version is at the moment. +CRAN provides Windows and macOS binaries only for the last two minor releases of R (e.g. 4.5 and 4.4), but not for older ones (e.g. 4.3). +Make sure that you are using one of these supported R versions. +Refer to https://r-project.org/ to find out what the latest R version is at the moment. -Note that the pre-compiled binaries on CRAN are only compatible with the R distribution [provided by CRAN itself](https://www.r-project.org/). If you obtained R from different sources, such as Homebrew or MacPorts on macOS, you will not be able to use these, and the only way to install packages will be to compile them from sources. +Note that the pre-compiled binaries on CRAN are only compatible with the R distribution [provided by CRAN itself](https://www.r-project.org/). +If you obtained R from different sources, such as Homebrew or MacPorts on macOS, you will not be able to use these, +and the only way to install packages will be to compile them from sources. #### I still want to compile igraph from sources -If you decide to try to compile from sources anyway, basic requirements are listed below. It is assumed that you are comfortable compiling software from sources and resolving basic issues as they arise. Otherwise, please use the binaries. +If you decide to try to compile from sources anyway, basic requirements are listed below. +It is assumed that you are comfortable compiling software from sources and resolving basic issues as they arise. +Otherwise, please use the binaries. - - Make sure you have a compatible toolchain installed, including a Fortran compiler. On macOS, make sure you have Xcode and [`gfortran` from here](https://cran.r-project.org/bin/macosx/tools/). For Windows, you will need Rtools. - - On Windows, see the [instructions for installing Rtools for your version of R](https://cran.r-project.org/bin/windows/Rtools/). Check the "Using pacman" link in the [Rtools 4.0 instructions](https://cran.r-project.org/bin/windows/Rtools/rtools40.html). You will find a [copyable pacman command for installing all dependencies](https://github.com/igraph/rigraph/#installation). - - On Windows, make sure you have the GLPK C library installed. This is not the same as the Rglpk R package. Instructions for installing libraries for Rtools4 on Windows are [here](https://cran.r-project.org/bin/windows/Rtools/) + - Make sure you have a compatible toolchain installed, including a Fortran compiler. + On macOS, make sure you have Xcode and [`gfortran` from here](https://cran.r-project.org/bin/macosx/tools/). + For Windows, you will need Rtools. + - On Windows, see the [instructions for installing Rtools for your version of R](https://cran.r-project.org/bin/windows/Rtools/). + Check the "Using pacman" link in the [Rtools 4.0 instructions](https://cran.r-project.org/bin/windows/Rtools/rtools40.html). + You will find a [copyable pacman command for installing all dependencies](https://github.com/igraph/rigraph/#installation). + - On Windows, make sure you have the GLPK C library installed. + This is not the same as the Rglpk R package. + Instructions for installing libraries for Rtools4 on Windows are [here](https://cran.r-project.org/bin/windows/Rtools/) ## Cannot compile igraph from sources on Linux -Since CRAN does not provide binary packages for Linux, Linux users usually need to compile igraph from sources. In order to do so, make sure that you have all the prerequisites: +Since CRAN does not provide binary packages for Linux, Linux users usually need to compile igraph from sources. +In order to do so, make sure that you have all the prerequisites: - - C, C++ and Fortran compilers. On Debian-based distros, use `sudo apt install build-essential gfortran`. On Fedora, use `yum install gcc gcc-c++ gcc-gfortran`. - - Development packages for `glpk` and `libxml2`. On Debian-based distros, use `sudo apt install libglpk-dev libxml2-dev`. On Fedora, use `yum install glpk-devel libxml2-devel`. + - C, C++ and Fortran compilers. + On Debian-based distros, use `sudo apt install build-essential gfortran`. + On Fedora, use `yum install gcc gcc-c++ gcc-gfortran`. + - Development packages for `glpk` and `libxml2`. + On Debian-based distros, use `sudo apt install libglpk-dev libxml2-dev`. + On Fedora, use `yum install glpk-devel libxml2-devel`. -If you have an Anaconda environment active, deactivate it _before_ compiling igraph. Having conda environments active are known to cause a number of issues, both during compilation and later during usage. +If you have an Anaconda environment active, deactivate it _before_ compiling igraph. +Having conda environments active are known to cause a number of issues, both during compilation and later during usage. -Set up your Anaconda installation so no environment is active by default. Make sure that Anaconda's `bin` directory is _not_ present in your `PATH` environment variable. [Do not add this directory to the path manually. Instead, let Anaconda manage it using `conda init`, as recommended by Anaconda.](https://docs.anaconda.com/anaconda/user-guide/faq/#distribution-faq-linux-path) Only Anaconda's `condabin`, _but not `bin`_, should be present in the `PATH`. +Set up your Anaconda installation so no environment is active by default. +Make sure that Anaconda's `bin` directory is _not_ present in your `PATH` environment variable. +[Do not add this directory to the path manually. Instead, let Anaconda manage it using `conda init`, as recommended by Anaconda.](https://docs.anaconda.com/anaconda/user-guide/faq/#distribution-faq-linux-path) Only Anaconda's `condabin`, +_but not `bin`_, should be present in the `PATH`. ## fatal error: glpk.h: No such file or directory -If you are using Windows or macOS, please refer to [Cannot compile igraph from sources on Windows or macOS](#cannot-compile-igraph-from-sources-on-windows-or-macos). +If you are using Windows or macOS, +please refer to [Cannot compile igraph from sources on Windows or macOS](#cannot-compile-igraph-from-sources-on-windows-or-macos). If you are using Linux, please refer to [Cannot compile igraph from sources on Linux](#cannot-compile-igraph-from-sources-on-linux). ## libgfortran.so.4: cannot open shared object file: No such file or directory -This problem occurs when there are multiple incompatible gfortran versions on your machine. Most commonly, one of them comes from an active Anaconda environment. Always deactivate all Anaconda environments using `conda deactivate` before installing igraph using `install.packages()`. +This problem occurs when there are multiple incompatible gfortran versions on your machine. +Most commonly, one of them comes from an active Anaconda environment. +Always deactivate all Anaconda environments using `conda deactivate` before installing igraph using `install.packages()`. -Set up your Anaconda installation so no environment is active by default. Make sure that Anaconda's `bin` directory is _not_ present in your `PATH` environment variable. [Do not add this directory to the path manually. Instead, let Anaconda manage it using `conda init`, as recommended by Anaconda.](https://docs.anaconda.com/anaconda/user-guide/faq/#distribution-faq-linux-path) Only Anaconda's `condabin`, _but not `bin`_, should be present in the `PATH`. +Set up your Anaconda installation so no environment is active by default. +Make sure that Anaconda's `bin` directory is _not_ present in your `PATH` environment variable. +[Do not add this directory to the path manually. Instead, let Anaconda manage it using `conda init`, as recommended by Anaconda.](https://docs.anaconda.com/anaconda/user-guide/faq/#distribution-faq-linux-path) Only Anaconda's `condabin`, +_but not `bin`_, should be present in the `PATH`. ## libmkl_rt.so.1: cannot open shared object file: No such file or directory -This issue typically occurs when an Anaconda environment containing conflicting BLAS libraries is active. Please refer to the instructions in the section "libgfortran.so.4: cannot open shared object file". +This issue typically occurs when an Anaconda environment containing conflicting BLAS libraries is active. +Please refer to the instructions in the section "libgfortran.so.4: cannot open shared object file". ## libglpk.so.40: cannot open shared object file: No such file or directory -This error will occur on Linux systems when igraph was compiled with GLPK support, but GLPK is not currently installed on the system. To resolve it, install GLPK. On Debian-based systems, simply use `sudo apt install libglpk40`. +This error will occur on Linux systems when igraph was compiled with GLPK support, but GLPK is not currently installed on the system. +To resolve it, install GLPK. +On Debian-based systems, simply use `sudo apt install libglpk40`. -This may happen when a binary version of igraph is installed from https://packagemanager.rstudio.com. These binaries assume that GLPK is present on your system. +This may happen when a binary version of igraph is installed from https://packagemanager.rstudio.com. +These binaries assume that GLPK is present on your system. ## GLPK is not available, Unimplemented function call -This error occurs when calling an igraph function that relies on GLPK, but igraph was compiled without GLPK support. This cannot happen in igraph 2.0.3 and later. If you are compiling an earlier version, please refer to ["Cannot compile igraph from sources on Linux"](#cannot-compile-igraph-from-sources-on-linux) for instructions on compiling igraph with GLPK support. +This error occurs when calling an igraph function that relies on GLPK, but igraph was compiled without GLPK support. +This cannot happen in igraph 2.0.3 and later. +If you are compiling an earlier version, +please refer to ["Cannot compile igraph from sources on Linux"](#cannot-compile-igraph-from-sources-on-linux) for instructions on compiling igraph with GLPK support. diff --git a/vignettes/igraph.Rmd b/vignettes/igraph.Rmd index 6682bc6b3fc..789e7f7be4a 100644 --- a/vignettes/igraph.Rmd +++ b/vignettes/igraph.Rmd @@ -10,7 +10,11 @@ vignette: > %\VignetteEncoding{UTF-8} --- -`igraph` is a fast and open source library for the analysis of graphs or networks. The library consists of a core written in C and bindings for high-level languages including [R](https://r.igraph.org/), [Python](https://python.igraph.org/en/stable/), and [Mathematica](https://szhorvat.net/pelican/igraphm-a-mathematica-interface-for-igraph.html). This vignette aims to give you an overview of the functions available in the R interface of `igraph`. For detailed function by function API documentation, check out . +`igraph` is a fast and open source library for the analysis of graphs or networks. +The library consists of a core written in C and bindings for high-level languages including [R](https://r.igraph.org/), +[Python](https://python.igraph.org/en/stable/), and [Mathematica](https://szhorvat.net/pelican/igraphm-a-mathematica-interface-for-igraph.html). +This vignette aims to give you an overview of the functions available in the R interface of `igraph`. +For detailed function by function API documentation, check out . *** **NOTE:** Throughout this tutorial, we will use words `graph` and `network` as synonyms, and also `vertex` or `node` as synonyms. @@ -23,7 +27,8 @@ To install the library from CRAN, use: install.packages("igraph") ``` -More details on dependencies, requirements, and troubleshooting on installation are found on the main [documentation page](https://r.igraph.org/). +More details on dependencies, requirements, +and troubleshooting on installation are found on the main [documentation page](https://r.igraph.org/). ## Usage To use `igraph` in your R code, you must first load the library: @@ -39,19 +44,27 @@ library("igraph") Now you have all `igraph` functions available. ## Creating a graph -`igraph` offers many ways to create a graph. The simplest one is the function `make_empty_graph()`: +`igraph` offers many ways to create a graph. +The simplest one is the function `make_empty_graph()`: ```{r} g <- make_empty_graph() ``` -The most common way to create a graph is `make_graph()`, which constructs a network based on specified edges. For example, to make a graph with 10 nodes (numbered `1` to `10`) and two edges connecting nodes `1-2` and `1-5`: +The most common way to create a graph is `make_graph()`, which constructs a network based on specified edges. +For example, to make a graph with 10 nodes (numbered `1` to `10`) and two edges connecting nodes `1-2` and `1-5`: ```{r} g <- make_graph(edges = c(1, 2, 1, 5), n = 10, directed = FALSE) ``` -Starting from igraph 0.8.0, you can also include literal here, via igraph's formula notation. In this case, the first term of the formula has to start with a `~` character, just like regular formulae in R. The expressions consist of vertex names and edge operators. An edge operator is a sequence of `-` and `+` characters, the former is for the edges and the latter is used for arrow heads. The edges can be arbitrarily long, that is to say, you may use as many `-` characters to "draw" them as you like. If all edge operators consist of only `-` characters then the graph will be undirected, whereas a single `+` character implies a directed graph: that is to say to create the same graph as above: +Starting from igraph 0.8.0, you can also include literal here, via igraph's formula notation. +In this case, the first term of the formula has to start with a `~` character, +just like regular formulae in R. The expressions consist of vertex names and edge operators. +An edge operator is a sequence of `-` and `+` characters, the former is for the edges and the latter is used for arrow heads. +The edges can be arbitrarily long, that is to say, you may use as many `-` characters to "draw" them as you like. +If all edge operators consist of only `-` characters then the graph will be undirected, +whereas a single `+` character implies a directed graph: that is to say to create the same graph as above: ```{r echo = TRUE} g <- make_graph(~ 1--2, 1--5, 3, 4, 5, 6, 7, 8, 9, 10) @@ -63,7 +76,8 @@ We can print the graph to get a summary of its nodes and edges: g ``` -This means: **U**ndirected **N**amed graph with **10** vertices and **2** edges, with the exact edges listed out. If the graph has a `[name]` attribute, it is printed as well. +This means: **U**ndirected **N**amed graph with **10** vertices and **2** edges, with the exact edges listed out. +If the graph has a `[name]` attribute, it is printed as well. *** **NOTE**: `summary()` does not list the edges, which is convenient for large graphs with millions of edges: @@ -74,7 +88,9 @@ This means: **U**ndirected **N**amed graph with **10** vertices and **2** edges, summary(g) ``` -The same function `make_graph()` can create some notable graphs by just specifying their name. For example you can create the graph that represents the social network of Zachary's karate club, that shows the friendship between 34 members of a karate club at a US university in the 1970s: +The same function `make_graph()` can create some notable graphs by just specifying their name. +For example you can create the graph that represents the social network of Zachary's karate club, +that shows the friendship between 34 members of a karate club at a US university in the 1970s: ```{r echo = TRUE} g <- make_graph("Zachary") @@ -90,20 +106,27 @@ A more detailed description of plotting options is provided later on in this tut ## Vertex and edge IDs -Vertices and edges have numerical vertex IDs in igraph. Vertex IDs are always consecutive and they start with 1. For a graph with n vertices the vertex IDs are always between 1 and n. If some operation changes the number of vertices in the graphs, for instance a subgraph is created via `induced_subgraph()`, then the vertices are renumbered to satisfy this criterion. +Vertices and edges have numerical vertex IDs in igraph. +Vertex IDs are always consecutive and they start with 1. For a graph with n vertices the vertex IDs are always between 1 and n. If some operation changes the number of vertices in the graphs, +for instance a subgraph is created via `induced_subgraph()`, then the vertices are renumbered to satisfy this criterion. The same is true for the edges as well: edge IDs are always between 1 and m, the total number of edges in the graph. *** -**NOTE**: If you are familiar with the C core or the [Python](https://python.igraph.org/en/stable/) interface of `igraph`, you might have noticed that in those languages vertex and edge IDs start from 0. In the R interface, both start from 1 instead, to keep consistent with the convention in each language. +**NOTE**: If you are familiar with the C core or the [Python](https://python.igraph.org/en/stable/) interface of `igraph`, +you might have noticed that in those languages vertex and edge IDs start from 0. In the R interface, both start from 1 instead, +to keep consistent with the convention in each language. *** -In addition to IDs, vertices and edges can be assigned a name and other attributes. That makes it easier to track them whenever the graph is altered. Examples of this pattern are shown later on in this tutorial. +In addition to IDs, vertices and edges can be assigned a name and other attributes. +That makes it easier to track them whenever the graph is altered. +Examples of this pattern are shown later on in this tutorial. ## Adding/deleting vertices and edges -Let's continue working with the Karate club graph. To add one or more vertices to an existing graph, use `add_vertices()`: +Let's continue working with the Karate club graph. +To add one or more vertices to an existing graph, use `add_vertices()`: ```{r} g <- add_vertices(g, 3) @@ -115,9 +138,12 @@ Similarly, to add edges you can use `add_edges()`: g <- add_edges(g, edges = c(1, 35, 1, 36, 34, 37)) ``` -Edges are added by specifying the source and target vertex IDs for each edge. This call added three edges, one connecting vertices `1` and `35`, one connecting vertices `1` and `36`, and one connecting vertices `34` and `37`. +Edges are added by specifying the source and target vertex IDs for each edge. +This call added three edges, one connecting vertices `1` and `35`, one connecting vertices `1` and `36`, +and one connecting vertices `34` and `37`. -In addition to the `add_vertices()` and `add_edges()` functions, the plus operator can be used to add vertices or edges to graph. The actual operation that is performed depends on the type of the right hand side argument: +In addition to the `add_vertices()` and `add_edges()` functions, the plus operator can be used to add vertices or edges to graph. +The actual operation that is performed depends on the type of the right hand side argument: ```{r echo = TRUE, eval=FALSE} g <- g + edges(c(1, 35, 1, 36, 34, 37)) @@ -125,15 +151,19 @@ g <- g + edges(c(1, 35, 1, 36, 34, 37)) You can add a single vertex/edge at a time using `add_vertex()` and `add_edge()` (singular). -**Warning**: If you need to add multiple edges to a graph, it is much more efficient to call `add_edges()` once rather than repeatedly calling `add_edge()` with a single new edge. The same applies when deleting edges and vertices. +**Warning**: If you need to add multiple edges to a graph, +it is much more efficient to call `add_edges()` once rather than repeatedly calling `add_edge()` with a single new edge. +The same applies when deleting edges and vertices. -If you try to add edges to vertices with invalid IDs (i.e., you try to add an edge to vertex `38` when the graph has only 37 vertices), `igraph` shows an error: +If you try to add edges to vertices with invalid IDs (i.e., you try to add an edge to vertex `38` when the graph has only 37 vertices), +`igraph` shows an error: ```{r echo = TRUE, error = TRUE} g <- add_edges(g, edges = c(38, 37)) ``` -Let us add some more vertices and edges to our graph. In `igraph` we can use the `magrittr` package, which provides a mechanism for chaining commands with the operator `%>%`: +Let us add some more vertices and edges to our graph. +In `igraph` we can use the `magrittr` package, which provides a mechanism for chaining commands with the operator `%>%`: ```{r echo = TRUE} g <- g %>% @@ -143,7 +173,11 @@ g <- g %>% g ``` -We now have an undirected graph with 40 vertices and 86 edges. Vertex and edge IDs are always *contiguous*, so if you delete a vertex all subsequent vertices will be renumbered. When a vertex is renumbered, edges are **not** renumbered, but their source and target vertices will be. Use `delete_vertices()` and `delete_edges()` to perform these operations. For instance, to delete the edge connecting vertices `1-34`, get its ID and then delete it: +We now have an undirected graph with 40 vertices and 86 edges. +Vertex and edge IDs are always *contiguous*, so if you delete a vertex all subsequent vertices will be renumbered. +When a vertex is renumbered, edges are **not** renumbered, but their source and target vertices will be. +Use `delete_vertices()` and `delete_edges()` to perform these operations. +For instance, to delete the edge connecting vertices `1-34`, get its ID and then delete it: ```{r echo = TRUE} edge_id_to_delete <- get_edge_ids(g, c(1, 34)) @@ -161,7 +195,10 @@ g <- make_ring(10) %>% delete_edges("10|1") plot(g) ``` -The example above shows that you can also refer to edges with strings containing the IDs of the source and target vertices, connected by a pipe symbol `|`. `"10|1"` in the above example means the edge that connects vertex 10 to vertex 1. Of course you can also use the edge IDs directly, or retrieve them with the `get_edge_ids()` function: +The example above shows that you can also refer to edges with strings containing the IDs of the source and target vertices, +connected by a pipe symbol `|`. +`"10|1"` in the above example means the edge that connects vertex 10 to vertex 1. Of course you can also use the edge IDs directly, +or retrieve them with the `get_edge_ids()` function: ```{r echo = TRUE} g <- make_ring(5) @@ -169,7 +206,10 @@ g <- delete_edges(g, get_edge_ids(g, c(1, 5, 4, 5))) plot(g) ``` -As another example, let's make a chordal graph. Remember that a graph is chordal (or triangulated) if each of its cycles of four or more nodes has a chord, which is an edge joining two nodes that are not adjacent in the cycle. First, let's create the initial graph using `graph_from_literal()`: +As another example, let's make a chordal graph. +Remember that a graph is chordal (or triangulated) if each of its cycles of four or more nodes has a chord, +which is an edge joining two nodes that are not adjacent in the cycle. +First, let's create the initial graph using `graph_from_literal()`: ```{r} g1 <- graph_from_literal( @@ -185,7 +225,9 @@ g1 <- graph_from_literal( plot(g1) ``` -In the example above, the `:` operator was used to define vertex sets. If an edge operator connects two vertex sets, then every vertex from the first set will be connected to every vertex in the second set. Then we use `is_chordal()` to evaluate if our graph is chordal and to search what edges are missing to fill-in the graph: +In the example above, the `:` operator was used to define vertex sets. +If an edge operator connects two vertex sets, then every vertex from the first set will be connected to every vertex in the second set. +Then we use `is_chordal()` to evaluate if our graph is chordal and to search what edges are missing to fill-in the graph: ```{r echo = TRUE} is_chordal(g1, fillin = TRUE) @@ -200,14 +242,17 @@ plot(chordal_graph) ## Constructing graphs -In addition to `make_empty_graph()`, `make_graph()`, and `make_graph_from_literal()`, `igraph` includes many other function to construct a graph. Some are *deterministic*, that is to say they produce the same graph each single time, for instance `make_tree()`: +In addition to `make_empty_graph()`, `make_graph()`, and `make_graph_from_literal()`, +`igraph` includes many other function to construct a graph. +Some are *deterministic*, that is to say they produce the same graph each single time, for instance `make_tree()`: ```{r echo = TRUE} graph1 <- make_tree(127, 2, mode = "undirected") summary(graph1) ``` -This generates a regular tree graph with 127 vertices, each vertex having two children. No matter how many times you call `make_tree()`, the generated graph will always be the same if you use the same parameters: +This generates a regular tree graph with 127 vertices, each vertex having two children. +No matter how many times you call `make_tree()`, the generated graph will always be the same if you use the same parameters: ```{r} graph2 <- make_tree(127, 2, mode = "undirected") @@ -217,31 +262,41 @@ graph2 <- make_tree(127, 2, mode = "undirected") identical_graphs(graph1, graph2) ``` -Other functions generate graphs *stochastically*, which means they produce a different graph each time. For instance `sample_grg()`: +Other functions generate graphs *stochastically*, which means they produce a different graph each time. +For instance `sample_grg()`: ```{r echo = TRUE} graph1 <- sample_grg(100, 0.2) summary(graph1) ``` -This generates a geometric random graph: *n* points are chosen randomly and uniformly inside the unit square and pairs of points closer to each other than a predefined distance *d* are connected by an edge. If you generate GRGs with the same parameters, they will be different: +This generates a geometric random graph: +*n* points are chosen randomly and uniformly inside the unit square and pairs of points closer to each other than a predefined distance *d* are connected by an edge. +If you generate GRGs with the same parameters, they will be different: ```{r echo = TRUE} graph2 <- sample_grg(100, 0.2) identical_graphs(graph1, graph2) ``` -A slightly looser way to check if the graphs are equivalent is via `isomorphic`. Two graphs are said to be isomorphic if they have the same number of components (vertices and edges) and maintain a one-to-one correspondence between vertices and edges, that is to say, they are connected in the same way. +A slightly looser way to check if the graphs are equivalent is via `isomorphic`. +Two graphs are said to be isomorphic +if they have the same number of components (vertices and edges) and maintain a one-to-one correspondence between vertices and edges, +that is to say, they are connected in the same way. ```{r echo = TRUE} isomorphic(graph1, graph2) ``` -Checking for isomorphism can take a while for large graphs (in this case, the answer can quickly be given by checking the degree sequence of the two graphs). `identical_graph()` is a stricter criterion than `isomorphic()`: the two graphs must have the same list of vertices and edges, in exactly the same order, with same directedness, and the two graphs must also have identical graph, vertex and edge attributes. +Checking for isomorphism can take a while for large graphs (in this case, the answer can quickly be given by checking the degree sequence of the two graphs). +`identical_graph()` is a stricter criterion than `isomorphic()`: the two graphs must have the same list of vertices and edges, +in exactly the same order, with same directedness, and the two graphs must also have identical graph, vertex and edge attributes. ## Setting and retrieving attributes -In addition to IDs, vertex and edges can have *attributes* such as a name, coordinates for plotting, metadata, and weights. The graph itself can have such attributes too (for instance a name, which will show in `summary()`). In a sense, every graph, vertex and edge can be used as an R namespace to store and retrieve these attributes. +In addition to IDs, vertex and edges can have *attributes* such as a name, coordinates for plotting, metadata, and weights. +The graph itself can have such attributes too (for instance a name, which will show in `summary()`). +In a sense, every graph, vertex and edge can be used as an R namespace to store and retrieve these attributes. To demonstrate the use of attributes, let us create a simple social network: @@ -252,7 +307,10 @@ g <- make_graph( ) ``` -Each vertex represents a person, so we want to store ages, genders and types of connection between two people (`is_formal()` refers to whether a connection between one person or another is formal or informal, respectively colleagues or friends). The `$` operator is a shortcut to get and set graph attributes. It is shorter and just as readable as `graph_attr()` and `set_graph_attr()`. +Each vertex represents a person, so we want to store ages, +genders and types of connection between two people (`is_formal()` refers to whether a connection between one person or another is formal or informal, respectively colleagues or friends). +The `$` operator is a shortcut to get and set graph attributes. +It is shorter and just as readable as `graph_attr()` and `set_graph_attr()`. ```{r echo = TRUE} V(g)$age <- c(25, 31, 18, 23, 47, 22, 50) @@ -261,7 +319,9 @@ E(g)$is_formal <- c(FALSE, FALSE, TRUE, TRUE, TRUE, FALSE, TRUE, FALSE, FALSE) summary(g) ``` -`V()` and `E()` are the standard way to obtain a sequence of all vertices and edges, respectively. This assigns an attribute to *all* vertices/edges at once. Another way to generate our social network is with the use of `set_vertex_attr()` and `set_edge_attr()` and the operator `%>%`: +`V()` and `E()` are the standard way to obtain a sequence of all vertices and edges, respectively. +This assigns an attribute to *all* vertices/edges at once. +Another way to generate our social network is with the use of `set_vertex_attr()` and `set_edge_attr()` and the operator `%>%`: ```{r echo = TRUE, eval=FALSE} g <- make_graph( @@ -282,14 +342,17 @@ E(g)$is_formal[1] <- TRUE E(g)$is_formal ``` -Attribute values can be set to any R object, but note that storing the graph in some file formats might result in the loss of complex attribute values. Vertices, edges and the graph itself can all be used to set attributes, for instance to add a date to the graph: +Attribute values can be set to any R object, +but note that storing the graph in some file formats might result in the loss of complex attribute values. +Vertices, edges and the graph itself can all be used to set attributes, for instance to add a date to the graph: ```{r echo = TRUE} g$date <- c("2022-02-11") graph_attr(g, "date") ``` -To retrieve attributes, you can also use `graph_attr()`, `vertex_attr()`, and `edge_attr()`. To find the ID of a vertex you can use the function `match()`: +To retrieve attributes, you can also use `graph_attr()`, `vertex_attr()`, and `edge_attr()`. +To find the ID of a vertex you can use the function `match()`: ```{r echo = TRUE} match(c("Ibrahim"), V(g)$name) @@ -313,15 +376,25 @@ If you want to save a graph in R with all the attributes use `saveRDS()` (and th ## Structural properties of graphs -`igraph` provides a large set of functions to calculate various structural properties of graphs. It is beyond the scope of this tutorial to document all of them, hence this section will only introduce a few of them for illustrative purposes. We will work on the small social network constructed in the previous section. +`igraph` provides a large set of functions to calculate various structural properties of graphs. +It is beyond the scope of this tutorial to document all of them, +hence this section will only introduce a few of them for illustrative purposes. +We will work on the small social network constructed in the previous section. -Perhaps the simplest property one can think of is the _degree_. The degree of a vertex equals the number of edges adjacent to it. In case of directed networks, we can also define _in-degree_ (the number of edges pointing towards the vertex) and _out-degree_ (the number of edges originating from the vertex). `igraph` is able to calculate all of them using a simple syntax: +Perhaps the simplest property one can think of is the _degree_. +The degree of a vertex equals the number of edges adjacent to it. +In case of directed networks, +we can also define _in-degree_ (the number of edges pointing towards the vertex) and _out-degree_ (the number of edges originating from the vertex). +`igraph` is able to calculate all of them using a simple syntax: ```{r echo = TRUE} degree(g) ``` -If the graph was directed, we would have been able to calculate the in- and out-degrees separately using `degree(mode = "in")` and `degree(mode = "out")`. You can also pass a single vertex ID or a list of vertex IDs to `degree()` if you want to calculate the degrees for only a subset of vertices: +If the graph was directed, +we would have been able to calculate the in- and out-degrees separately using `degree(mode = "in")` and `degree(mode = "out")`. +You can also pass a single vertex ID or a list of vertex IDs to `degree()` +if you want to calculate the degrees for only a subset of vertices: ```{r echo = TRUE} degree(g, 7) @@ -343,14 +416,22 @@ It also works for single vertices: degree(g, "Bruno") ``` -A similar syntax is used for most of the structural properties `igraph` can calculate. For vertex properties, the functions accept a vertex ID, a vertex name, or a list of vertex IDs or names (and if they are omitted, the default is the set of all vertices). For edge properties, the functions accept a single edge ID or a list of edge IDs. +A similar syntax is used for most of the structural properties `igraph` can calculate. +For vertex properties, the functions accept a vertex ID, a vertex name, +or a list of vertex IDs or names (and if they are omitted, the default is the set of all vertices). +For edge properties, the functions accept a single edge ID or a list of edge IDs. *** -**NOTE:** For some measures, it does not make sense to calculate them only for a few vertices or edges instead of the whole graph, as it would take the same time anyway. In this case, the functions won't accept vertex or edge IDs, but you can still restrict the resulting list later using standard operations. One such example is eigenvector centrality (`evcent()`). +**NOTE:** For some measures, it does not make sense to calculate them only for a few vertices or edges instead of the whole graph, +as it would take the same time anyway. +In this case, the functions won't accept vertex or edge IDs, but you can still restrict the resulting list later using standard operations. +One such example is eigenvector centrality (`evcent()`). *** -Besides degree, igraph includes built-in routines to calculate many other centrality properties, including vertex and edge betweenness (`edge_betweenness()`) or Google's PageRank (`page_rank()`) just to name a few. Here we just illustrate edge betweenness: +Besides degree, igraph includes built-in routines to calculate many other centrality properties, +including vertex and edge betweenness (`edge_betweenness()`) or Google's PageRank (`page_rank()`) just to name a few. +Here we just illustrate edge betweenness: ```{r echo = TRUE} edge_betweenness(g) @@ -367,7 +448,8 @@ as_edgelist(g)[ebs == max(ebs), ] ### Selecting vertices -Imagine that in a given social network, you want to find out who has the largest degree. You can do that with the tools presented so far and the `which.max()` function: +Imagine that in a given social network, you want to find out who has the largest degree. +You can do that with the tools presented so far and the `which.max()` function: ```{r echo = TRUE} which.max(degree(g)) @@ -400,13 +482,16 @@ seq <- V(graph)[2, 3, 7, "foo", 3.5] ## Error in simple_vs_index(x, ii, na_ok) : Unknown vertex selected ``` -Attribute names can also be used as-is within the indexing brackets of `V()` and `E()`. This can be combined with R's ability to use Boolean vectors for indexing to obtain very concise and readable expressions to retrieve a subset of the vertex or edge set of a graph. For instance, the following command gives you the names of the individuals younger than 30 years in our social network: +Attribute names can also be used as-is within the indexing brackets of `V()` and `E()`. +This can be combined with R's ability to use Boolean vectors for indexing to obtain very concise and readable expressions to retrieve a subset of the vertex or edge set of a graph. +For instance, the following command gives you the names of the individuals younger than 30 years in our social network: ```{r echo = TRUE} V(g)[age < 30]$name ``` -Of course, `<` is not the only boolean operator that can be used for this. Other possibilities include the following: +Of course, `<` is not the only boolean operator that can be used for this. +Other possibilities include the following: | Operator | Meaning | |---------------------------|-----------------------------------------------------------------| @@ -418,14 +503,15 @@ Of course, `<` is not the only boolean operator that can be used for this. Other | `>=` | The attribute/property value must be *greater than or equal to* | | `%in%` | The attribute/property value must be *included in* | -You can also create a "not in" operator from `%in%` using the `Negate()` -function: +You can also create a "not in" operator from `%in%` using the `Negate()` function: ```{r echo = TRUE} `%notin%` <- Negate(`%in%`) ``` -If an attribute has the same name as an `igraph` function, you should be careful as the syntax can become a little confusing. For instance, if there is an attribute named `degree` that represents the grades of an exam for each person, that should not be confused with the `igraph` function that computes the degrees of vertices in a network sense: +If an attribute has the same name as an `igraph` function, you should be careful as the syntax can become a little confusing. +For instance, if there is an attribute named `degree` that represents the grades of an exam for each person, +that should not be confused with the `igraph` function that computes the degrees of vertices in a network sense: ```{r echo = TRUE} V(g)$degree <- c("A", "B", "B+", "A+", "C", "A", "B") @@ -437,9 +523,12 @@ V(g)$name[degree(g) == 3] ``` ### Selecting edges -Edges can be selected based on attributes just like vertices. As mentioned above, the standard way to get edges is `E`. Moreover, there are a few special structural properties for selecting edges. +Edges can be selected based on attributes just like vertices. +As mentioned above, the standard way to get edges is `E`. +Moreover, there are a few special structural properties for selecting edges. -Using `.from()` allows you to filter the edge sequence based on the source vertices of the edges. For instance, to select all the edges originating from Carmina (who has vertex index 3): +Using `.from()` allows you to filter the edge sequence based on the source vertices of the edges. +For instance, to select all the edges originating from Carmina (who has vertex index 3): ```{r echo = TRUE, warning = FALSE} E(g)[.from(3)] @@ -451,15 +540,22 @@ Of course it also works with vertex names: E(g)[.from("Carmina")] ``` -Using `.to()` filters edge sequences based on the target vertices. This is different from `.from()` if the graph is directed, while it gives the same answer for undirected graphs. Using `.inc()` selects only those edges that are incident on a single vertex or at least one of the vertices, irrespective of the edge directions. +Using `.to()` filters edge sequences based on the target vertices. +This is different from `.from()` if the graph is directed, while it gives the same answer for undirected graphs. +Using `.inc()` selects only those edges that are incident on a single vertex or at least one of the vertices, +irrespective of the edge directions. -The `%--%` operator can be used to select edges between specific groups of vertices, ignoring edge directions in directed graphs. For instance, the following expression selects all the edges between Carmina (vertex index 3), Nang (vertex index 5) and Samira (vertex index 6): +The `%--%` operator can be used to select edges between specific groups of vertices, ignoring edge directions in directed graphs. +For instance, the following expression selects all the edges between Carmina (vertex index 3), +Nang (vertex index 5) and Samira (vertex index 6): ```{r echo = TRUE} E(g)[3:5 %--% 5:6] ``` -To make the `%--%` operator work with names, you can build string vectors containing the names and then use these vectors as operands. For instance, to select all the edges that connect men to women, we can do the following after re-adding the gender attribute that we deleted earlier: +To make the `%--%` operator work with names, you can build string vectors containing the names and then use these vectors as operands. +For instance, to select all the edges that connect men to women, +we can do the following after re-adding the gender attribute that we deleted earlier: ```{r} V(g)$gender <- c("f", "m", "f", "m", "m", "f", "m") @@ -481,21 +577,31 @@ E(g)[men %--% women] ## Treating a graph as an adjacency matrix -The adjacency matrix is another way to represent a graph. In an adjacency matrix, rows and columns are labeled by graph vertices, and the elements of the matrix indicate the number of edges between vertices *i* and *j*. The adjacency matrix for the example graph is: +The adjacency matrix is another way to represent a graph. +In an adjacency matrix, rows and columns are labeled by graph vertices, +and the elements of the matrix indicate the number of edges between vertices *i* and *j*. +The adjacency matrix for the example graph is: ```{r echo = TRUE} as_adjacency_matrix(g) ``` -For example, Carmina (`1, 0, 0, 1, 1, 1, 0`) is directly connected to Alejandra (who has vertex index 1), Moshe (index 4), Nang (index 5) and Samira (index 6), but not to Bruno (index 2) or to Ibrahim (index 7). +For example, Carmina (`1, 0, 0, 1, 1, 1, 0`) is directly connected to Alejandra (who has vertex index 1), Moshe (index 4), +Nang (index 5) and Samira (index 6), but not to Bruno (index 2) or to Ibrahim (index 7). ## Layouts and plotting -A graph is an abstract mathematical object without a specific representation in 2D, 3D or any other geometric space. This means that whenever we want to visualise a graph, we have to find a mapping from vertices to coordinates in two- or three-dimensional space first, preferably in a way that is useful and/or pleasing for the eye. A separate branch of graph theory, namely graph drawing, tries to solve this problem via several graph layout algorithms. igraph implements quite a few layout algorithms and is also able to draw them onto the screen or to any output format that R itself supports. +A graph is an abstract mathematical object without a specific representation in 2D, 3D or any other geometric space. +This means that whenever we want to visualise a graph, +we have to find a mapping from vertices to coordinates in two- or three-dimensional space first, +preferably in a way that is useful and/or pleasing for the eye. +A separate branch of graph theory, namely graph drawing, +tries to solve this problem via several graph layout algorithms. igraph implements quite a few layout algorithms and is also able to draw them onto the screen or to any output format that R itself supports. ### Layout algorithms -The layout functions in igraph always start with `layout`. The following table summarises them: +The layout functions in igraph always start with `layout`. +The following table summarises them: | Method name | Algorithm description | |----------------------|-----------------------------------------------------------------------------------| @@ -509,13 +615,17 @@ The layout functions in igraph always start with `layout`. The following table s | `layout_as_tree` | Reingold-Tilford tree layout, useful for (almost) tree-like graphs | | `layout_nicely` | Layout algorithm that automatically picks one of the other algorithms based on certain properties of the graph | -Layout algorithms can be called directly with a graph as its first argument. They will return a matrix with two columns and as many rows as the number of vertices in the graph; each row will correspond to the position of a single vertex, ordered by vertex IDs. Some algorithms have a 3D variant; in this case they return 3 columns instead of 2. +Layout algorithms can be called directly with a graph as its first argument. +They will return a matrix with two columns and as many rows as the number of vertices in the graph; +each row will correspond to the position of a single vertex, ordered by vertex IDs. +Some algorithms have a 3D variant; in this case they return 3 columns instead of 2. ```{r} layout <- layout_with_kk(g) ``` -Some layout algorithms take additional arguments; for instance, when laying out a graph as a tree, it might make sense to specify which vertex is to be placed at the root of the layout: +Some layout algorithms take additional arguments; for instance, when laying out a graph as a tree, +it might make sense to specify which vertex is to be placed at the root of the layout: ```{r} layout <- layout_as_tree(g, root = 2) @@ -533,9 +643,11 @@ layout <- layout_with_kk(g) plot(g, layout = layout, main = "Social network with the Kamada-Kawai layout algorithm") ``` -This should open a new window showing a visual representation of the network. Remember that the exact placement of nodes may be different on your machine since the layout is not deterministic. +This should open a new window showing a visual representation of the network. +Remember that the exact placement of nodes may be different on your machine since the layout is not deterministic. -The `layout` argument also accepts functions; in this case, the function will be called with the graph as its first argument. This makes it possible to just pass the name of a layout function directly, without creating a layout variable: +The `layout` argument also accepts functions; in this case, the function will be called with the graph as its first argument. +This makes it possible to just pass the name of a layout function directly, without creating a layout variable: ```{r} plot( @@ -545,9 +657,8 @@ plot( ) ``` -To improve the visuals, a trivial addition would be to color the vertices -according to the gender. We should also try to place the labels slightly -outside the vertices to improve readability: +To improve the visuals, a trivial addition would be to color the vertices according to the gender. +We should also try to place the labels slightly outside the vertices to improve readability: ```{r} V(g)$color <- ifelse(V(g)$gender == "m", "yellow", "red") @@ -558,13 +669,17 @@ plot( ) ``` -You can also treat the `gender` attribute as a factor and provide the colors with an argument to `plot()`, which takes precedence over the `color` vertex attribute. Colors will be assigned automatically to levels of a factor: +You can also treat the `gender` attribute as a factor and provide the colors with an argument to `plot()`, +which takes precedence over the `color` vertex attribute. +Colors will be assigned automatically to levels of a factor: ```{r} plot(g, layout = layout, vertex.label.dist = 3.5, vertex.color = as.factor(V(g)$gender)) ``` -As seen above with the `vertex.color` argument, you can specify visual properties as arguments to `plot` instead of using vertex or edge attributes. The following plot shows the formal ties with thick lines while informal ones with thin lines: +As seen above with the `vertex.color` argument, +you can specify visual properties as arguments to `plot` instead of using vertex or edge attributes. +The following plot shows the formal ties with thick lines while informal ones with thin lines: ```{r} plot(g, @@ -574,9 +689,12 @@ plot(g, ) ``` -This latter approach is preferred if you want to keep the properties of the visual representation of your graph separate from the graph itself. +This latter approach is preferred +if you want to keep the properties of the visual representation of your graph separate from the graph itself. -In summary, there are special vertex and edge properties that correspond to the visual representation of the graph. These attributes override the default settings of igraph (i.e color, weight, name, shape, layout, etc.). The following two tables summarise the most frequently used visual attributes for vertices and edges, respectively: +In summary, there are special vertex and edge properties that correspond to the visual representation of the graph. +These attributes override the default settings of igraph (i.e color, weight, name, shape, layout, etc.). +The following two tables summarise the most frequently used visual attributes for vertices and edges, respectively: ### Vertex attributes controlling graph plots @@ -619,7 +737,11 @@ These settings can be specified as arguments to the `plot` function to control t ## igraph and the outside world -No graph module would be complete without some kind of import/export functionality that enables the package to communicate with external programs and toolkits. `igraph` is no exception: it provides functions to read the most common graph formats and to save graphs into files obeying these format specifications. The main functions for reading and writing from/to file are `read_graph()` and `write_graph()`, respectively. The following table summarises the formats igraph can read or write: +No graph module would be complete without some kind of import/export functionality that enables the package to communicate with external programs and toolkits. +`igraph` is no exception: +it provides functions to read the most common graph formats and to save graphs into files obeying these format specifications. +The main functions for reading and writing from/to file are `read_graph()` and `write_graph()`, respectively. +The following table summarises the formats igraph can read or write: | Format | Short name | Read function | Write function | |------------------|------------------|------------------|------------------| @@ -635,7 +757,11 @@ No graph module would be complete without some kind of import/export functionali | [Pajek](http://mrvar.fdv.uni-lj.si/pajek/) format | `pajek` | `read_graph(file, format = c("pajek"))` | `write_graph(graph, file, format = c("pajek"))` | *** -**NOTE:** Each file format has its own limitations. For instance, not all of them can store attributes. Your best bet is probably GraphML or GML if you want to save igraph graphs in a format that can be read from an external package and you want to preserve numeric and string attributes. Edge list and NCOL is also fine if you don't have attributes (NCOL supports vertex names and edge weights, though). +**NOTE:** Each file format has its own limitations. +For instance, not all of them can store attributes. +Your best bet is probably GraphML or GML +if you want to save igraph graphs in a format that can be read from an external package and you want to preserve numeric and string attributes. +Edge list and NCOL is also fine if you don't have attributes (NCOL supports vertex names and edge weights, though). *** @@ -643,7 +769,10 @@ No graph module would be complete without some kind of import/export functionali This tutorial is a brief introduction to `igraph` in R. We sincerely hope you enjoyed reading it and that it will be useful for your own network analyses. -For a detailed description of specific functions, see . For questions on how to use `igraph`, please visit our [Forum](https://igraph.discourse.group). To report a bug, open a [Github issue](https://github.com/igraph/rigraph/issues). Please do not ask usage questions on Github directly as it's meant for developers rather than users. +For a detailed description of specific functions, see . +For questions on how to use `igraph`, please visit our [Forum](https://igraph.discourse.group). +To report a bug, open a [Github issue](https://github.com/igraph/rigraph/issues). +Please do not ask usage questions on Github directly as it's meant for developers rather than users. ## Session info diff --git a/vignettes/igraph_ES.rmd b/vignettes/igraph_ES.rmd index c102c204450..4a08355ed94 100644 --- a/vignettes/igraph_ES.rmd +++ b/vignettes/igraph_ES.rmd @@ -10,11 +10,16 @@ vignette: > %\VignetteEncoding{UTF-8} --- -`igraph` es una biblioteca rápida y de código abierto para el análisis de grafos o redes. El núcleo de ésta libreria se encuentra escrito en C y contiene enlaces para lenguajes de alto nivel como [R](https://r.igraph.org/), [Python](https://python.igraph.org/), y [Mathematica](https://szhorvat.net/pelican/igraphm-a-mathematica-interface-for-igraph.html). Esta viñeta pretende darte una visión general de las funciones disponibles de `igraph` en R. Para obtener información detallada de cada función, consulta . +`igraph` es una biblioteca rápida y de código abierto para el análisis de grafos o redes. +El núcleo de ésta libreria se encuentra escrito en C y contiene enlaces para lenguajes de alto nivel como [R](https://r.igraph.org/), +[Python](https://python.igraph.org/), y [Mathematica](https://szhorvat.net/pelican/igraphm-a-mathematica-interface-for-igraph.html). +Esta viñeta pretende darte una visión general de las funciones disponibles de `igraph` en R. Para obtener información detallada de cada función, +consulta . ------------------------------------------------------------------------ -**NOTA:** A lo largo de este tutorial, utilizaremos las palabras `grafo` y `red` como sinónimos, y también `vértice` o `nodo` como sinónimos. +**NOTA:** A lo largo de este tutorial, utilizaremos las palabras `grafo` y `red` como sinónimos, +y también `vértice` o `nodo` como sinónimos. ------------------------------------------------------------------------ @@ -26,7 +31,8 @@ Para instalar la librería desde CRAN, usa: install.packages("igraph") ``` -Encontrarás más información sobre dependencias, requisitos y resolución de problemas sobre la instalación en la [página principal](https://r.igraph.org/). +Encontrarás más información sobre dependencias, +requisitos y resolución de problemas sobre la instalación en la [página principal](https://r.igraph.org/). ## Uso de igraph @@ -44,19 +50,29 @@ Ahora tienes todas las funciones de `igraph` disponibles. ## Crear un grafo -`igraph` ofrece muchas formas de crear un grafo. La más sencilla es con la función `make_empty_graph()`: +`igraph` ofrece muchas formas de crear un grafo. +La más sencilla es con la función `make_empty_graph()`: ```{r} g <- make_empty_graph() ``` -La forma más común de crear un grafo es con `make_graph()`, que construye un grafo basado en especificar las aristas. Por ejemplo, Para hacer un grafo con 10 nodos (numerados `1` a `10`) y dos aristas que conecten los nodos `1-2` y `1-5`: +La forma más común de crear un grafo es con `make_graph()`, que construye un grafo basado en especificar las aristas. +Por ejemplo, Para hacer un grafo con 10 nodos (numerados `1` a `10`) y dos aristas que conecten los nodos `1-2` y `1-5`: ```{r} g <- make_graph(edges = c(1,2, 1,5), n=10, directed = FALSE) ``` -A partir de igraph 0.8.0, también puedes incluir literales mediante la notación de fórmulas de igraph. En este caso, el primer término de la fórmula tiene que empezar con un carácter `~`, como comúnmente se usa en las fórmulas en R. Las expresiones constan de los nombres de los vértices y los operadores de las aristas. El operador de un arista es una secuencia de caracteres `-` y `+`, el primero es para indicar propiamente las aristas y el segundo para las puntas de flecha (dirección). Puedes utilizar tantos caracteres `-` como quieras para "dibujarlas". Si todos los operadores de un arista están formados únicamente por caracteres `-`, el grafo será no dirigido, mientras que un único carácter `+` implica un grafo dirigido. Por ejemplo, para crear el mismo grafo que antes: +A partir de igraph 0.8.0, también puedes incluir literales mediante la notación de fórmulas de igraph. +En este caso, el primer término de la fórmula tiene que empezar con un carácter `~`, +como comúnmente se usa en las fórmulas en R. Las expresiones constan de los nombres de los vértices y los operadores de las aristas. +El operador de un arista es una secuencia de caracteres `-` y `+`, +el primero es para indicar propiamente las aristas y el segundo para las puntas de flecha (dirección). +Puedes utilizar tantos caracteres `-` como quieras para "dibujarlas". +Si todos los operadores de un arista están formados únicamente por caracteres `-`, el grafo será no dirigido, +mientras que un único carácter `+` implica un grafo dirigido. +Por ejemplo, para crear el mismo grafo que antes: ```{r echo = TRUE} g <- make_graph(~ 1--2, 1--5, 3, 4, 5, 6, 7, 8, 9, 10) @@ -68,7 +84,8 @@ Podemos imprimir el grafo para obtener un resumen de sus nodos y aristas: g ``` -Esto significa: grafo no dirigido (**U**ndirected) con **10** vértices y **2** aristas, que se enlistan en la última parte. Si el grafo tiene un atributo [nombre], también se imprime. +Esto significa: grafo no dirigido (**U**ndirected) con **10** vértices y **2** aristas, que se enlistan en la última parte. +Si el grafo tiene un atributo [nombre], también se imprime. ------------------------------------------------------------------------ @@ -80,7 +97,9 @@ Esto significa: grafo no dirigido (**U**ndirected) con **10** vértices y **2** summary(g) ``` -También `make_graph()` puede crear algunos grafos destacados con sólo especificar su nombre. Por ejemplo, puedes generar el grafo que muestra la red social del club de kárate de Zachary, que refleja la amistad entre los 34 miembros del club de una universidad de los Estados Unidos en la década de los 70s: +También `make_graph()` puede crear algunos grafos destacados con sólo especificar su nombre. +Por ejemplo, puedes generar el grafo que muestra la red social del club de kárate de Zachary, +que refleja la amistad entre los 34 miembros del club de una universidad de los Estados Unidos en la década de los 70s: ```{r echo = TRUE} g <- make_graph("Zachary") @@ -96,21 +115,30 @@ Más adelante en este tutorial se ofrece una descripción detallada de las opcio ## IDs de vértices y aristas -Los vértices y las aristas tienen un identificador numérico en igraph. Los ID de los vértices son siempre consecutivos y empiezan por 1. Para un grafo con "n" vértices, los ID de los vértices están siempre entre 1 y "n". Si alguna operación cambia el número de vértices en los grafos, por ejemplo, se crea un subgrafo mediante `induced_subgraph()`, entonces los vértices se vuelven a enumerar para satisfacer este criterio. +Los vértices y las aristas tienen un identificador numérico en igraph. +Los ID de los vértices son siempre consecutivos y empiezan por 1. Para un grafo con "n" vértices, +los ID de los vértices están siempre entre 1 y "n". +Si alguna operación cambia el número de vértices en los grafos, por ejemplo, se crea un subgrafo mediante `induced_subgraph()`, +entonces los vértices se vuelven a enumerar para satisfacer este criterio. Lo mismo ocurre con las aristas: los ID de las aristas están siempre entre 1 y "m", el número total de aristas del grafo. ------------------------------------------------------------------------ -**NOTA**: Si estás familiarizado con C o con la interfaz [Python](https://python.igraph.org/en/stable/) de `igraph`, te habrás dado cuenta de que en esos lenguajes los IDs de vértices y aristas empiezan por 0. En la interfaz de R, ambos empiezan por 1, para mantener la coherencia con la convención de cada lenguaje. +**NOTA**: Si estás familiarizado con C o con la interfaz [Python](https://python.igraph.org/en/stable/) de `igraph`, +te habrás dado cuenta de que en esos lenguajes los IDs de vértices y aristas empiezan por 0. En la interfaz de R, ambos empiezan por 1, +para mantener la coherencia con la convención de cada lenguaje. ------------------------------------------------------------------------ -Además de los IDs, a los vértices y aristas se les puede asignar un nombre y otros atributos. Esto facilita su seguimiento cada vez que se altera un grafo. Más adelante en este tutorial se muestran ejemplos de cómo alterar estas características. +Además de los IDs, a los vértices y aristas se les puede asignar un nombre y otros atributos. +Esto facilita su seguimiento cada vez que se altera un grafo. +Más adelante en este tutorial se muestran ejemplos de cómo alterar estas características. ## Añadir y borrar vértices y aristas -Sigamos trabajando con el grafo del club de kárate. Para añadir uno o más vértices a un grafo existente, utiliza `add_vertices()`: +Sigamos trabajando con el grafo del club de kárate. +Para añadir uno o más vértices a un grafo existente, utiliza `add_vertices()`: ```{r} g <- add_vertices(g, 3) @@ -122,9 +150,12 @@ Del mismo modo, para añadir aristas puedes utilizar `add_edges()`: g <- add_edges(g, edges = c(1,35, 1,36, 34,37)) ``` -Las aristas se añaden especificando el ID del vértice origen y el vértice destino de cada arista. Con las instrucciones anteriores se añaden tres aristas, una que conecta los vértices `1` y `35`, otra que conecta los vértices `1` y `36` y otra que conecta los vértices `34` y `37`. +Las aristas se añaden especificando el ID del vértice origen y el vértice destino de cada arista. +Con las instrucciones anteriores se añaden tres aristas, una que conecta los vértices `1` y `35`, +otra que conecta los vértices `1` y `36` y otra que conecta los vértices `34` y `37`. -Además de las funciones `add_vertices()` y `add_edges()`, se puede utilizar el operador "+" para añadir vértices o aristas al grafo. La operación que se realice dependerá del tipo de argumento del lado derecho: +Además de las funciones `add_vertices()` y `add_edges()`, se puede utilizar el operador "+" para añadir vértices o aristas al grafo. +La operación que se realice dependerá del tipo de argumento del lado derecho: ```{r echo = TRUE, eval=FALSE} g <- g + edges(c(1,35, 1,36, 34,37)) @@ -132,15 +163,19 @@ g <- g + edges(c(1,35, 1,36, 34,37)) Puedes añadir un solo vértice/arista a la vez usando `add_vertex()` y `add_edge()` (singular). -**Advertencia**: Si necesitas añadir múltiples aristas a un grafo, es mucho más eficiente usar `add_edges()` una vez que utilizar repetidamente `add_edge()` con una nueva arista a la vez. Lo mismo ocurre al eliminar aristas y vértices. +**Advertencia**: Si necesitas añadir múltiples aristas a un grafo, +es mucho más eficiente usar `add_edges()` una vez que utilizar repetidamente `add_edge()` con una nueva arista a la vez. +Lo mismo ocurre al eliminar aristas y vértices. -Si intentas añadir aristas a vértices con IDs no válidos (por ejemplo, intentas añadir una arista al vértice `38` cuando el grafo sólo tiene 37 vértices), `igraph` muestra un error: +Si intentas añadir aristas a vértices con IDs no válidos (por ejemplo, intentas añadir una arista al vértice `38` cuando el grafo sólo tiene 37 vértices), +`igraph` muestra un error: ```{r echo = TRUE, error = TRUE} g <- add_edges(g, edges = c(38, 37)) ``` -Añadamos más vértices y aristas a nuestro grafo. En `igraph` podemos utilizar el paquete `magrittr`, que proporciona un mecanismo para encadenar comandos con el operador `%>%`: +Añadamos más vértices y aristas a nuestro grafo. +En `igraph` podemos utilizar el paquete `magrittr`, que proporciona un mecanismo para encadenar comandos con el operador `%>%`: ```{r echo = TRUE} g <- g %>% @@ -150,7 +185,12 @@ g <- g %>% g ``` -Ahora tenemos un grafo no dirigido con 40 vértices y 89 aristas. Los IDs de los vértices y aristas son siempre *contiguos*, así que si borras un vértice, todos los vértices subsecuentes se vuelven a enumerar. Cuando se re-numera un vértice, las aristas **no** se vuelven a enumerar, pero sí sus vértices origen y destino. Puedes usar `delete_vertices()` y `delete_edges()` para realizar estas operaciones. Por ejemplo, para borrar la arista que conecta los vértices `1-34`, obtén su ID y luego bórrala: +Ahora tenemos un grafo no dirigido con 40 vértices y 89 aristas. +Los IDs de los vértices y aristas son siempre *contiguos*, así que si borras un vértice, +todos los vértices subsecuentes se vuelven a enumerar. +Cuando se re-numera un vértice, las aristas **no** se vuelven a enumerar, pero sí sus vértices origen y destino. +Puedes usar `delete_vertices()` y `delete_edges()` para realizar estas operaciones. +Por ejemplo, para borrar la arista que conecta los vértices `1-34`, obtén su ID y luego bórrala: ```{r echo = TRUE} edge_id_para_borrar <- get_edge_ids(g, c(1,34)) @@ -168,7 +208,10 @@ g <- make_ring(10) %>% delete_edges("10|1") plot(g) ``` -El ejemplo anterior muestra que también puedes referirte a las aristas indicando los IDs de los vértices origen y destino, conectados por el símbolo `|`. En el ejemplo, `"10|1"` significa la arista que conecta el vértice `10` con el vértice `1`. Por supuesto, también puedes usar los IDs de las aristas directamente, o recuperarlos con la función `get_edge_ids()`: +El ejemplo anterior muestra que también puedes referirte a las aristas indicando los IDs de los vértices origen y destino, +conectados por el símbolo `|`. +En el ejemplo, `"10|1"` significa la arista que conecta el vértice `10` con el vértice `1`. +Por supuesto, también puedes usar los IDs de las aristas directamente, o recuperarlos con la función `get_edge_ids()`: ```{r echo = TRUE} g <- make_ring(5) @@ -176,7 +219,10 @@ g <- delete_edges(g, get_edge_ids(g, c(1,5, 4,5))) plot(g) ``` -Veamos otro ejemplo, hagamos un grafo cordal. Recuerda que un grafo es cordal (o triangulado) si cada uno de sus ciclos de cuatro o más nodos tienen una "cuerda", que es una arista que une dos nodos que no son adyacentes en el ciclo. En primer lugar, vamos a crear el grafo inicial utilizando `graph_from_literal()`: +Veamos otro ejemplo, hagamos un grafo cordal. +Recuerda que un grafo es cordal (o triangulado) si cada uno de sus ciclos de cuatro o más nodos tienen una "cuerda", +que es una arista que une dos nodos que no son adyacentes en el ciclo. +En primer lugar, vamos a crear el grafo inicial utilizando `graph_from_literal()`: ```{r} g1 <- graph_from_literal( @@ -193,7 +239,10 @@ g1 <- graph_from_literal( plot(g1) ``` -En este ejemplo, se ha utilizado el operador `:` para definir conjuntos de vértices. Si el operador de un arista conecta dos conjuntos de vértices, entonces cada vértice del primer conjunto estará conectado a cada vértice del segundo conjunto. A continuación utilizamos `is_chordal()` para evaluar si nuestro grafo es cordal y buscar qué aristas faltan para rellenar el grafo: +En este ejemplo, se ha utilizado el operador `:` para definir conjuntos de vértices. +Si el operador de un arista conecta dos conjuntos de vértices, +entonces cada vértice del primer conjunto estará conectado a cada vértice del segundo conjunto. +A continuación utilizamos `is_chordal()` para evaluar si nuestro grafo es cordal y buscar qué aristas faltan para rellenar el grafo: ```{r echo = TRUE} is_chordal(g1, fillin=TRUE) @@ -208,14 +257,17 @@ plot(chordal_graph) ## Construcción de grafos -Además de `make_empty_graph()`, `make_graph()` y `make_graph_from_literal()`, `igraph` incluye muchas otras funciones para construir un grafo. Algunas son *deterministas*, es decir, producen el mismo grafo cada vez, por ejemplo `make_tree()`: +Además de `make_empty_graph()`, `make_graph()` y `make_graph_from_literal()`, +`igraph` incluye muchas otras funciones para construir un grafo. +Algunas son *deterministas*, es decir, producen el mismo grafo cada vez, por ejemplo `make_tree()`: ```{r echo = TRUE} graph1 <- make_tree(127, 2, mode = "undirected") summary(g) ``` -Esto genera un grafo regular en forma de árbol con 127 vértices, cada vértice con dos hijos. No importa cuántas veces llames a `make_tree()`, el grafo generado será siempre el mismo si utilizas los mismos parámetros: +Esto genera un grafo regular en forma de árbol con 127 vértices, cada vértice con dos hijos. +No importa cuántas veces llames a `make_tree()`, el grafo generado será siempre el mismo si utilizas los mismos parámetros: ```{r} graph2 <- make_tree(127, 2, mode = "undirected") @@ -232,24 +284,34 @@ graph1 <- sample_grg(100, 0.2) summary(graph1) ``` -Esto genera un grafo geométrico aleatorio: Se eligen *n* puntos de forma aleatoria y uniforme dentro del espacio métrico, y los pares de puntos más cercanos entre sí respecto a una distancia predeterminada *d* se conectan mediante una arista. Si se generan GRGs con los mismos parámetros, serán diferentes: +Esto genera un grafo geométrico aleatorio: Se eligen *n* puntos de forma aleatoria y uniforme dentro del espacio métrico, +y los pares de puntos más cercanos entre sí respecto a una distancia predeterminada *d* se conectan mediante una arista. +Si se generan GRGs con los mismos parámetros, serán diferentes: ```{r echo = TRUE} graph2 <- sample_grg(100, 0.2) identical_graphs(graph1, graph2) ``` -Una forma un poco más relajada de comprobar si los grafos son equivalentes es mediante `isomorphic()`. Se dice que dos grafos son isomorfos si tienen el mismo número de componentes (vértices y aristas) y mantienen una correspondencia uno a uno entre vértices y aristas, es decir, están conectados de la misma manera: +Una forma un poco más relajada de comprobar si los grafos son equivalentes es mediante `isomorphic()`. +Se dice que dos grafos son isomorfos si tienen el mismo número de componentes (vértices y aristas) y mantienen una correspondencia uno a uno entre vértices y aristas, +es decir, están conectados de la misma manera: ```{r echo = TRUE} isomorphic(graph1, graph2) ``` -Comprobar el isomorfismo puede llevar un tiempo en el caso de grafos grandes (en este caso, la respuesta puede darse rápidamente comprobando la secuencia de grados de los dos grafos). `identical_graph()` es un criterio más estricto que `isomorphic()`: los dos grafos deben tener la misma lista de vértices y aristas, exactamente en el mismo orden, con la misma direccionalidad, y los dos grafos también deben tener idénticos atributos de grafo, vértice y arista. +Comprobar el isomorfismo puede llevar un tiempo en el caso de grafos grandes (en este caso, la respuesta puede darse rápidamente comprobando la secuencia de grados de los dos grafos). +`identical_graph()` es un criterio más estricto que `isomorphic()`: los dos grafos deben tener la misma lista de vértices y aristas, +exactamente en el mismo orden, con la misma direccionalidad, y los dos grafos también deben tener idénticos atributos de grafo, +vértice y arista. ## Establecer y recuperar atributos -Además de los IDs, los vértices y aristas pueden tener *atributos* como un nombre, coordenadas para graficar, metadatos y pesos. El propio grafo también puede tener estos atributos (por ejemplo, un nombre, que se mostrará en `summary`). En cierto sentido, cada grafo, vértice y arista puede ser utilizado como un espacio de nombres en R para almacenar y recuperar estos atributos. +Además de los IDs, los vértices y aristas pueden tener *atributos* como un nombre, coordenadas para graficar, metadatos y pesos. +El propio grafo también puede tener estos atributos (por ejemplo, un nombre, que se mostrará en `summary`). +En cierto sentido, cada grafo, +vértice y arista puede ser utilizado como un espacio de nombres en R para almacenar y recuperar estos atributos. Para demostrar el uso de los atributos, creemos una red social sencilla: @@ -262,7 +324,10 @@ g <- make_graph( ) ``` -Cada vértice representa a una persona, por lo que queremos almacenar sus edades, géneros y el tipo de conexión entre dos personas (`is_formal()` se refiere a si una conexión entre una persona y otra es formal o informal, es decir, colegas o amigos). El operador `$` es un atajo para obtener y establecer atributos de un grafo. Es más corto y tan legible como `graph_attr()` y `set_graph_attr()`. +Cada vértice representa a una persona, por lo que queremos almacenar sus edades, +géneros y el tipo de conexión entre dos personas (`is_formal()` se refiere a si una conexión entre una persona y otra es formal o informal, es decir, colegas o amigos). +El operador `$` es un atajo para obtener y establecer atributos de un grafo. +Es más corto y tan legible como `graph_attr()` y `set_graph_attr()`. ```{r echo = TRUE} V(g)$age <- c(25, 31, 18, 23, 47, 22, 50) @@ -271,7 +336,9 @@ E(g)$is_formal <- c(FALSE, FALSE, TRUE, TRUE, TRUE, FALSE, TRUE, FALSE, FALSE) summary(g) ``` -`V` y `E` son la forma estándar de obtener una secuencia de todos los vértices y aristas respectivamente. Esto asigna un atributo a *todos* los vértices/aristas a la vez. Otra forma de generar nuestra red social es con el uso de `set_vertex_attr()` y `set_edge_attr()` y el operador `%>%`: +`V` y `E` son la forma estándar de obtener una secuencia de todos los vértices y aristas respectivamente. +Esto asigna un atributo a *todos* los vértices/aristas a la vez. +Otra forma de generar nuestra red social es con el uso de `set_vertex_attr()` y `set_edge_attr()` y el operador `%>%`: ```{r echo = TRUE, eval=FALSE} g <- make_graph( @@ -294,14 +361,17 @@ E(g)$is_formal[1] <- TRUE E(g)$is_formal ``` -Los valores de los atributos pueden establecerse en cualquier objeto de R, pero ten en cuenta que almacenar el grafo en algunos formatos puede provocar la pérdida de valores en atributos complejos. Los vértices, las aristas y el propio grafo pueden utilizarse para establecer atributos, por ejemplo, para añadir una fecha al grafo: +Los valores de los atributos pueden establecerse en cualquier objeto de R, +pero ten en cuenta que almacenar el grafo en algunos formatos puede provocar la pérdida de valores en atributos complejos. +Los vértices, las aristas y el propio grafo pueden utilizarse para establecer atributos, por ejemplo, para añadir una fecha al grafo: ```{r echo = TRUE} g$date <- c("2022-02-11") graph_attr(g, "date") ``` -Para recuperar atributos, también puedes utilizar `graph_attr()`, `vertex_attr()` y `edge_attr()`. Para encontrar el ID de un vértice puedes utilizar la función `match()`: +Para recuperar atributos, también puedes utilizar `graph_attr()`, `vertex_attr()` y `edge_attr()`. +Para encontrar el ID de un vértice puedes utilizar la función `match()`: ```{r echo = TRUE} match(c("Ibrahim"), V(g)$name) @@ -325,15 +395,22 @@ Si quieres guardar un grafo en R con todos los atributos utiliza la función `sa ## Propiedades estructurales de los grafos -igraph proporciona un amplio conjunto de métodos para calcular varias propiedades estructurales de los grafos. Está más allá del alcance de este tutorial documentar todos ellos, por lo que esta sección sólo presentará algunos de ellos con fines ilustrativos. Trabajaremos con la pequeña red social que construimos en la sección anterior. +igraph proporciona un amplio conjunto de métodos para calcular varias propiedades estructurales de los grafos. +Está más allá del alcance de este tutorial documentar todos ellos, +por lo que esta sección sólo presentará algunos de ellos con fines ilustrativos. +Trabajaremos con la pequeña red social que construimos en la sección anterior. -Probablemente, la propiedad más sencilla en la que se puede pensar es el "grado del vértice". El grado de un vértice es igual al número de aristas incidentes a él. En el caso de los grafos dirigidos, también podemos definir el `grado de entrada` (el número de aristas que apuntan hacia el vértice) y el `grado de salida` (el número de aristas que se originan en el vértice). igraph es capaz de calcularlos todos utilizando una sintaxis sencilla: +Probablemente, la propiedad más sencilla en la que se puede pensar es el "grado del vértice". +El grado de un vértice es igual al número de aristas incidentes a él. En el caso de los grafos dirigidos, +también podemos definir el `grado de entrada` (el número de aristas que apuntan hacia el vértice) y el `grado de salida` (el número de aristas que se originan en el vértice). igraph es capaz de calcularlos todos utilizando una sintaxis sencilla: ```{r echo = TRUE} degree(g) ``` -Si el grafo fuera dirigido, podríamos calcular los grados de entrada y salida por separado utilizando `degree(mode = "in")` y `degree(mode = "out")`. También puedes pasar un único ID de un vértice o una lista de IDs de los vértices a `degree()` si quieres calcular los grados sólo para un subconjunto de vértices: +Si el grafo fuera dirigido, +podríamos calcular los grados de entrada y salida por separado utilizando `degree(mode = "in")` y `degree(mode = "out")`. +También puedes pasar un único ID de un vértice o una lista de IDs de los vértices a `degree()` si quieres calcular los grados sólo para un subconjunto de vértices: ```{r echo = TRUE} degree(g, 7) @@ -355,15 +432,24 @@ También funciona para vértices individuales: degree(g, "Bruno") ``` -De igual manera, se utiliza una sintaxis similar para la mayoría de las propiedades estructurales que igraph puede calcular. Para las propiedades de los vértices, las funciones aceptan un ID, un nombre o una lista de IDs o nombres (y si se omiten, el valor predeterminado es el conjunto de todos los vértices). Para las propiedades de aristas, las funciones aceptan un único ID o una lista de IDs. +De igual manera, se utiliza una sintaxis similar para la mayoría de las propiedades estructurales que igraph puede calcular. +Para las propiedades de los vértices, las funciones aceptan un ID, +un nombre o una lista de IDs o nombres (y si se omiten, el valor predeterminado es el conjunto de todos los vértices). +Para las propiedades de aristas, las funciones aceptan un único ID o una lista de IDs. ------------------------------------------------------------------------ -**NOTA:** Para algunas mediciones, no tiene sentido calcularlas sólo para unos pocos vértices o aristas en lugar de para todo el grafo, ya que de todas formas llevaría el mismo tiempo. En este caso, las funciones no aceptan IDs de vértices o aristas, pero se puede restringir la lista resultante utilizando operaciones estándar. Un ejemplo es la centralidad de vectores propios (`evcent()`). +**NOTA:** Para algunas mediciones, no tiene sentido calcularlas sólo para unos pocos vértices o aristas en lugar de para todo el grafo, +ya que de todas formas llevaría el mismo tiempo. +En este caso, las funciones no aceptan IDs de vértices o aristas, +pero se puede restringir la lista resultante utilizando operaciones estándar. +Un ejemplo es la centralidad de vectores propios (`evcent()`). ------------------------------------------------------------------------ -Además del grado, igraph incluye funciones integradas para calcular muchas otras propiedades de centralidad, como la intermediación de vértices y aristas (`edge_betweenness()`) o el PageRank de Google (`page_rank()`), por nombrar algunas. Aquí sólo ilustraremos la intermediación de aristas: +Además del grado, igraph incluye funciones integradas para calcular muchas otras propiedades de centralidad, +como la intermediación de vértices y aristas (`edge_betweenness()`) o el PageRank de Google (`page_rank()`), por nombrar algunas. +Aquí sólo ilustraremos la intermediación de aristas: ```{r echo = TRUE} edge_betweenness(g) @@ -380,7 +466,8 @@ as_edgelist(g)[ebs == max(ebs), ] ### Selección de vértices -Tomando como ejemplo la red social anteriormente creada, te gustaría averiguar quién tiene el mayor grado. Puedes hacerlo con las herramientas presentadas hasta ahora y con la función `which.max()`: +Tomando como ejemplo la red social anteriormente creada, te gustaría averiguar quién tiene el mayor grado. +Puedes hacerlo con las herramientas presentadas hasta ahora y con la función `which.max()`: ```{r echo = TRUE} which.max(degree(g)) @@ -412,13 +499,16 @@ Al seleccionar un vértice que no existe se produce un error: seq <- V(graph)[2, 3, 7, "foo", 3.5] ``` -Los nombres de los atributos también pueden utilizarse tal cual dentro de los operadores de indexación ("[]") de `V()` y `E()`. Esto puede combinarse con la capacidad de R de utilizar vectores booleanos para indexar y obtener expresiones muy concisas y legibles para recuperar un subconjunto del set de vértices o aristas de un grafo. Por ejemplo, el siguiente comando nos da los nombres de los individuos menores de 30 años de nuestra red social: +Los nombres de los atributos también pueden utilizarse tal cual dentro de los operadores de indexación ("[]") de `V()` y `E()`. +Esto puede combinarse con la capacidad de R de utilizar vectores booleanos para indexar y obtener expresiones muy concisas y legibles para recuperar un subconjunto del set de vértices o aristas de un grafo. +Por ejemplo, el siguiente comando nos da los nombres de los individuos menores de 30 años de nuestra red social: ```{r echo = TRUE} V(g)[age < 30]$name ``` -Por supuesto, `<` no es el único operador booleano que puede utilizarse para esto. Otras posibilidades son las siguientes: +Por supuesto, `<` no es el único operador booleano que puede utilizarse para esto. +Otras posibilidades son las siguientes: | Operador | Significado | |----------|---------------------------------------------------------------| @@ -436,7 +526,9 @@ También puede crear un operador "no incluido en" a partir de `%in%` utilizando `%notin%` <- Negate(`%in%`) ``` -Si un atributo tiene el mismo nombre que una función de igraph, debes tener cuidado ya que la sintaxis puede llegar a ser un poco confusa. Por ejemplo, si hay un atributo llamado `degree` que representa las notas de un examen para cada persona, no debe confundirse con la función de igraph que calcula los grados de los vértices de una red: +Si un atributo tiene el mismo nombre que una función de igraph, debes tener cuidado ya que la sintaxis puede llegar a ser un poco confusa. +Por ejemplo, si hay un atributo llamado `degree` que representa las notas de un examen para cada persona, +no debe confundirse con la función de igraph que calcula los grados de los vértices de una red: ```{r echo = TRUE} V(g)$degree <- c("A", "B", "B+", "A+", "C", "A", "B") @@ -449,9 +541,12 @@ V(g)$name[degree(g) == 3] ### Selección de aristas -Las aristas pueden seleccionarse basándose en atributos, igual que los vértices. Como ya se ha mencionado, la forma estándar de obtener aristas es `E`. Además, existen algunas propiedades estructurales especiales para seleccionar aristas. +Las aristas pueden seleccionarse basándose en atributos, igual que los vértices. +Como ya se ha mencionado, la forma estándar de obtener aristas es `E`. +Además, existen algunas propiedades estructurales especiales para seleccionar aristas. -El uso de `.from()` permite filtrar la serie de aristas desde los vértices de donde proceden. Por ejemplo, para seleccionar todas las aristas procedentes de Carmina (cuyo ID de vértice es el 3): +El uso de `.from()` permite filtrar la serie de aristas desde los vértices de donde proceden. +Por ejemplo, para seleccionar todas las aristas procedentes de Carmina (cuyo ID de vértice es el 3): ```{r echo = TRUE, warning = FALSE} E(g)[.from(3)] @@ -463,15 +558,24 @@ Por supuesto, también funciona con nombres de vértices: E(g)[.from("Carmina")] ``` -Al usar `.to()`, se filtran la serie de aristas en función de los vértices de destino o diana. Esto es diferente de `.from()` si el grafo es dirigido, mientras que da la misma respuesta para grafos no dirigidos. Con `.inc()` sólo se seleccionan las aristas que inciden en un único vértice o en al menos uno de los vértices, independientemente de la dirección de las aristas. +Al usar `.to()`, se filtran la serie de aristas en función de los vértices de destino o diana. +Esto es diferente de `.from()` si el grafo es dirigido, mientras que da la misma respuesta para grafos no dirigidos. +Con `.inc()` sólo se seleccionan las aristas que inciden en un único vértice o en al menos uno de los vértices, +independientemente de la dirección de las aristas. -La expresión `%--%` es un operador especial que puede utilizarse para seleccionar todas las aristas entre dos conjuntos de vértices. Ignora las direcciones de las aristas en los grafos dirigidos. Por ejemplo, la siguiente expresión selecciona todas las aristas entre Carmina (su ID de vértice es el 3), Nang (su ID de vértice es el 5) y Samira (su ID de vértice es el 6): +La expresión `%--%` es un operador especial que puede utilizarse para seleccionar todas las aristas entre dos conjuntos de vértices. +Ignora las direcciones de las aristas en los grafos dirigidos. +Por ejemplo, la siguiente expresión selecciona todas las aristas entre Carmina (su ID de vértice es el 3), +Nang (su ID de vértice es el 5) y Samira (su ID de vértice es el 6): ```{r echo = TRUE} E(g) [ 3:5 %--% 5:6 ] ``` -Para que el operador `%--%` funcione con nombres, puedes construir vectores de caracteres que contengan los nombres y luego utilizar estos vectores como operandos. Por ejemplo, para seleccionar todas las aristas que conectan a los hombres con las mujeres, podemos hacer lo siguiente, luego de volver a añadir el atributo de género que hemos eliminado anteriormente: +Para que el operador `%--%` funcione con nombres, +puedes construir vectores de caracteres que contengan los nombres y luego utilizar estos vectores como operandos. +Por ejemplo, para seleccionar todas las aristas que conectan a los hombres con las mujeres, podemos hacer lo siguiente, +luego de volver a añadir el atributo de género que hemos eliminado anteriormente: ```{r} V(g)$gender <- c("f", "m", "f", "m", "m", "f", "m") @@ -493,21 +597,31 @@ E(g)[men %--% women] ## Tratar un grafo como una matriz de adyacencia -Una matriz de adyacencia es otra manera de representar un grafo. En la matriz de adyacencia, las filas y columnas están indicadas por los vértices del grafo y los elementos de la matriz indican el número de aristas entre los vértices *i* y *j*. La matriz de adyacencia del grafo de nuestra red social imaginaria es: +Una matriz de adyacencia es otra manera de representar un grafo. +En la matriz de adyacencia, +las filas y columnas están indicadas por los vértices del grafo y los elementos de la matriz indican el número de aristas entre los vértices *i* y *j*. +La matriz de adyacencia del grafo de nuestra red social imaginaria es: ```{r echo = TRUE} as_adjacency_matrix(g) ``` -Por ejemplo, Carmina (`1, 0, 0, 1, 1, 1, 0`) está directamente conectada con Alejandra (que tiene el índice 1), Moshe (índice 4), Nang (índice 5), Samira (índice 6) y , pero no con Bruno (índice 2) ni con Ibrahim (índice 7). +Por ejemplo, Carmina (`1, 0, 0, 1, 1, 1, 0`) está directamente conectada con Alejandra (que tiene el índice 1), Moshe (índice 4), +Nang (índice 5), Samira (índice 6) y , pero no con Bruno (índice 2) ni con Ibrahim (índice 7). ## Diseños y graficación -Un grafo es un objeto matemático abstracto sin una representación específica en el espacio 2D, 3D o cualquier espacio geométrico. Esto significa que, cuando queremos visualizar un grafo, primero tenemos que encontrar una correspondencia entre los vértices y las coordenadas en un espacio bidimensional o tridimensional, preferiblemente de una manera útil y/o agradable a la vista. Una rama separada de la teoría de grafos, denominada dibujo de grafos, trata de resolver este problema mediante varios algoritmos de diseño de grafos. igraph implementa varios algoritmos de diseño y también es capaz de dibujarlos en la pantalla o en cualquier formato de salida que soporte el propio R. +Un grafo es un objeto matemático abstracto sin una representación específica en el espacio 2D, 3D o cualquier espacio geométrico. +Esto significa que, cuando queremos visualizar un grafo, +primero tenemos que encontrar una correspondencia entre los vértices y las coordenadas en un espacio bidimensional o tridimensional, +preferiblemente de una manera útil y/o agradable a la vista. +Una rama separada de la teoría de grafos, denominada dibujo de grafos, +trata de resolver este problema mediante varios algoritmos de diseño de grafos. igraph implementa varios algoritmos de diseño y también es capaz de dibujarlos en la pantalla o en cualquier formato de salida que soporte el propio R. ### Algoritmos de diseño -Las funciones de diseño en igraph siempre empiezan por `layout`. La siguiente tabla las resume: +Las funciones de diseño en igraph siempre empiezan por `layout`. +La siguiente tabla las resume: | Nombre del método | Descripción del algoritmo | |-----------------|-------------------------------------------------------| @@ -521,13 +635,17 @@ Las funciones de diseño en igraph siempre empiezan por `layout`. La siguiente t | `layout_as_tree` | Diseño de árbol de Reingold-Tilford, útil para grafos (casi) arbóreos | | `layout_nicely` | Algoritmo de diseño que elige automáticamente uno de los otros algoritmos en función de determinadas propiedades del grafo | -Los algoritmos de diseño pueden ejecutarse directamente con un grafo como primer argumento. Devolverán una matriz con dos columnas y tantas filas como número de vértices del grafo; cada fila corresponderá a la posición de un único vértice, ordenado según el ID del vértice. Algunos algoritmos tienen una variante 3D; en este caso devuelven tres columnas en lugar de 2. +Los algoritmos de diseño pueden ejecutarse directamente con un grafo como primer argumento. +Devolverán una matriz con dos columnas y tantas filas como número de vértices del grafo; +cada fila corresponderá a la posición de un único vértice, ordenado según el ID del vértice. +Algunos algoritmos tienen una variante 3D; en este caso devuelven tres columnas en lugar de 2. ```{r} layout <- layout_with_kk(g) ``` -Algunos algoritmos de diseño toman argumentos adicionales; por ejemplo, cuando se diseña un grafo con la forma de un árbol, puede tener sentido especificar qué vértice debe colocarse en la raíz del diseño: +Algunos algoritmos de diseño toman argumentos adicionales; por ejemplo, cuando se diseña un grafo con la forma de un árbol, +puede tener sentido especificar qué vértice debe colocarse en la raíz del diseño: ```{r} layout <- layout_as_tree(g, root = 2) @@ -545,9 +663,12 @@ layout <- layout_with_kk(g) plot(g, layout = layout, main = "Red social con el algoritmo de diseño Kamada-Kawai") ``` -Esto debería abrir una nueva ventana mostrando una representación visual de la red. Recuerda que la ubicación exacta de los nodos puede ser diferente en tu máquina, ya que la disposición no es determinista. +Esto debería abrir una nueva ventana mostrando una representación visual de la red. +Recuerda que la ubicación exacta de los nodos puede ser diferente en tu máquina, ya que la disposición no es determinista. -El argumento `layout` también acepta funciones; en este caso, la función será llamada con el grafo como su primer argumento. Esto permite ingresar directamente el nombre de una función de diseño, sin tener que crear una variable de diseño, como en el ejemplo anterior: +El argumento `layout` también acepta funciones; en este caso, la función será llamada con el grafo como su primer argumento. +Esto permite ingresar directamente el nombre de una función de diseño, sin tener que crear una variable de diseño, +como en el ejemplo anterior: ```{r} plot( @@ -557,7 +678,8 @@ plot( ) ``` -Para mejorar el aspecto visual, una adición trivial sería colorear los vértices según el género. También deberíamos intentar colocar los nombres ligeramente fuera de los vértices para mejorar la legibilidad: +Para mejorar el aspecto visual, una adición trivial sería colorear los vértices según el género. +También deberíamos intentar colocar los nombres ligeramente fuera de los vértices para mejorar la legibilidad: ```{r} V(g)$color <- ifelse(V(g)$gender == "m", "yellow", "red") @@ -569,7 +691,9 @@ plot( ) ``` -También puedes tratar el atributo `gender` como un factor y proporcionar los colores como un argumento a `plot()`, que tiene prioridad sobre el atributo `color` que se asigna de manera estándar a los vértices. Los colores se asignan automáticamente: +También puedes tratar el atributo `gender` como un factor y proporcionar los colores como un argumento a `plot()`, +que tiene prioridad sobre el atributo `color` que se asigna de manera estándar a los vértices. +Los colores se asignan automáticamente: ```{r} plot( @@ -579,7 +703,9 @@ plot( vertex.color = as.factor(V(g)$gender)) ``` -Como se vio anteriormente, con el argumento `vertex.color` puedes especificar propiedades visuales para `plot` en lugar de usar y/o manipular los atributos de vértices o aristas. El siguiente gráfico muestra las relaciones formales con líneas gruesas y las informales con líneas finas: +Como se vio anteriormente, +con el argumento `vertex.color` puedes especificar propiedades visuales para `plot` en lugar de usar y/o manipular los atributos de vértices o aristas. +El siguiente gráfico muestra las relaciones formales con líneas gruesas y las informales con líneas finas: ```{r} plot( @@ -592,9 +718,12 @@ plot( ) ``` -Este último procedimiento es preferible si quieres modificar la representación visual de tu grafo, pero no quieres hacer modificaciones al grafo mismo. +Este último procedimiento es preferible si quieres modificar la representación visual de tu grafo, +pero no quieres hacer modificaciones al grafo mismo. -En resumen, hay propiedades especiales de vértices y aristas que corresponden a la representación visual del grafo. Estos atributos pueden modificar la configuración predeterminada de igraph (es decir, color, peso, nombre, forma, diseño, etc.). Las dos tablas siguientes resumen los atributos visuales más utilizados para vértices y aristas, respectivamente: +En resumen, hay propiedades especiales de vértices y aristas que corresponden a la representación visual del grafo. +Estos atributos pueden modificar la configuración predeterminada de igraph (es decir, color, peso, nombre, forma, diseño, etc.). +Las dos tablas siguientes resumen los atributos visuales más utilizados para vértices y aristas, respectivamente: ### Atributos de los vértices para graficar @@ -637,7 +766,10 @@ Estos parámetros pueden especificarse como argumentos de la función `plot` par ## igraph y el mundo exterior -Ningún módulo de grafos estaría completo sin algún tipo de funcionalidad de importación/exportación que permita al paquete comunicarse con programas y kits de herramientas externos. igraph no es una excepción: proporciona funciones para leer los formatos de grafos más comunes y para guardar grafos en archivos que obedezcan estas especificaciones de formato. Las funciones principales para leer y escribir de/a un fichero son `read_graph()` y `write_graph()`, respectivamente. La siguiente tabla resume los formatos que igraph puede leer o escribir: +Ningún módulo de grafos estaría completo sin algún tipo de funcionalidad de importación/exportación que permita al paquete comunicarse con programas y kits de herramientas externos. igraph no es una excepción: +proporciona funciones para leer los formatos de grafos más comunes y para guardar grafos en archivos que obedezcan estas especificaciones de formato. +Las funciones principales para leer y escribir de/a un fichero son `read_graph()` y `write_graph()`, respectivamente. +La siguiente tabla resume los formatos que igraph puede leer o escribir: | Formato | Nombre corto | Método de lectura | Método de escritura | |-----------------|-----------------|-------------------|-------------------| @@ -654,7 +786,8 @@ Ningún módulo de grafos estaría completo sin algún tipo de funcionalidad de ------------------------------------------------------------------------ -**NOTA:** La mayoría de los formatos tienen sus propias limitaciones; por ejemplo, no todos pueden almacenar atributos. Tu mejor opción es probablemente GraphML o GML si quieres guardar los grafos de igraph en un formato que pueda ser leído desde un paquete externo y quieres preservar los atributos numéricos y de cadena. *Edge list* y NCOL también están bien si no tienes atributos (aunque NCOL admite nombres de vértices y pesos de aristas). +**NOTA:** La mayoría de los formatos tienen sus propias limitaciones; por ejemplo, no todos pueden almacenar atributos. +Tu mejor opción es probablemente GraphML o GML si quieres guardar los grafos de igraph en un formato que pueda ser leído desde un paquete externo y quieres preservar los atributos numéricos y de cadena. *Edge list* y NCOL también están bien si no tienes atributos (aunque NCOL admite nombres de vértices y pesos de aristas). ------------------------------------------------------------------------ @@ -662,7 +795,10 @@ Ningún módulo de grafos estaría completo sin algún tipo de funcionalidad de Este tutorial es una breve introducción a `igraph` en R. Esperamos que hayas disfrutado de su lectura y que te resulte útil para tus propios análisis de redes. -Para una descripción detallada de funciones específicas, consulta . Si tienes preguntas sobre cómo utilizar `igraph`, visita nuestro [Foro](https://igraph.discourse.group). Para informar de un error, abre una [incidencia en Github](https://github.com/igraph/rigraph/issues). Por favor, no hagas preguntas de uso en Github directamente, ya que está pensado para desarrolladores y no para usuarios. +Para una descripción detallada de funciones específicas, consulta . +Si tienes preguntas sobre cómo utilizar `igraph`, visita nuestro [Foro](https://igraph.discourse.group). +Para informar de un error, abre una [incidencia en Github](https://github.com/igraph/rigraph/issues). +Por favor, no hagas preguntas de uso en Github directamente, ya que está pensado para desarrolladores y no para usuarios. ## Información de la sesión