xgi
xgi copied to clipboard
stats features are hard to find and understand from docs
If a new user starts looking H.nodes.degree they will have a hard time finding it in the docs:
- if they look for it in classes,
Hypergraph.pydoesn't say anything about stats and has no pointers: https://xgi.readthedocs.io/en/latest/api/classes/xgi.classes.hypergraph.Hypergraph.html#xgi.classes.hypergraph.Hypergraph.edges - if they know to look in the stats packages (how would they?), they might end up here: https://xgi.readthedocs.io/en/latest/api/stats.html, which clearly contains more info. But the new user has to make a conceptual jump by understanding that information about
H.nodes.degreeis actually described inxgi.stats.nodestats.degree(H), which looks pretty different. And there is no example to make that particular link explicit (there are somewhere else above on the page).
I'm not sure how yet, but I'm realising we might need to make the link between these things much more explicit for new users. So far, the best "explanation" of how stats work and what they are is probably the tutorial.
Originally posted by @maximelucas in https://github.com/xgi-org/xgi/issues/202#issuecomment-1297023988
Further discussion on this can be found in #202.
I think we kind of agreed (https://github.com/xgi-org/xgi/pull/202#issuecomment-1297309094) that the final solution should:
- the docs of H.nodes and H.edges should mention the stats and point to the relevant documentation (maybe the stats package?).
- the stats package documentation page should explicitly mention the equivalence. the docs of H.degree (and other stats) should at least point to the docs of H.nodes.degree (which it now does)
- but then the docs of H.nodes.degree should be explicit, mention the equivalence with the stats package syntax, and be findable also online.
If there is a way to solve the last point without writing the docstrings twice, great. If not, I suggest we write it twice (at least for now).
Leo suggested concrete of implementing this in this https://github.com/xgi-org/xgi/pull/202#issuecomment-1298113259
Bumping this up after our conversation today.