Make sure that `weights=NA` is documented

[szhorvat]

In igraph, the weights function parameter typically takes the following values:

• A vector of edge weights
• NULL means: use the weight attribute automatically if present
• NA means: do not use weights at all, regardless of attributes

This is documented for some, but not all functions. For example, it is not documented for betweenness and closeness.

It is causing confusion for users. See this SO question with an incorrect and highly voted answer: https://stackoverflow.com/q/16129233/695132

This issue is to:

• review which doc pages lack this information and add it
• think about a central location where this could be explained; add it to the tutorial?
• check which functions do not follow this convention and point this out very clearly in their documentation; an example is modularity()

CC @maelle

[maelle]

To me the first step is deciding which of the functions with the argument can share the same text for the argument, which we would do with documentation inheritance. If there are some specificities that are not too important, they could be documented under Details. There could be two versions of the text, one for the functions that support weights=NA, one for the others.

Could you help me fill the table below? Then I can edit the roxygen2 source (note that some of these functions are the deprecated ones so they inherit param definitions from the non deprecated ones, feel free to ignore them!)

library(igraph)
#> 
#> Attaching package: 'igraph'
#> The following objects are masked from 'package:stats':
#> 
#>     decompose, spectrum
#> The following object is masked from 'package:base':
#> 
#>     union
library(tidyverse)

# https://seankross.com/2021/02/25/Analyzing-R-Function-Arguments.html
args_data <- tibble(Package = "package:igraph") %>% 
  mutate(Function = list(lsf.str(Package))) %>% 
  unnest(Function) %>% 
  mutate(Function = as.character(Function)) %>% 
  mutate(Arg = map(Function, 
                   compose(args, as.list, names, ~ keep(.x, nzchar), .dir = "forward")
  )) %>% 
  unnest(Arg, keep_empty = TRUE)

dplyr::filter(args_data, Arg == "weights") |>
  dplyr::mutate(deprecated = grepl("\\.", Function)) |>
  dplyr::mutate(arg_def = "") |>
  dplyr::mutate(notes = "") |>
  dplyr::arrange(deprecated) |>
  knitr::kable()

Package	Function	Arg	deprecated	arg_def	notes
package:igraph	all_shortest_paths	weights	FALSE
package:igraph	alpha_centrality	weights	FALSE
package:igraph	authority_score	weights	FALSE
package:igraph	average_local_efficiency	weights	FALSE
package:igraph	betweenness	weights	FALSE
package:igraph	closeness	weights	FALSE
package:igraph	cluster_edge_betweenness	weights	FALSE
package:igraph	cluster_fast_greedy	weights	FALSE
package:igraph	cluster_label_prop	weights	FALSE
package:igraph	cluster_leading_eigen	weights	FALSE
package:igraph	cluster_leiden	weights	FALSE
package:igraph	cluster_louvain	weights	FALSE
package:igraph	cluster_optimal	weights	FALSE
package:igraph	cluster_spinglass	weights	FALSE
package:igraph	cluster_walktrap	weights	FALSE
package:igraph	constraint	weights	FALSE
package:igraph	diameter	weights	FALSE
package:igraph	distances	weights	FALSE
package:igraph	diversity	weights	FALSE
package:igraph	eccentricity	weights	FALSE
package:igraph	edge_betweenness	weights	FALSE
package:igraph	eigen_centrality	weights	FALSE
package:igraph	embed_adjacency_matrix	weights	FALSE
package:igraph	embed_laplacian_matrix	weights	FALSE
package:igraph	estimate_betweenness	weights	FALSE
package:igraph	estimate_closeness	weights	FALSE
package:igraph	estimate_edge_betweenness	weights	FALSE
package:igraph	evcent	weights	FALSE
package:igraph	farthest_vertices	weights	FALSE
package:igraph	feedback_arc_set	weights	FALSE
package:igraph	get_diameter	weights	FALSE
package:igraph	global_efficiency	weights	FALSE
package:igraph	graph_center	weights	FALSE
package:igraph	graphlet_basis	weights	FALSE
package:igraph	graphlet_proj	weights	FALSE
package:igraph	graphlets	weights	FALSE
package:igraph	harmonic_centrality	weights	FALSE
package:igraph	hits_scores	weights	FALSE
package:igraph	hub_score	weights	FALSE
package:igraph	k_shortest_paths	weights	FALSE
package:igraph	knn	weights	FALSE
package:igraph	laplacian_matrix	weights	FALSE
package:igraph	layout_with_drl	weights	FALSE
package:igraph	layout_with_fr	weights	FALSE
package:igraph	layout_with_kk	weights	FALSE
package:igraph	layout_with_sugiyama	weights	FALSE
package:igraph	local_efficiency	weights	FALSE
package:igraph	max_bipartite_match	weights	FALSE
package:igraph	mean_distance	weights	FALSE
package:igraph	modularity_matrix	weights	FALSE
package:igraph	mst	weights	FALSE
package:igraph	page_rank	weights	FALSE
package:igraph	radius	weights	FALSE
package:igraph	random_edge_walk	weights	FALSE
package:igraph	random_walk	weights	FALSE
package:igraph	shortest_paths	weights	FALSE
package:igraph	strength	weights	FALSE
package:igraph	transitivity	weights	FALSE
package:igraph	voronoi_cells	weights	FALSE
package:igraph	alpha.centrality	weights	TRUE
package:igraph	authority.score	weights	TRUE
package:igraph	average.path.length	weights	TRUE
package:igraph	betweenness.estimate	weights	TRUE
package:igraph	closeness.estimate	weights	TRUE
package:igraph	edge.betweenness	weights	TRUE
package:igraph	edge.betweenness.community	weights	TRUE
package:igraph	edge.betweenness.estimate	weights	TRUE
package:igraph	farthest.nodes	weights	TRUE
package:igraph	fastgreedy.community	weights	TRUE
package:igraph	get.all.shortest.paths	weights	TRUE
package:igraph	get.diameter	weights	TRUE
package:igraph	get.shortest.paths	weights	TRUE
package:igraph	graph.diversity	weights	TRUE
package:igraph	graph.knn	weights	TRUE
package:igraph	graph.laplacian	weights	TRUE
package:igraph	graph.strength	weights	TRUE
package:igraph	graphlets.candidate.basis	weights	TRUE
package:igraph	graphlets.project	weights	TRUE
package:igraph	hub.score	weights	TRUE
package:igraph	label.propagation.community	weights	TRUE
package:igraph	layout.drl	weights	TRUE
package:igraph	layout.sugiyama	weights	TRUE
package:igraph	leading.eigenvector.community	weights	TRUE
package:igraph	maximum.bipartite.matching	weights	TRUE
package:igraph	minimum.spanning.tree	weights	TRUE
package:igraph	mod.matrix	weights	TRUE
package:igraph	multilevel.community	weights	TRUE
package:igraph	optimal.community	weights	TRUE
package:igraph	page.rank	weights	TRUE
package:igraph	shortest.paths	weights	TRUE
package:igraph	spinglass.community	weights	TRUE
package:igraph	walktrap.community	weights	TRUE

