docs: use "ID"/"IDs" consistently in documentation prose

AGENTS.md

@@ -78,6 +78,7 @@ pak::pak(dependencies = "Config/Needs/build")
 - Document all arguments and return values
 - Document internal functions using devtag (work in progress)
 - Link to C documentation using `@cdocs` tag: `#' @cdocs igraph_function_name`
+- Write "ID"/"IDs" (not "id"/"ids") when referring to vertex/edge IDs in documentation *prose*. Lowercase stays only where the token is code: argument names, runnable `@examples`, and spans in `` `...` `` or `\code{}`. Run `Rscript tools/check-id-casing.R` to find violations in roxygen prose.
 - Always run `devtools::document()` after updating documentation
 
 ### Naming Conventions

CONTRIBUTING.md

@@ -156,6 +156,15 @@ igraph` to update the `.Rd` files.
 
 - Links to C docs are added automatically thanks to the igraph.r2cdocs's roclet.
 
+- Write "ID"/"IDs" (not "id"/"ids") when referring to vertex or edge IDs in
+documentation prose. Lowercase stays only where the token is code: argument
+names, runnable `@examples`, and spans wrapped in `` `...` `` or `\code{}`. You
+can check roxygen prose for stray lowercase forms with:
+
+```sh
+Rscript tools/check-id-casing.R
+```
+
 ### Maintaining igraph.r2cdocs
 
 To update the data (when the C docs index has changed after a release) in https://github.com/igraph/igraph.r2cdocs/, run the script that is `data-raw`, commit the csv file and push.

R/attributes.R

@@ -1204,12 +1204,12 @@ delete_edge_attr <- function(graph, name) {
 #' 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
+#' 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.
+#' 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

R/bipartite.R

@@ -124,7 +124,7 @@ bipartite.mapping <- function(graph) {
 #'   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
+#'   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.

R/centrality.R

@@ -1399,7 +1399,7 @@ strength <- function(
 #' @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.
+#' @param vids The vertex IDs for which to calculate the measure.
 #' @return A numeric vector, its length is the number of vertices.
 #' @author Gabor Csardi \email{csardi.gabor@@gmail.com}
 #' @references Nathan Eagle, Michael Macy and Rob Claxton: Network Diversity

R/cliques.R

@@ -213,12 +213,12 @@ clique.number <- function(graph) {
 #'   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
+#' @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
+#'   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`
@@ -286,15 +286,15 @@ largest_cliques <- function(graph) {
 }
 
 #' @rdname cliques
