list available EdgeStats in docs

[maximelucas]

Right now they are here https://xgi.readthedocs.io/en/latest/api/stats/xgi.stats.edgestats.html in a non-compact way.

It would be nice to have them there as a list, and in the docs of methods like filterby().

[leotrs]

Good suggestion. One problem is that stats are meant to be dynamic, in two different ways:

1. A user can add a node attribute that then becomes a NodeStat object: H.add_node(0, name="Max") leads to the creation of the NodeStat H.nodes.attrs("name").
2. A user can create their own stat function and add it to the library with the decorator @nodestat_func.

So to solve this issue I propose we add a list at the top of this page with all the hard-coded ones, but also add two new methods:

@xgi.nodestat_func
def my_degree():
    ...

# Returns all the hard-coded node stats PLUS all user-defined ones
xgi.all_nodestats()
# -> ["degree", "clustering", "my_degree"]

H = xgi.Hypergraph
H.add_node(0, name="Max")
# Returns all the stats available on H
H.nodes.all_stats()
# -> ["degree", "clustering", "my_degree", "attrs('name')", ...]

The first method returns a list of the hard-coded ones PLUS the user-defined ones. The second method would contain all the hard-coded ones PLUS the user-defined ones PLUS all the attributes in H.

I think this is the most complete list(s) of available stats. However, there would be three different lists of stats: one hard-coded on the documentation, one given by xgi.all_nodestats() and one given by H.nodes.all_stats(). And I'm not crazy about having three different lists...

What do yall think?

[leotrs]

Revisiting the above, having three different sources of truth seems overkill and generally a Big Bad Idea. So I think I'll go ahead and implement one static list in the docs, and just add the H.nodes.all_stats() function that returns everything in existence.

[thomasrobiglio]

I was thinking of addressing the docs part of this issue (idk if the plan about the all_stats() function is still actual), just to be sure to have understood the right thing:

We want to have all pre-implemented stats listed somewhere visible in the docs (maybe on this page) with a static list, right?

Also the list would be this one:

nodestats:

• average_neighbor_degree
• clique_eigenvector_centrality
• clustering_coefficient
• degree
• eigenvector_centrality
• local_clustering_coefficient
• node_edge_centrality
• two_nodes_clustering_coefficient

edgestats:

• order
• size
• node_edge_centrality

dinodestats:

• degree
• in_degree
• out_degree

diedgestat:

• order
• size
• head_order
• head_size
• tail_order
• tail_size

Let me know if I'm missing some stats and if I got correctly the point of the issue 😄

[leotrs]

@thomasrobiglio Yes, visible documentation is certainly part of this issue.

Each of nodestats, edgestats, and their directed versions each live in a different module under the stats sub-package. So the point is to document each of them AND have the list be visible. I suggest we add them to the "quick links" section of the RTD page.

[thomasrobiglio]

ok, thank you @leotrs! I will propose a way to do this sometime this week, then we can discuss the details of the appearance on the PR.

[maximelucas]

Great, thanks Thomas! I think the all_stats could also be useful.

[thomasrobiglio]

Reopening this manually:

To fully fix https://github.com/xgi-org/xgi/issues/188 I would still add two things (but they could be in another PR):

1. an all_stat() function that would list of all available stats (see this https://github.com/xgi-org/xgi/issues/188#issuecomment-1295849967)
2. list available stats when user request one that does not exist. Right now, H.nodes.test() raises AttributeError: Stat 'test' not defined. It would be nice if it could also say something like: "NodeStat must be one of ["degree", ...]"

[leotrs]

The way to unlink the PR from this issue is by removing the string "Fixes #188" from the description of the PR. Just edit the description and delete that sentence.