^{Created on 2025-04-09 with reprex v2.1.1}

[maelle]

For "arg_def" you could say "option 1" and "option 2" and define option 1 and 2 outside of the table. it could be some of the existing text in the current docs.

[maelle]

The tutorial doesn't have an example with weights. Maybe there could be a new example, or a small vignette about weights specifically? @schochastics what do you think?

[schochastics]

Yes weights need attention in examples/vignettes. But I would rather make it a subsection in the regular vignette than a standalone weight vignette. So a topic x has a subsection on weights rather than the topic weights has a subsection x

[szhorvat]

There could be two versions of the text, one for the functions that support weights=NA, one for the others.

Only two is absolutely not sufficient. The interpretation of weights is different for different functions.

IMO the text should only be shared between related functions, not otherwise.

Restrictions on accepted weight values also differ, sometimes even between related functions (e.g. is NaN excluded? weight must be positive? non-negative? Infinities allowed?)

[maelle]

Then, reading the current definitions, how do I judge whether they are good enough? Is it something I can see in the R code? Sorry to be so helpless. 😅

[szhorvat]

No, this cannot be seen in the R code. One must understand what the function does. The descriptions in the C docs are mostly decent, and can be used as a reference.

From the top of my head:

• A major distinction is between weights that are interpreted as lengths (and used in functions that compute measures based on the concept of path length, such as diameter, betweenness, efficiency, etc.), vs connection strength. The latter is usually treated in a way that's loosely equivalent to edge multiplicity. Examples include strength, modularity and modularity-based community detection, PageRank, eigenvector centrality, assortativity, etc. We could say something like "weights of parallel edges are effectively added up", but even this phrasing could prove to be confusing or insufficient in some contexts. Furthermore, this interpretation does not always apply, layout functions being a major example. With FR, larger weights indicate stronger connections, but the weights of parallel edges do not add up. With KK, larger weights indicate weaker/longer connections, but this doesn't map directly to the distance at which vertices are drawn (even though shortest path calculations are used internally). Then there are functions where it makes no sense to discuss whether larger weights indicate stronger/weaker connections, such as mst.
• Restrictions on values vary between functions. It's acceptable not to point out all restrictions, but it is not acceptable to include invalid information. If the restrictions are spelt out, then it's important to distinguish non-negative from positive—these are not the same thing.

Sharing the docs between related functions is a good idea, but trying to push sharing between too many functions is IMO too risky and will lead to even higher user confusion about these topics than we already have.

This is one of those cases when over-automation is counter-productive. The focus should be on scientific correctness first, and this simply requires giving individual attention to most functions. There is just no way around this. This way igraph, as well as other truly scientific packages, are different from packages that software developers are used to, where function signatures and type information already tell you most of what you need to know.

If you make a google doc with a list of functions, I can sort a few into small groups which I think can probably share doc text, but this will still leave many out, and there will be many groups.

[szhorvat]

@maelle Is there any way to share partial text? Just bring in a single phrase instead of the whole paragraph describing the parameter?

[szhorvat]

I was looking at some specific examples (and just fixed one), but the more I look, the more difficult it seems to share docs. I thought that hits_scores(), eigen_centrality() could share docs, but reading through the existing documentation, there are little issues that I notice: the warning about directed graphs and negative weights only applies to eigen_centrality() and not hits_scores(). One could argue to include this information in the description, but that would be a drop in the documentation quality because users are just less likely to look at that section when they are thinking about weights ... it's better to have weight-related information under weights.

How much we want to trade documentation quality for convenience is a decision to be made.

It is certainly true that the currently used phrasings are often not very nice, sometimes not even grammatical. Sharing more would make them look prettier, but wouldn't necessarily make them more informative.

(On the other hand, I just fixed a copy-paste error in the docs of hits_scores() ...)

[schochastics]

@maelle happy to help you here. I have some questions myself regarding the weights anyway. We can maybe set up a google doc to better discuss partial texts

[maelle]

To share partial text I think we could define an internal function that outputs the text.

weaker_weights_rd <- function() {
  "the weaker the weight bla"
}

@param weights blabla `r weaker_weights_rd()`

Like when we have badges r lifecycle::badge("deprecated").

[maelle]

I'll update this thread when the doc is ready (a table with function name and weight definition, where the latter column is what we want to fill in).