Session 4. Tutorial on HITS.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Hands-on Tutorial for Link Analysis\n",
    "\n",
    "Welcome to hands-on tutorial for link analysis. \n",
    "In this tutorial, we will study several techniques for link analysis in graphs. \n",
    "This tutorial consists of four sessions, and each session will handle the following topic:\n",
    "\n",
    "* **Session 1**. Tutorial on PageRank - Part 1 (50 mins)\n",
    "* **Session 2**. Tutorial on PageRank - Part 2 (50 mins)\n",
    "* **Session 3**. Tutorial on Topic-specific PageRank (50 mins)\n",
    "* **Session 4**. Tutorial on HITS (50 mins) <<<\n",
    "\n",
    "We recommend fully understanding link analysis (or ranking) models such as PageRank, Topic-specific PageRank, and HITS before entering this tutorial since we will **NOT** explain the theoretical backgrounds on these techniques during the tutorial. \n",
    "We will mainly focus on how to implement the algorithms of those models and how to rank nodes in real-world graphs using those ranking models. \n",
    "\n",
    "The main contributor of this meterial is as follows:\n",
    "\n",
    "* Jinhong Jung (jinhongjung@snu.ac.kr)\n",
    "\n",
    "------"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Session 4. Tutorial on HITS (50 mins)\n",
    "In this session, we will explore how to implement HITS in Python. \n",
    "The main goals of this session are summarized as follows:\n",
    "* **Goal 1.** How to implement HITS based on sparse matrices using `numpy` and `scipy` in Python\n",
    "* **Goal 2.** To perform a qualitative analysis of the ranking result from HITS in real-world networks\n",
    "\n",
    "The outline of this session is as follows:\n",
    "* **Step 1.** Review HITS algorithm\n",
    "* **Step 2.** Implement HITS algorithm - the sparse matrix version\n",
    "* **Step 3.** Validate your HITS implementation\n",
    "* **Step 4.** Qualitative analysis of the ranking result from HITS\n",
    "* **Step 5.** Comparison between PageRank and HITS\n",
    "------"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 1. Review HITS algorithm\n",
    "\n",
    "In this step, we will briefly review HITS algorithm which is another global node ranking model in graphs. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Step 1-1. Mathematical definition of HITS\n",
    "Given an adjacency matrix of a graph, HITS computes the hub and authority score vectors which can be used for ranking nodes in the graph. \n",
    "\n",
    "##### Problem definition of HITS\n",
    "* **Input**: adjacency matrix $\\mathbf{A}\\in \\mathbb{R}^{n \\times n}$ of a graph $G=(V, E)$\n",
    "* **Output**: hub score vector $\\mathbf{h} \\in \\mathbb{R}^{n}$, and authority score vector $\\mathbf{a} \\in \\mathbb{R}^{n}$ such that\n",
    "\n",
    "    - $\\mathbf{h} = \\mathbf{A}\\mathbf{a}$\n",
    "    - $\\mathbf{a} = \\mathbf{A}^{\\top}\\mathbf{h}$\n",
    "\n",
    "* The above equations are called the equations for HITS.\n",
    "\n",
    "Note that HITS does not require the row-normalized adjacency matrix. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Step 1-2. Iterative Algorithm for HITS\n",
    "The hub and authority score vectors, $\\mathbf{h}$ and $\\mathbf{a}$, are obtained by iteratively computing the equations for HITS.   \n",
    "Note that for each iteration, we need to L2-normalize the vectors $\\mathbf{h}$ and $\\mathbf{a}$.\n",
    "The following pseudo-code represents the iterative algorithm for HITS. \n",
    "\n",
    "<img src=\"./images/iterative-algorithm-hits.png\" width=\"400\">\n",
    "\n",
    "We will implement the iterative algorithm in Python. \n",
    "\n",
    "------"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 2. Implement HITS algorithm - the sparse matrix version\n",
    "We are going to implement the sparse matrix version of HITS algorithm in Python."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Step 2-1. Set up requirements for this tutorial\n",
    "\n",
    "As in the previous sessions, we first import required packages as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "try:\n",
    "    import numpy\n",
    "except ImportError:\n",
    "    print(\"numpy is not installed, type pip install numpy\")\n",
    "\n",
    "try:\n",
    "    import scipy\n",
    "except ImportError:\n",
    "    print(\"scipy is not installed, type pip install scipy\")\n",
    "    \n",
    "try:\n",
    "    import matplotlib\n",
    "except ImportError:\n",
    "    print(\"matplotlib is not installed, type pip install matplotlib\")\n",
    "    \n",
    "try:\n",
    "    import pandas\n",
    "except ImportError:\n",
    "    print(\"pandas is not installed, type pip install pandas\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Step 2-2. Implement the phase for loading the graph dataset\n",
    "In this step, we will implement the phase for loading the graph dataset of the sparse matrix version of HITS. \n",
    "We first need to import the following packages for this. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "# the below commands restrict the number of computation threads to 1\n",
    "import os\n",
    "os.environ[\"MKL_NUM_THREADS\"] = \"1\" \n",
    "os.environ[\"NUMEXPR_NUM_THREADS\"] = \"1\" \n",
    "os.environ[\"OMP_NUM_THREADS\"] = \"1\" \n",
    "\n",
    "import numpy as np\n",
    "from scipy.sparse import csr_matrix, find\n",
    "import pandas as pd"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As in the previous sessions, we implement the following function for load graph datasets.\n",
    "Note that we do not need to modify the function since the functionality in the version is the same with that of Session 3. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "class SparseHITS:\n",
    "    def load_graph_dataset(self, data_home, is_undirected=False):\n",
    "        '''\n",
    "        Load the graph dataset from the given directory (data_home)\n",
    "\n",
    "        inputs:\n",
    "            data_home: string\n",
    "                directory path conatining a dataset (edges.tsv, node_labels.tsv)\n",
    "            is_undirected: bool\n",
    "                if the graph is undirected\n",
    "        '''\n",
    "        # Step 1. self file paths from data_home\n",
    "        edge_path = \"{}/edges.tsv\".format(data_home)\n",
    "        \n",
    "        # Step 2. read the list of edges from edge_path\n",
    "        edges = np.loadtxt(edge_path, dtype=int)\n",
    "        n = int(np.amax(edges[:, 0:2])) + 1\n",
    "        \n",
    "        # Step 3. convert the edge list to the weighted adjacency matrix\n",
    "        rows = edges[:, 0]\n",
    "        cols = edges[:, 1]\n",
    "        weights = edges[:, 2]\n",
    "        self.A = csr_matrix((weights, (rows, cols)), shape=(n, n), dtype=float)\n",
    "        if is_undirected == True:\n",
    "            self.A = self.A + self.A.T\n",
    "        self.AT = self.A.T\n",
    "                \n",
    "        # Step 4. set n (# of nodes) and m (# of edges)\n",
    "        self.n = self.A.shape[0]     # number of nodes\n",
    "        self.m = self.A.nnz          # number of edges"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "class SparseHITS(SparseHITS):\n",
    "    def load_node_labels(self, data_home):\n",
    "        '''\n",
    "        Load the node labels from the given directory (data_home)\n",
    "\n",
    "        inputs:\n",
    "            data_home: string\n",
    "                directory path conatining a dataset\n",
    "        '''\n",
    "        label_path = \"{}/node_labels.tsv\".format(data_home)\n",
    "        self.node_labels = pd.read_csv(label_path, sep=\"\\t\")        "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's check if the function is correctly implemented. \n",
    "We will use the small dataset at `./data/small` as before."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The number n of nodes: 29\n",
      "The number m of edges: 376\n"
     ]
    }
   ],
   "source": [
    "hits = SparseHITS()\n",
    "hits.load_graph_dataset('./data/small', is_undirected=False)\n",
    "print(\"The number n of nodes: {}\".format(hits.n))\n",
    "print(\"The number m of edges: {}\".format(hits.m))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Step 2-3. Implement the iterative phase\n",
    "\n",
    "Contrary to PageRank, HITS does not need a normalization phase for the adjacency matrix. \n",
    "In this step, we implement the iterative phase of HITS in the following algorithm.\n",
    "\n",
    "<img src=\"./images/iterative-algorithm-hits.png\" width=\"400\">\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "class SparseHITS(SparseHITS):\n",
    "    def iterate_HITS(self, epsilon=1e-9, maxIters=100):\n",
    "        '''\n",
    "        Iterate the HITS equation to obatin the hub & authority score vectors\n",
    "        \n",
    "        inputs:\n",
    "            epsilon: float\n",
    "                the error tolerance of the iteration\n",
    "            maxIters: int\n",
    "                the maximum number of iterations\n",
    "                \n",
    "        outputs:\n",
    "            h: np.ndarray (n x 1 vector)\n",
    "                the final hub score vector\n",
    "            a: np.ndarray (n x 1 vector)\n",
    "                the final authority score vector\n",
    "            h_residuals: list\n",
    "                the list of hub residuals over the iteration\n",
    "            a_residuals: list\n",
    "                the list of authority residuals over the iteration\n",
    "\n",
    "        '''\n",
    "        old_h = np.ones(self.n)/self.n\n",
    "        old_a = np.ones(self.n)/self.n\n",
    "        h_residuals = []\n",
    "        a_residuals = []\n",
    "        \n",
    "        for t in range(maxIters):\n",
    "            h = self.A.dot(old_a)\n",
    "            a = self.AT.dot(h)\n",
    "                        \n",
    "            h = h / np.linalg.norm(h, 2)\n",
    "            a = a / np.linalg.norm(a, 2)\n",
    "            \n",
    "            h_residual = np.linalg.norm(h - old_h, 1)\n",
    "            a_residual = np.linalg.norm(a - old_a, 1)\n",
    "            h_residuals.append(h_residual)\n",
    "            a_residuals.append(a_residual)\n",
    "            old_h = h\n",
    "            old_a = a\n",
    "            \n",
    "            if h_residual < epsilon and a_residual < epsilon:\n",
    "                break\n",
    "        \n",
    "        return h, a, h_residuals, a_residuals"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's check the implementation is correctly performed. \n",
    "We will briefly check each personalized ranking result using `pandas`. \n",
    "See the following code where a seed node is given. \n",
    "Note that the given seed node should have a high ranking score. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "\n",
    "def rank_nodes(ranking_scores, topk=-1):\n",
    "    sorted_nodes = np.flipud(np.argsort(ranking_scores))\n",
    "    sorted_scores = ranking_scores[sorted_nodes]\n",
    "    ranking_results = pd.DataFrame()\n",
    "    ranking_results[\"node_id\"] = sorted_nodes\n",
    "    ranking_results[\"score\"] = sorted_scores\n",
    "    \n",
    "    return ranking_results[0:topk]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Top-5 rankings based on the hub score vector:\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>node_id</th>\n",
       "      <th>score</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>4</td>\n",
       "      <td>0.320863</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>5</td>\n",
       "      <td>0.317454</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>3</td>\n",
       "      <td>0.293383</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>2</td>\n",
       "      <td>0.224871</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>21</td>\n",
       "      <td>0.219779</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   node_id     score\n",
       "0        4  0.320863\n",
       "1        5  0.317454\n",
       "2        3  0.293383\n",
       "3        2  0.224871\n",
       "4       21  0.219779"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Top-5 rankings based on the authority score vector\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>node_id</th>\n",
       "      <th>score</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>7</td>\n",
       "      <td>0.269209</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>8</td>\n",
       "      <td>0.262543</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>10</td>\n",
       "      <td>0.260004</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>13</td>\n",
       "      <td>0.249306</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>11</td>\n",
       "      <td>0.242907</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   node_id     score\n",
       "0        7  0.269209\n",
       "1        8  0.262543\n",
       "2       10  0.260004\n",
       "3       13  0.249306\n",
       "4       11  0.242907"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "hits = SparseHITS()\n",
    "hits.load_graph_dataset('./data/small', is_undirected=False)\n",
    "h, a, _, _ = hits.iterate_HITS(epsilon=1e-9, maxIters=100)\n",
    "\n",
    "print(\"Top-5 rankings based on the hub score vector:\")\n",
    "display(rank_nodes(h, 5))\n",
    "\n",
    "print(\"Top-5 rankings based on the authority score vector\")\n",
    "display(rank_nodes(a, 5))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 3. Validate your HITS implementation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We will validate the implementation of HITS. \n",
    "Similarly to PageRank, we will check if the residuals of the iterative algorithm monotonically decrease, and compare between the exact and iterative solutions of HITS. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Step 3-1. Check if the residuals of the iterative algorithm monotonically decrease"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "plt.rcParams.update({'font.size': 13}) # set the font-size in the figure\n",
    "\n",
    "def plot_residuals(residuals, title):\n",
    "    plt.semilogy(residuals, marker='o', markersize=5)\n",
    "    plt.title(title)\n",
    "    plt.ylim(bottom=1e-10, top=1e1)\n",
    "    plt.ylabel('Residual')\n",
    "    plt.xlabel('# of iterations')\n",
    "    plt.grid(True)\n",
    "    plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's check the plot for the hub residuals first. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "hits = SparseHITS()\n",
    "hits.load_graph_dataset('./data/small', is_undirected=False)\n",
    "h, a, h_residuals, a_residuals = hits.iterate_HITS(epsilon=1e-9, maxIters=100)\n",
    "\n",
    "plot_residuals(h_residuals, 'Change of Hub Residuals from HITS')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, the following will plot the authority residuals. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "plot_residuals(a_residuals, 'Change of Authority Residuals from HITS')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you can see, those residuals monotonically decrease as the number of iteration increases. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Step 3-2. Check if the iterative solution is equal to the exact solution of HITS\n",
    "\n",
    "We can directly compute the hub ans authority score vectors of HITS as follows:\n",
    "* The hub score vector $\\mathbf{h}$ is the principle eigenvector of $\\mathbf{A}\\mathbf{A}^{\\top}$.\n",
    "* The authority score vector $\\mathbf{a}$ is the principle eigenvector of $\\mathbf{A}^{\\top}\\mathbf{A}$.\n",
    "\n",
    "The principle eigenvector of a matrix is an eigenvector of the largest eigenvalue. \n",
    "Suppose the Singular Value Decomposition (SVD) of the adjacency matrix is $\\mathbf{A}=\\mathbf{U}\\mathbf{S}\\mathbf{V}^{\\top}$. Then,\n",
    "* $\\mathbf{h}$ is the first (most left) vector of $\\mathbf{U}$. \n",
    "* $\\mathbf{a}$ is the first (most left) vector of $\\mathbf{V}$.\n",
    "\n",
    "We will not describe the detailed proofs for the above statements, but we can use them as the exact solutions for the hub and authority score vectors. \n",
    "\n",
    "We will implement the following function to compute the exact solutions. \n",
    "Note that since the adjacency matrix $\\mathbf{A}$ is a sparse matrix, we will use `svds` (sparse SVD) in `scipy`.\n",
    "* `svds`: this performs SVD on a sparse matrix\n",
    "    - https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.svds.html"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "from scipy.sparse.linalg import svds\n",
    "\n",
    "class SparseHITS(SparseHITS):\n",
    "    def compute_exact_HITS(self):\n",
    "        '''\n",
    "        Compute the exact hub & authority score vectors from the closed form\n",
    "\n",
    "        outputs:\n",
    "            h: np.ndarray (n x 1 vector)\n",
    "                the final hub score vector\n",
    "            a: np.ndarray (n x 1 vector)\n",
    "                the final authority score vector\n",
    "        '''\n",
    "        h, s, a = svds(self.A, k=1)\n",
    "        \n",
    "        h = np.asarray(h).flatten()   \n",
    "        a = np.asarray(a).flatten()\n",
    "        \n",
    "        # since SVD is not unique, h and a could be negative according to a random seed\n",
    "        # in this case, we need to make the scores non-negative and L2-normalize them out\n",
    "        h = h * np.sign(h)\n",
    "        h = h / np.linalg.norm(h, 2)\n",
    "        a = a * np.sign(a)\n",
    "        a = a / np.linalg.norm(a, 2)\n",
    "        \n",
    "        return h, a"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's check the error between the exact and iterative solutions of HITS. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Error between exact and iterative hub scores: 1.275377e-10\n",
      "Error between exact and iterative authority scores: 4.813520e-11\n"
     ]
    }
   ],
   "source": [
    "hits = SparseHITS()\n",
    "hits.load_graph_dataset('./data/small', is_undirected=False)\n",
    "h_exact, a_exact = hits.compute_exact_HITS()\n",
    "h_iter, a_iter, _, _ = hits.iterate_HITS(epsilon=1e-9, maxIters=100)\n",
    "\n",
    "h_error = np.linalg.norm(h_exact - h_iter, 1)\n",
    "print(\"Error between exact and iterative hub scores: {:e}\".format(h_error))\n",
    "\n",
    "a_error = np.linalg.norm(a_exact - a_iter, 1)\n",
    "print(\"Error between exact and iterative authority scores: {:e}\".format(a_error))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 4. Qualitative analysis of the ranking result from HITS\n",
    "\n",
    "Now, we will do a qualitative analysis of the ranking result from HITS on a real-world graph. \n",
    "For this, we first use the following code which is already implemented through the previous session. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [],
   "source": [
    "class SparseHITS(SparseHITS):\n",
    "    def rank_nodes(self, ranking_scores, topk=-1):\n",
    "        '''\n",
    "        Rank nodes in the order of given ranking scores. \n",
    "        This function reports top-k rankings. \n",
    "\n",
    "        inputs:\n",
    "            ranking_scores: np.ndarray\n",
    "                ranking score vector\n",
    "            topk: int\n",
    "                top-k ranking parameter, default is -1 indicating report all ranks\n",
    "        '''\n",
    "        sorted_nodes = np.flipud(np.argsort(ranking_scores)) # argsort in the descending order\n",
    "        sorted_scores = ranking_scores[sorted_nodes]         # sort the ranking scores\n",
    "        ranks = range(1, self.n+1) # 0~n-1\n",
    "\n",
    "        result_labels = self.node_labels.iloc[sorted_nodes][0:topk]\n",
    "        result_labels.insert(0, \"rank\", ranks[0:topk])\n",
    "        result_labels[\"score\"] = sorted_scores[0:topk]\n",
    "        result_labels.reset_index(drop = True, inplace = True)\n",
    "        return result_labels"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The dataset used in this step is *enron* at `./data/enron` which has been used in Session 2. \n",
    "Please refer to Session 2 for the detailed description for the dataset. \n",
    "\n",
    "After loading the dataset, we will compute the hub ans authority score vectors of HITS. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "data_home = './data/enron'\n",
    "hits = SparseHITS()\n",
    "hits.load_graph_dataset(data_home, is_undirected=False)\n",
    "hits.load_node_labels(data_home)\n",
    "h, a, h_residuals, a_residuals = hits.iterate_HITS(epsilon=1e-9, maxIters=100)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's check the top-10 rankings based on the hub score vector in the network. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Top-10 rankings based on the hub score vector:\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>rank</th>\n",
       "      <th>node_id</th>\n",
       "      <th>address</th>\n",
       "      <th>score</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>1</td>\n",
       "      <td>141</td>\n",
       "      <td>no.address@enron.com</td>\n",
       "      <td>0.464946</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>2</td>\n",
       "      <td>371</td>\n",
       "      <td>40enron@enron.com</td>\n",
       "      <td>0.301402</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>3</td>\n",
       "      <td>733</td>\n",
       "      <td>tana.jones@enron.com</td>\n",
       "      <td>0.155692</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>4</td>\n",
       "      <td>671</td>\n",
       "      <td>sara.shackleton@enron.com</td>\n",
       "      <td>0.135909</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>5</td>\n",
       "      <td>105</td>\n",
       "      <td>steven.kean@enron.com</td>\n",
       "      <td>0.124172</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>6</td>\n",
       "      <td>1328</td>\n",
       "      <td>mark.haedicke@enron.com</td>\n",
       "      <td>0.114921</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6</th>\n",
       "      <td>7</td>\n",
       "      <td>90</td>\n",
       "      <td>jeff.dasovich@enron.com</td>\n",
       "      <td>0.110499</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>7</th>\n",
       "      <td>8</td>\n",
       "      <td>1624</td>\n",
       "      <td>mark.taylor@enron.com</td>\n",
       "      <td>0.108638</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>8</th>\n",
       "      <td>9</td>\n",
       "      <td>2</td>\n",
       "      <td>john.lavorato@enron.com</td>\n",
       "      <td>0.107663</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>9</th>\n",
       "      <td>10</td>\n",
       "      <td>156</td>\n",
       "      <td>louise.kitchen@enron.com</td>\n",
       "      <td>0.105987</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   rank  node_id                    address     score\n",
       "0     1      141       no.address@enron.com  0.464946\n",
       "1     2      371          40enron@enron.com  0.301402\n",
       "2     3      733       tana.jones@enron.com  0.155692\n",
       "3     4      671  sara.shackleton@enron.com  0.135909\n",
       "4     5      105      steven.kean@enron.com  0.124172\n",
       "5     6     1328    mark.haedicke@enron.com  0.114921\n",
       "6     7       90    jeff.dasovich@enron.com  0.110499\n",
       "7     8     1624      mark.taylor@enron.com  0.108638\n",
       "8     9        2    john.lavorato@enron.com  0.107663\n",
       "9    10      156   louise.kitchen@enron.com  0.105987"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "print(\"Top-10 rankings based on the hub score vector:\")\n",
    "display(hits.rank_nodes(h, topk=10))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's check the top-10 rankings based on the authority score vector in the network. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Top-10 rankings based on the authority score vector:\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>rank</th>\n",
       "      <th>node_id</th>\n",
       "      <th>address</th>\n",
       "      <th>score</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>1</td>\n",
       "      <td>156</td>\n",
       "      <td>louise.kitchen@enron.com</td>\n",
       "      <td>0.196387</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>2</td>\n",
       "      <td>2</td>\n",
       "      <td>john.lavorato@enron.com</td>\n",
       "      <td>0.149168</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>3</td>\n",
       "      <td>228</td>\n",
       "      <td>greg.whalley@enron.com</td>\n",
       "      <td>0.137076</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>4</td>\n",
       "      <td>97</td>\n",
       "      <td>sally.beck@enron.com</td>\n",
       "      <td>0.126122</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>5</td>\n",
       "      <td>733</td>\n",
       "      <td>tana.jones@enron.com</td>\n",
       "      <td>0.125953</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>6</td>\n",
       "      <td>1</td>\n",
       "      <td>tim.belden@enron.com</td>\n",
       "      <td>0.120326</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6</th>\n",
       "      <td>7</td>\n",
       "      <td>1624</td>\n",
       "      <td>mark.taylor@enron.com</td>\n",
       "      <td>0.119657</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>7</th>\n",
       "      <td>8</td>\n",
       "      <td>1136</td>\n",
       "      <td>elizabeth.sager@enron.com</td>\n",
       "      <td>0.108948</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>8</th>\n",
       "      <td>9</td>\n",
       "      <td>671</td>\n",
       "      <td>sara.shackleton@enron.com</td>\n",
       "      <td>0.108918</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>9</th>\n",
       "      <td>10</td>\n",
       "      <td>136</td>\n",
       "      <td>richard.shapiro@enron.com</td>\n",
       "      <td>0.103350</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   rank  node_id                    address     score\n",
       "0     1      156   louise.kitchen@enron.com  0.196387\n",
       "1     2        2    john.lavorato@enron.com  0.149168\n",
       "2     3      228     greg.whalley@enron.com  0.137076\n",
       "3     4       97       sally.beck@enron.com  0.126122\n",
       "4     5      733       tana.jones@enron.com  0.125953\n",
       "5     6        1       tim.belden@enron.com  0.120326\n",
       "6     7     1624      mark.taylor@enron.com  0.119657\n",
       "7     8     1136  elizabeth.sager@enron.com  0.108948\n",
       "8     9      671  sara.shackleton@enron.com  0.108918\n",
       "9    10      136  richard.shapiro@enron.com  0.103350"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "print(\"Top-10 rankings based on the authority score vector:\")\n",
    "display(hits.rank_nodes(a, topk=10))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Session 4. Summary"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this session, we implemented HITS algorithm (the sparse matrix version) in Python. \n",
    "More specifically, we are able to answer the following goals now. \n",
    "\n",
    "* **Goal 1.** How to implement HITS based on sparse matrices using `numpy` and `scipy` in Python\n",
    "    - We implemented the iterative algorithm for HITS based on sparse matrices.\n",
    "* **Goal 2.** To perform a qualitative analysis of the ranking result from HITS in real-world networks\n",
    "    - We performed a qualitative analysis on the `enron` dataset which is a real-world network. \n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}