Inconsistent naming: "vertex" vs "node"

[szhorvat]

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 Inconsistent naming of vertex selector parameters #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.

[schochastics]

I tried to gather all functions that use c("nodes", "vids", "v","vertex", "vertices","n")
My suggestion to consolidate:

• use n for number of nodes (scalar)
• use vertices for subset of nodes (vector of vertex ids/names, could be a single vertex though)
• use v (or vertex) 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}

[szhorvat]

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.

[ntamas]

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.

[szhorvat]

@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.

[krlmlr]

@claude: Can you please propose a solution based on the discussion?

[github-actions]

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

• Read repository guidelines (CLAUDE.md)
• Analyze current parameter naming patterns in codebase
• Synthesize discussion into concrete proposal
• Outline implementation strategy and phases
• 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 nodes parameter 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 v parameter

Benefits

1. Predictability: Users can predict parameter names based on function purpose
2. Consistency: Eliminates confusion between "vertex" and "node" terminology
3. Clarity: Clear distinction between scalars (n, v) vs vectors (vertices)
4. 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 (@param tags)
• 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., vids will match vertices)
• No immediate breaking changes for end users

Documentation Updates:

• All @param documentation 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:

1. Coordinate with @ntamas on functions.yaml updates
2. Create parameter mapping documentation for the transition
3. 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.

---

[ntamas]

@szhorvat

Are you okay with this?

yes, that's fine, go ahead.