Merge pull request #726 from xgi-org/stats-docstring-deduplication

docs: deduplicate stats docstrings and link to algorithms (#621)

Author: leotrs

xgi/algorithms/centrality.py

@@ -39,6 +39,11 @@ def clique_eigenvector_centrality(H, tol=1e-6):
         Centrality, where keys are node IDs and values are centralities. The
         centralities are 1-normalized.
 
+    Notes
+    -----
+    Also accessible via the stats interface as
+    ``H.nodes.clique_eigenvector_centrality``.
+
     See Also
     --------
     h_eigenvector_centrality
@@ -115,6 +120,9 @@ def node_edge_centrality(
     general functions for both nodes and edges, nodes and edges may be weighted,
     and one can choose different norms for normalization.
 
+    Also accessible via the stats interface: ``H.nodes.node_edge_centrality`` for the
+    node component and ``H.edges.node_edge_centrality`` for the edge component.
+
     References
     ----------
     Node and edge nonlinear eigenvector centrality for hypergraphs,
@@ -271,6 +279,8 @@ def katz_centrality(H, cutoff=100):
     [2] The Katz-centrality of isolated nodes (no hyperedges contains them) is
     zero. The Katz-centrality of an empty hypergraph is not defined.
 
+    Also accessible via the stats interface as ``H.nodes.katz_centrality``.
+
     References
     ----------
     See https://en.wikipedia.org/wiki/Katz_centrality#Alpha_centrality (visited
@@ -320,6 +330,10 @@ def h_eigenvector_centrality(H, max_iter=100, tol=1e-6, seed=None):
         Centrality, where keys are node IDs and values are centralities. The
         centralities are 1-normalized.
 
+    Notes
+    -----
+    Also accessible via the stats interface as ``H.nodes.h_eigenvector_centrality``.
+
     See Also
     --------
     clique_eigenvector_centrality
@@ -409,6 +423,10 @@ def z_eigenvector_centrality(H, max_iter=100, tol=1e-6):
     XGIError
         If the hypergraph is not uniform.
 
+    Notes
+    -----
+    Also accessible via the stats interface as ``H.nodes.z_eigenvector_centrality``.
+
     See Also
     --------
     clique_eigenvector_centrality

xgi/algorithms/clustering.py

@@ -42,6 +42,8 @@ def clustering_coefficient(H):
     to 0 in these cases. For more discussion, see
     https://arxiv.org/abs/0802.2512
 
+    Also accessible via the stats interface as ``H.nodes.clustering_coefficient``.
+
     See Also
     --------
     local_clustering_coefficient
@@ -99,6 +101,9 @@ def local_clustering_coefficient(H):
     to 0 in these cases. For more discussion, see
     https://arxiv.org/abs/0802.2512
 
+    Also accessible via the stats interface as
+    ``H.nodes.local_clustering_coefficient``.
+
     See Also
     --------
     clustering_coefficient
@@ -191,6 +196,9 @@ def two_node_clustering_coefficient(H, kind="union"):
     to 0 in these cases. For more discussion, see
     https://arxiv.org/abs/0802.2512
 
+    Also accessible via the stats interface as
+    ``H.nodes.two_node_clustering_coefficient``.
+
     See Also
     --------
     clustering_coefficient

xgi/stats/edgestats.py

@@ -191,51 +191,27 @@ def node_edge_centrality(
     max_iter=100,
     tol=1e-6,
 ):
-    """Computes edge centralities.
+    """Edge component of the nonlinear node-edge centrality.
+
+    See :func:`xgi.algorithms.centrality.node_edge_centrality` for the definition,
+    parameters, and references.
 
     Parameters
     ----------
     net : Hypergraph
-        The hypergraph of interest
+        The hypergraph of interest.
     bunch : Iterable
-        Edges in `net`
-    f : lambda function, default: x^2
-        The function f as described in Tudisco and Higham.
-        Must accept a numpy array.
-    g : lambda function, default: x^0.5
-        The function g as described in Tudisco and Higham.
-        Must accept a numpy array.
-    phi : lambda function, default: x^2
-        The function phi as described in Tudisco and Higham.
-        Must accept a numpy array.
-    psi : lambda function, default: x^0.5
-        The function psi as described in Tudisco and Higham.
-        Must accept a numpy array.
-    max_iter : int, default: 100
-        Number of iterations at which the algorithm terminates
-        if convergence is not reached.
-    tol : float > 0, default: 1e-6
-        The total allowable error in the node and edge centralities.
+        Edges in `net`.
 
     Returns
     -------
-    dict, dict
-        The edge centrality where keys are the edge IDs and values are
-        associated centralities.
-
-    Notes
-    -----
-    In the paper from which this was taken, it is more general in that it includes
-    general functions for both nodes and edges, nodes and edges may be weighted,
-    and one can choose different norms for normalization.
+    dict
+        Edge centralities.
 
-    This method does not output the node centralities even though they are computed.
+    See Also
+    --------
+    ~xgi.algorithms.centrality.node_edge_centrality
 
-    References
-    ----------
-    Node and edge nonlinear eigenvector centrality for hypergraphs,
-    Francesco Tudisco & Desmond J. Higham,
-    https://doi.org/10.1038/s42005-021-00704-2
     """
     _, c = xgi.node_edge_centrality(net, f, g, phi, psi, max_iter, tol)
     return {e: c[e] for e in c if e in bunch}