include listw2U in spdep manual R topics documented

[lanselin]

Hi Roger:
The function listw2U is currently not included in the spdep.pdf R topics documented list (Oct 14, 2022). It is included in the index and referred to in geary.test and moran.test for example, where it is included in "See Also", but there is no separate entry in the manual. Is this by design, or an oversight? In any case, it would be useful to have it included for those who do not know the manual by heart :-)
L.

[rsbivand]

?listw2U is in the lm.morantest() help page, probably because it was first used there https://r-spatial.github.io/spdep/reference/index.html. Should I move it to nb2listw()?

[lanselin]

I think it would be best as a separate entry, e.g., between listw2sn and lm.LMtests. It is indeed used in the examples for several of the tests which use initially asymmetric weights. But since it is mentioned in "See Also", I would think it warrants its own separate entry. Right now, to find that it even exists, one has to do a search on "non-symmetric", which is how I found it initially.

[rsbivand]

Since I almost always use ? or help(), the fact that function help entries are not in any sort order had not registered. I typicallly \alias{} them in the Rd file together where they came into being. I'll note that this connects to #30, but will take more time. I'd really prefer not to give each function its own page, I feel that more documentation vignettes would be useful. @angela-li would you care to comment on documentation? Should the legacy vignettes be upgraded? Since https://r-spatial.org/book/ is forthcoming, should the parts that work better in Ch 14-15 be added as links?

[lanselin]

I think this is an interesting example of different "cultures" :-) I have always felt the help system in R to be rather unhelpful and typically rely on google to find answers. Using help or ? seems to assume that one knows what the function is. For example, since I did not remember listw2U, using help(asymmetric) or ?asymmetric or even ??asymmetric does not give anything useful, but of course ?listw2U does. I discovered listw2U by searching on non-symmetric in the pdf file. I recognize your preference not to give each function its own page (I guess we may have a difference of opinion on that), but then there is an inherent inconsistency in the generated "See Also", when there is no Also to see ... Instead, maybe it should then say, use ?listw2U or help(listw2U) instead of See Also listw2U? This still would not solve the problem of not knowing where to look when one wants to make a weights matrix symmetric outside of the specific moran.test etc. contexts (i.e., my use case).

[rsbivand]

The help file structure was directly inherited from S and S-Plus and supplemented by vignettes 20 years ago. Bioconductor mandates vignettes to try to address the problem you refer to of discoverability of function names. HTML help files with (I think) MathJax may supplement the PDF document - there are also accessibility issues involved. The See also block live-links the named functions in the PDF, HTML, and pkgdown renderings for me, and should do so generally - do they not do so in your case?

I have an unpublished video about help, and why pagerank and SO can defeat web searches (the top answers are often stale and/or wrong). Should I try to make it availaable or improve it?

[lanselin]

Yes, there is a live link to the description of listw2U in lm.morantest. However, this still assumes one knows listw2U is what to look for. In my opinion discoverability remains an issue (having additional vignettes assumes one is going to look through them) and here I have a pretty fundamental disagreement with the original design of the help system: it is designed for people who already know what to look for. The help system is useless for questions like "how do I do x in R". Agreed that web searches often turn up crap, but there is an art to searching :-) and if there is a description of the function one looks for in one of the many R documentation sites, it almost always turns up in a web search.