igraph
Inconsistent naming: "vertex" vs "node"
In the interest of predictability, we should ensure that the API uses "vertex" consistently and avoids "node".
Currently, "node" us used:
- Sometimes in place of
vids, see #691 - To specify the number of vertices in some graph generators, see e.g.
sample_traits_callaway()and other similar functions. Grep for@param nodes.
This issue refers specifically to the API, which should be predictable. Using both "node" and "vertex" in the documentation text is less of an issue.
I tried to gather all functions that use c("nodes", "vids", "v","vertex", "vertices","n")
My suggestion to consolidate:
- use
nfor number of nodes (scalar) - use
verticesfor subset of nodes (vector of vertex ids/names, could be a single vertex though) - use
v(orvertex) for a specific vertex (scalar, can neverf be a vector)
This would eliminate vids and nodes
@szhorvat What do you think?
library(igraph)
#>
#> Attaching package: 'igraph'
#> The following objects are masked from 'package:stats':
#>
#> decompose, spectrum
#> The following object is masked from 'package:base':
#>
#> union
fns <- ls("package:igraph")
has_arg <- function(fname, arg) {
obj <- get(fname, envir = asNamespace("igraph"))
is.function(obj) && arg %in% names(formals(obj))
}
args <- c("nodes", "vids", "v","vertex", "vertices","n","vid")
purrr:::map_dfr(
args,
function(arg) {
data.frame(
fn = fns[sapply(fns, has_arg, arg = arg)],
arg = arg
)
}
)
#> fn arg
#> 1 alpha_centrality nodes
#> 2 alpha.centrality nodes
#> 3 asymmetric.preference.game nodes
#> 4 bonpow nodes
#> 5 callaway.traits.game nodes
#> 6 centr_betw_tmax nodes
#> 7 centr_clo_tmax nodes
#> 8 centr_degree_tmax nodes
#> 9 centr_eigen_tmax nodes
#> 10 centralization.betweenness.tmax nodes
#> 11 centralization.closeness.tmax nodes
#> 12 centralization.degree.tmax nodes
#> 13 centralization.evcent.tmax nodes
#> 14 constraint nodes
#> 15 ego nodes
#> 16 ego_size nodes
#> 17 establishment.game nodes
#> 18 forest.fire.game nodes
#> 19 graph_from_graphdb nodes
#> 20 graph.graphdb nodes
#> 21 graph.neighborhood nodes
#> 22 grg.game nodes
#> 23 make_ego_graph nodes
#> 24 make_neighborhood_graph nodes
#> 25 neighborhood nodes
#> 26 neighborhood_size nodes
#> 27 neighborhood.size nodes
#> 28 power_centrality nodes
#> 29 preference.game nodes
#> 30 sample_asym_pref nodes
#> 31 sample_forestfire nodes
#> 32 sample_grg nodes
#> 33 sample_pref nodes
#> 34 sample_traits nodes
#> 35 sample_traits_callaway nodes
#> 36 adjacent.triangles vids
#> 37 betweenness.estimate vids
#> 38 closeness vids
#> 39 closeness.estimate vids
#> 40 count_triangles vids
#> 41 diversity vids
#> 42 eccentricity vids
#> 43 estimate_betweenness vids
#> 44 estimate_closeness vids
#> 45 graph.diversity vids
#> 46 graph.isoclass.subgraph vids
#> 47 graph.knn vids
#> 48 graph.strength vids
#> 49 harmonic_centrality vids
#> 50 induced_subgraph vids
#> 51 induced.subgraph vids
#> 52 knn vids
#> 53 local_efficiency vids
#> 54 page_rank vids
#> 55 page.rank vids
#> 56 similarity vids
#> 57 similarity.dice vids
#> 58 similarity.invlogweighted vids
#> 59 similarity.jaccard vids
#> 60 strength vids
#> 61 subgraph vids
#> 62 transitivity vids
#> 63 adjacent_vertices v
#> 64 betweenness v
#> 65 bibcoupling v
#> 66 cocitation v
#> 67 degree v
#> 68 delete_vertices v
#> 69 delete.vertices v
#> 70 distances v
#> 71 igraph.shape.noplot v
#> 72 incident v
#> 73 incident_edges v
#> 74 isomorphism_class v
#> 75 max_degree v
#> 76 neighbors v
#> 77 running_mean v
#> 78 running.mean v
#> 79 shape_noplot v
#> 80 shortest.paths v
#> 81 subcomponent v
#> 82 cluster_spinglass vertex
#> 83 spinglass.community vertex
#> 84 graph_from_data_frame vertices
#> 85 graph.data.frame vertices
#> 86 aging.ba.game n
#> 87 aging.barabasi.game n
#> 88 aging.prefatt.game n
#> 89 ba.game n
#> 90 barabasi.game n
#> 91 categorical_pal n
#> 92 cited.type.game n
#> 93 citing.cited.type.game n
#> 94 diverging_pal n
#> 95 erdos.renyi.game n
#> 96 graph n
#> 97 graph_from_atlas n
#> 98 graph_from_lcf n
#> 99 graph.atlas n
#> 100 graph.de.bruijn n
#> 101 graph.empty n
#> 102 graph.extended.chordal.ring n
#> 103 graph.famous n
#> 104 graph.full n
#> 105 graph.full.citation n
#> 106 graph.kautz n
#> 107 graph.lcf n
#> 108 graph.ring n
#> 109 graph.star n
#> 110 graph.tree n
#> 111 growing.random.game n
#> 112 lastcit.game n
#> 113 make_chordal_ring n
#> 114 make_de_bruijn_graph n
#> 115 make_directed_graph n
#> 116 make_empty_graph n
#> 117 make_full_citation_graph n
#> 118 make_full_graph n
#> 119 make_graph n
#> 120 make_kautz_graph n
#> 121 make_ring n
#> 122 make_star n
#> 123 make_tree n
#> 124 make_undirected_graph n
#> 125 r_pal n
#> 126 random.graph.game n
#> 127 sample_cit_cit_types n
#> 128 sample_cit_types n
#> 129 sample_correlated_gnp_pair n
#> 130 sample_dirichlet n
#> 131 sample_gnm n
#> 132 sample_gnp n
#> 133 sample_growing n
#> 134 sample_hierarchical_sbm n
#> 135 sample_last_cit n
#> 136 sample_pa n
#> 137 sample_pa_age n
#> 138 sample_sbm n
#> 139 sample_sphere_surface n
#> 140 sample_sphere_volume n
#> 141 sample_tree n
#> 142 sbm.game n
#> 143 sequential_pal n
#> 144 sample_spanning_tree vid
Created on 2025-06-25 with reprex v2.1.1
Sounds good, but I didn't think through the details. We should keep this in sync with the interface definition file at https://github.com/igraph/igraph/blob/master/interfaces/functions.yaml (i.e. update names there as well).
@ntamas, do you have any input, or objections to aggressively refactoring the interface file at the same time as fixing this in the R interface?
My suggestion is to do this for the release that is based on C/igraph 1.0, as there will unavoidably be more breaking changes there.
Sounds good to me, feel free to go ahead and update functions.yaml. Ideally, the code generator for the R interface should then use the argument names from functions.yaml directly, and so will the new Python interface.
@ntamas I'm going to eventually refactor parameter names in the C interface to match, for 1.0. Are you okay with this? This is not a breaking change in C.
There might be a few function names, those should be discussed. I don't want to cause a major disruption. I'll do this only for parameter names for now.
The goal here is to improve consistency and predictability, which is helpful for users.
Claude finished @krlmlr's task —— View job
Proposal: Standardize vertex/node parameter naming
Based on the discussion and analysis of the codebase, here's a concrete proposal for resolving the inconsistent "vertex" vs "node" naming:
Todo List
- [x] Read repository guidelines (CLAUDE.md)
- [x] Analyze current parameter naming patterns in codebase
- [x] Synthesize discussion into concrete proposal
- [x] Outline implementation strategy and phases
- [x] Consider testing and compatibility implications
Current State Analysis
I've identified the following inconsistent parameter names across the codebase:
Parameter name variations found:
-
nodes- Used in ~35 functions (e.g.,sample_traits_callaway(),sample_grg(), centralization functions) -
vids- Used in ~25 functions (e.g.,subgraph(),transitivity(),betweenness()) -
v- Used in ~25 functions (e.g.,degree(),neighbors(),distances()) -
vertex- Used in ~5 functions (e.g.,cluster_spinglass()) -
vertices- Used in ~5 functions (e.g.,graph_from_data_frame()) -
n- Used in ~50+ functions (e.g.,make_star(),sample_gnp(), graph generators)
Proposed Standardization
Following @schochastics' proposal with maintainer approval:
1. n - Number of vertices (scalar)
- Usage: For functions that specify the total number of vertices in a graph
-
Examples: Graph generators like
sample_gnp(n, p),make_star(n) -
Current: Functions already using
nodesparameter for this purpose
2. vertices - Subset of vertices (vector)
- Usage: For vertex IDs/names, can be single vertex or vector of vertices
-
Examples:
subgraph(graph, vertices),betweenness(graph, vertices) -
Current: Functions using
vids,nodes(when referring to vertex subsets)
3. v or vertex - Single specific vertex (scalar)
- Usage: For operations requiring exactly one vertex
-
Examples:
neighbors(graph, v), functions that work on one vertex only -
Current: Functions already using
vparameter
Benefits
- Predictability: Users can predict parameter names based on function purpose
- Consistency: Eliminates confusion between "vertex" and "node" terminology
- Clarity: Clear distinction between scalars (n, v) vs vectors (vertices)
- Alignment: Matches the agreed approach for C/igraph 1.0 and functions.yaml
Implementation Strategy
Phase 1: Coordinate with upstream
- Update parameter names in
functions.yaml - Ensure R interface code generator uses standardized names
- This aligns with the C/igraph 1.0 release timeline
Phase 2: Update R interface
- Rename parameters in function signatures
- Update documentation (
@paramtags) - Maintain backward compatibility through parameter matching
- Update examples and vignettes
Phase 3: Validation
- Run comprehensive tests to ensure functionality unchanged
- Check that existing code continues to work via partial parameter matching
- Update internal function calls to use new parameter names
Compatibility Considerations
Backward Compatibility:
- R's partial parameter matching will handle most existing code automatically
- Functions will continue to accept old parameter names (e.g.,
vidswill matchvertices) - No immediate breaking changes for end users
Documentation Updates:
- All
@paramdocumentation needs updating - Function examples should use new parameter names
- Help pages will reflect the standardized naming
Testing Impact:
- Existing tests should continue to pass due to parameter matching
- New tests should use standardized parameter names
- Test suite can help validate the transition
Timeline and Scope
Immediate actions:
- Coordinate with @ntamas on
functions.yamlupdates - Create parameter mapping documentation for the transition
- Begin systematic renaming starting with most problematic functions
Target for C/igraph 1.0 release:
- Complete parameter standardization
- Updated documentation
- Validated backward compatibility
This proposal addresses the core consistency issue while maintaining stability and coordinating with the broader igraph ecosystem changes planned for 1.0.
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "Published by a pub.dev verified publisher"){kind=small}