Deprecate hub_matrix and authority_matrix (#4617)

* Replace internal use of hub_matrix and authority_matrix.

* Simplify getting max eigenvector.

* Update hist_numpy docstring example.

Add explicit examples of hub and authority matrix.

* Add deprecation warnings.

* Add deprecation to conftest and devnotes.

* Fix typo in docstring example.

* Add bullet to release notes.

1 files changed, 50 insertions, 9 deletions

diff --git a/networkx/algorithms/link_analysis/hits_alg.py b/networkx/algorithms/link_analysis/hits_alg.py
index 19fe9bb3..7ef2d8a5 100644
--- a/networkx/algorithms/link_analysis/hits_alg.py
+++ b/networkx/algorithms/link_analysis/hits_alg.py
@@ -120,13 +120,39 @@ def hits(G, max_iter=100, tol=1.0e-8, nstart=None, normalized=True):
 
 
 def authority_matrix(G, nodelist=None):
-    """Returns the HITS authority matrix."""
+    """Returns the HITS authority matrix.
+
+    .. deprecated:: 2.6
+    """
+    import warnings
+
+    msg = (
+        "\nauthority_matrix is deprecated as of version 2.6 and will be removed "
+        "in version 3.0.\n"
+        "The authority matrix can be computed by::\n"
+        "    >>> M = nx.to_numpy_array(G, nodelist=nodelist)\n"
+        "    >>> M.T @ M"
+    )
+    warnings.warn(msg, DeprecationWarning)
     M = nx.to_numpy_array(G, nodelist=nodelist)
     return M.T @ M
 
 
 def hub_matrix(G, nodelist=None):
-    """Returns the HITS hub matrix."""
+    """Returns the HITS hub matrix.
+
+    .. deprecated:: 2.6
+    """
+    import warnings
+
+    msg = (
+        "\nhub_matrix is deprecated as of version 2.6 and will be removed "
+        "in version 3.0.\n"
+        "The hub matrix can be computed by::\n"
+        "    >>> M = nx.to_numpy_array(G, nodelist=nodelist)\n"
+        "    >>> M @ M.T"
+    )
+    warnings.warn(msg, DeprecationWarning)
     M = nx.to_numpy_array(G, nodelist=nodelist)
     return M @ M.T
 
@@ -155,7 +181,21 @@ def hits_numpy(G, normalized=True):
     Examples
     --------
     >>> G = nx.path_graph(4)
-    >>> h, a = nx.hits(G)
+
+    The `hubs` and `authorities` are given by the eigenvectors corresponding to the
+    maximum eigenvalues of the hubs_matrix and the authority_matrix, respectively.
+
+    The ``hubs`` and ``authority`` matrices are computed from the adjancency
+    matrix:
+
+    >>> adj_ary = nx.to_numpy_array(G)
+    >>> hubs_matrix = adj_ary @ adj_ary.T
+    >>> authority_matrix = adj_ary.T @ adj_ary
+
+    `hits_numpy` maps the eigenvector corresponding to the maximum eigenvalue
+    of the respective matrices to the nodes in `G`:
+
+    >>> hubs, authority = hits_numpy(G)
 
     Notes
     -----
@@ -180,14 +220,15 @@ def hits_numpy(G, normalized=True):
 
     if len(G) == 0:
         return {}, {}
-    H = nx.hub_matrix(G, list(G))
+    adj_ary = nx.to_numpy_array(G)
+    # Hub matrix
+    H = adj_ary @ adj_ary.T
     e, ev = np.linalg.eig(H)
-    m = e.argsort()[-1]  # index of maximum eigenvalue
-    h = np.array(ev[:, m]).flatten()
-    A = nx.authority_matrix(G, list(G))
+    h = ev[:, np.argmax(e)]  # eigenvector corresponding to the maximum eigenvalue
+    # Authority matrix
+    A = adj_ary.T @ adj_ary
     e, ev = np.linalg.eig(A)
-    m = e.argsort()[-1]  # index of maximum eigenvalue
-    a = np.array(ev[:, m]).flatten()
+    a = ev[:, np.argmax(e)]  # eigenvector corresponding to the maximum eigenvalue
     if normalized:
         h = h / h.sum()
         a = a / a.sum()