Skip to content

docs: Break lines at meaning boundaries #2903

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
krlmlr wants to merge 4 commits into from
Open

docs: Break lines at meaning boundaries #2903

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
51f3b83
docs: Break lines at meaning boundaries
krlmlr Sep 13, 2026
041a7ab
docs: Start every broken sentence on its own line
krlmlr Sep 13, 2026
126e3cf
docs: Break the joined sentences apart
krlmlr Sep 13, 2026
cbaf9c0
chore: Auto-update from GitHub Actions
krlmlr Sep 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
80 changes: 33 additions & 47 deletions R/adjacency.R
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
#'
Expand Down Expand Up @@ -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")))
}
Expand Down
3 changes: 1 addition & 2 deletions R/as_phylo.R
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
82 changes: 33 additions & 49 deletions R/assortativity.R
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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}
Expand All @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -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
Expand Down
Loading