-#' @param subset If not `NULL`, then it must be a vector of vertex ids,
+#' @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
+#'   in the file, given with the numeric IDs of its vertices, separated by
 #'   whitespace.
 #' @export
 max_cliques <- function(
@@ -534,7 +534,7 @@ weighted_clique_num <- function(graph, vertex.weights = NULL) {
 #' @return `ivs()`,
 #'   `largest_ivs()` and
 #'   `max_ivs()` return a list containing numeric
-#'   vertex ids, each list element is an independent vertex set.
+#'   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

R/cocitation.R

@@ -37,7 +37,7 @@
 #' in the future.
 #'
 #' @param graph The graph object to analyze
-#' @param v Vertex sequence or numeric vector, the vertex ids for which the
+#' @param v Vertex sequence or numeric vector, the vertex IDs for which the
 #'   cocitation or bibliographic coupling values we want to calculate. The
 #'   default is all vertices.
 #' @return A numeric matrix with `length(v)` lines and

R/cohesive.blocks.R

@@ -152,7 +152,7 @@ blockGraphs <- function(blocks, graph) {
 #'
 #' 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.
+#' 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)
@@ -163,7 +163,7 @@ blockGraphs <- function(blocks, graph) {
 #' `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
+#' 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.
 #'
@@ -208,7 +208,7 @@ blockGraphs <- function(blocks, graph) {
 #' 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.
+#' 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.
 #'
@@ -264,7 +264,7 @@ blockGraphs <- function(blocks, graph) {
 #'   them to `plot.igraph()`.  [print()] and [summary()] ignore them.
 #' @return `cohesive_blocks()` returns a `cohesiveBlocks` object.
 #'
-#'   `blocks()` returns a list of numeric vectors, containing vertex ids.
+#'   `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.

R/community.R

@@ -491,11 +491,11 @@ code.length <- function(communities) {
 #' returns the number of communities.
 #'
 #' The `sizes()` function returns the community sizes, in the order of their
-#' ids.
+#' 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
+#' 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
@@ -504,7 +504,7 @@ code.length <- function(communities) {
 #' `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.
+#' 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
@@ -514,7 +514,7 @@ code.length <- function(communities) {
 #' 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
+#' 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()`.
 #'
@@ -744,7 +744,7 @@ print.communities <- function(x, ...) {
 #'
 #' @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
+#'   numeric vector denoting the ID of the community for each vertex. It
 #'   might be `NULL` for hierarchical community structures.
 #' @param algorithm Character string, the algorithm that generated
 #'   the community structure, it can be arbitrary.
@@ -756,7 +756,7 @@ print.communities <- function(x, ...) {
 #' @return A `communities` object.
 #'   \describe{
 #'     \item{membership}{
-#'       A numeric vector giving the community id for each vertex.
+#'       A numeric vector giving the community ID for each vertex.
 #'     }
 #'     \item{modularity}{
 #'       The modularity score of the partition.
@@ -1373,7 +1373,7 @@ community.to.membership2 <- function(merges, vcount, steps) {
 #' 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
+#' 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.
@@ -1436,7 +1436,7 @@ community.to.membership2 <- function(merges, vcount, steps) {
 #'   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`.
+#'       Numeric vector giving the IDs of the vertices in the same community as `vertex`.
 #'     }
 #'     \item{cohesion}{
 #'       The cohesion score of the result, see references.
@@ -1956,7 +1956,7 @@ cluster_walktrap <- function(
 #'   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
+#'   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
@@ -2947,7 +2947,7 @@ 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
+#'   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
@@ -3140,7 +3140,7 @@ split_join_distance <- function(comm1, comm2) {
 #'   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.
+#'   symbolic vertex IDs.
 #' @seealso [components()] and the various community finding
 #' functions.
 #' @examples
@@ -3205,7 +3205,7 @@ communities <- groups.communities
 #'
 #' @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
+#'   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.
@@ -3268,7 +3268,7 @@ contract <- function(
 #' @return A named list with two components:
 #'   \describe{
 #'     \item{membership}{
-#'       numeric vector giving the cluster id to which each vertex belongs.
+#'       numeric vector giving the cluster ID to which each vertex belongs.
 #'     }
 #'     \item{distances}{
 #'       numeric vector giving the distance of each vertex from its generator

R/components.R

@@ -290,7 +290,7 @@ bridges <- function(graph) {
 #'     }
 #'     \item{tree_edges}{
 #'       The components themselves, a list of numeric vectors.
-#'       Each vector is a set of edge ids giving the edges in a biconnected component.
+#'       Each vector is a set of edge IDs giving the edges in a biconnected component.
 #'       These edges define a spanning tree of the component.
 #'     }
 #'     \item{component_edges}{

R/conversion.R

@@ -346,7 +346,7 @@ get.adjacency.sparse <- function(
 #'   numeric. If the `sparse` argument is `FALSE`, then character is
 #'   also allowed. The reason for the difference is that the `Matrix`
 #'   package does not support character sparse matrices yet.
-#' @param edges `r lifecycle::badge("deprecated")` Logical scalar, whether to return the edge ids in the matrix.
+#' @param edges `r lifecycle::badge("deprecated")` Logical scalar, whether to return the edge IDs in the matrix.
 #'   For non-existant edges zero is returned.
 #' @param names Logical constant, whether to assign row and column names
 #'   to the matrix. These are only assigned if the `name` vertex attribute
@@ -433,7 +433,7 @@ as_adj <- function(
 #' @param graph The graph to convert.
 #' @param names Whether to return a character matrix containing vertex
 #'   names (i.e. the `name` vertex attribute) if they exist or numeric
-#'   vertex ids.
+#'   vertex IDs.
 #' @return A `ecount(graph)` by 2 numeric matrix.
 #' @seealso [graph_from_adjacency_matrix()], [read_graph()]
 #' @keywords graphs
@@ -601,12 +601,12 @@ as_undirected <- function(
 #' 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
+#' `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
+#' IDs of adjacent edges (according to the `mode` argument) of all
 #' vertices.
 #'
 #' @param graph The input graph.
@@ -808,7 +808,7 @@ graph_from_graphnel <- function(
 #' `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
+#' vertex names in the graphNEL graph. Otherwise numeric igraph vertex IDs
 #' will be used for this purpose.
 #'
 #' @param graph An igraph graph object.
@@ -1070,7 +1070,7 @@ get.incidence.sparse <- function(
 #' @param names Logical scalar, 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.
+#'   the IDs of the vertices are used as row and column names.
 #' @param sparse Logical scalar, if it is `TRUE` then a sparse matrix is
 #'   created, you will need the `Matrix` package for this.
 #' @return A sparse or dense matrix.
@@ -1254,8 +1254,8 @@ graph_from_adj_list <- function(
 #' 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.
+#' 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.
@@ -1488,14 +1488,14 @@ graph.data.frame <- function(d, directed = TRUE, vertices = NULL) {
 #' 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.
+#' 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.
+#' 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.
+#' 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`.
@@ -1639,9 +1639,9 @@ from_data_frame <- function(...) constructor_spec(graph_from_data_frame, ...)
 #'
 #' `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
+#' 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
+#' names and a vertex ID will be assigned to each name, and also a
 #' `name` vertex attribute will be added.
 #'
 #' @concept Edge list

R/cycles.R

@@ -36,7 +36,7 @@
 #'   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.
+#'   vertex IDs.
 #' @keywords graphs
 #' @examples
 #'