Annoy Tutorial - Text8 Changes

annoytutorial-text8.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Similarity Queries using Annoy Tutorial"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This tutorial is about using the ([Annoy Approximate Nearest Neighbors Oh Yeah](https://github.com/spotify/annoy \"Link to annoy repo\")) library for similarity queries with a Word2Vec model built with gensim.\n",
    "\n",
    "## Why use Annoy?\n",
    "The current implementation for finding k nearest neighbors in a vector space in gensim has linear complexity via brute force in the number of indexed documents, although with extremely low constant factors. The retrieved results are exact, which is an overkill in many applications: approximate results retrieved in sub-linear time may be enough. Annoy can find approximate nearest neighbors much faster.\n",
    "\n",
    "\n",
    "## Prerequisites\n",
    "Additional libraries needed for this tutorial:\n",
    "- annoy\n",
    "- psutil\n",
    "- matplotlib\n",
    "\n",
    "## Outline\n",
    "1. Download Text8 Corpus\n",
    "2. Build Word2Vec Model\n",
    "3. Construct AnnoyIndex with model & make a similarity query\n",
    "4. Verify & Evaluate performance\n",
    "5. Evaluate relationship of `num_trees` to initialization time and accuracy"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "CPython 3.6.1\n",
      "IPython 6.0.0\n",
      "\n",
      "gensim 2.1.0\n",
      "numpy 1.12.1\n",
      "scipy 0.19.0\n",
      "psutil 5.2.2\n",
      "matplotlib 2.0.2\n",
      "\n",
      "compiler   : GCC 4.2.1 Compatible Apple LLVM 6.0 (clang-600.0.57)\n",
      "system     : Darwin\n",
      "release    : 14.5.0\n",
      "machine    : x86_64\n",
      "processor  : i386\n",
      "CPU cores  : 8\n",
      "interpreter: 64bit\n"
     ]
    }
   ],
   "source": [
    "# pip install watermark\n",
    "%reload_ext watermark\n",
    "%watermark -v -m -p gensim,numpy,scipy,psutil,matplotlib"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1. Download Text8 Corpus"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os.path\n",
    "if not os.path.isfile('text8'):\n",
    "    !wget -c http://mattmahoney.net/dc/text8.zip\n",
    "    !unzip text8.zip"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Import & Set up Logging\n",
    "I'm not going to set up logging due to the verbose input displaying in notebooks, but if you want that, uncomment the lines in the cell below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "LOGS = False\n",
    "\n",
    "if LOGS:\n",
    "    import logging\n",
    "    logging.basicConfig(format='%(asctime)s : %(levelname)s : %(message)s', level=logging.INFO)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2. Build Word2Vec Model"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Word2Vec(vocab=71290, size=100, alpha=0.05)\n"
     ]
    }
   ],
   "source": [
    "from gensim.models import Word2Vec, KeyedVectors\n",
    "from gensim.models.word2vec import Text8Corpus\n",
    "\n",
    "# using params from Word2Vec_FastText_Comparison\n",
    "\n",
    "lr = 0.05\n",
    "dim = 100\n",
    "ws = 5\n",
    "epoch = 5\n",
    "minCount = 5\n",
    "neg = 5\n",
    "loss = 'ns'\n",
    "t = 1e-4\n",
    "\n",
    "# Same values as used for fastText training above\n",
    "params = {\n",
    "    'alpha': lr,\n",
    "    'size': dim,\n",
    "    'window': ws,\n",
    "    'iter': epoch,\n",
    "    'min_count': minCount,\n",
    "    'sample': t,\n",
    "    'sg': 1,\n",
    "    'hs': 0,\n",
    "    'negative': neg\n",
    "}\n",
    "\n",
    "model = Word2Vec(Text8Corpus('text8'), **params)\n",
    "print(model)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "See the [Word2Vec tutorial](https://github.com/RaRe-Technologies/gensim/blob/develop/docs/notebooks/word2vec.ipynb) for how to initialize and save this model."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Comparing the traditional implementation and the Annoy approximation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "#Set up the model and vector that we are using in the comparison\n",
    "try:\n",
    "    from gensim.similarities.index import AnnoyIndexer\n",
    "except ImportError:\n",
    "    raise ValueError(\"SKIP: Please install the annoy indexer\")\n",
    "\n",
    "model.init_sims()\n",
    "annoy_index = AnnoyIndexer(model, 100)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('the', 1.0),\n",
       " ('of', 0.8307580947875977),\n",
       " ('in', 0.8200849294662476),\n",
       " ('a', 0.7943764925003052),\n",
       " ('and', 0.7535111904144287)]"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Dry run to make sure both indices are fully in RAM\n",
    "vector = model.wv.syn0norm[0]\n",
    "model.most_similar([vector], topn=5, indexer=annoy_index)\n",
    "model.most_similar([vector], topn=5)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import time\n",
    "import numpy as np"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def avg_query_time(annoy_index=None, queries=1000):\n",
    "    \"\"\"\n",
    "    Average query time of a most_similar method over 1000 random queries,\n",
    "    uses annoy if given an indexer\n",
    "    \"\"\"\n",
    "    total_time = 0\n",
    "    for _ in range(queries):\n",
    "        rand_vec = model.wv.syn0norm[np.random.randint(0, len(model.wv.vocab))]\n",
    "        start_time = time.clock()\n",
    "        model.most_similar([rand_vec], topn=5, indexer=annoy_index)\n",
    "        total_time += time.clock() - start_time\n",
    "    return total_time / queries"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Gensim (s/query):\t0.00537\n",
      "Annoy (s/query):\t0.00027\n",
      "\n",
      "Annoy is 20.20 times faster on average on this particular run\n"
     ]
    }
   ],
   "source": [
    "queries = 10000\n",
    "\n",
    "gensim_time = avg_query_time(queries=queries)\n",
    "annoy_time = avg_query_time(annoy_index, queries=queries)\n",
    "print(\"Gensim (s/query):\\t{0:.5f}\".format(gensim_time))\n",
    "print(\"Annoy (s/query):\\t{0:.5f}\".format(annoy_time))\n",
    "speed_improvement = gensim_time / annoy_time\n",
    "print (\"\\nAnnoy is {0:.2f} times faster on average on this particular run\".format(speed_improvement))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "**This speedup factor is by no means constant** and will vary greatly from run to run and is particular to this data set, BLAS setup, Annoy parameters(as tree size increases speedup factor decreases), machine specifications, among other factors.\n",
    "\n",
    ">**Note**: Initialization time for the annoy indexer was not included in the times. The optimal knn algorithm for you to use will depend on how many queries you need to make and the size of the corpus. If you are making very few similarity queries, the time taken to initialize the annoy indexer will be longer than the time it would take the brute force method to retrieve results. If you are making many queries however, the time it takes to initialize the annoy indexer will be made up for by the incredibly fast retrieval times for queries once the indexer has been initialized\n",
    "\n",
    ">**Note** : Gensim's 'most_similar' method is using numpy operations in the form of dot product whereas Annoy's method isnt. If 'numpy' on your machine is using one of the BLAS libraries like ATLAS or LAPACK, it'll run on multiple cores(only if your machine has multicore support ). Check [SciPy Cookbook](http://scipy-cookbook.readthedocs.io/items/ParallelProgramming.html) for more details."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Construct AnnoyIndex with model & make a similarity query"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Creating an indexer\n",
    "An instance of `AnnoyIndexer` needs to be created in order to use Annoy in gensim. The `AnnoyIndexer` class is located in `gensim.similarities.index`\n",
    "\n",
    "`AnnoyIndexer()` takes two parameters:\n",
    "\n",
    "**`model`**: A `Word2Vec` or `Doc2Vec` model\n",
    "\n",
    "**`num_trees`**: A positive integer. `num_trees` effects the build time and the index size. **A larger value will give more accurate results, but larger indexes**. More information on what trees in Annoy do can be found [here](https://github.com/spotify/annoy#how-does-it-work). The relationship between `num_trees`, build time, and accuracy will be investigated later in the tutorial. \n",
    "\n",
    "Now that we are ready to make a query, lets find the top 5 most similar words to \"science\" in the Text8 corpus. To make a similarity query we call `Word2Vec.most_similar` like we would traditionally, but with an added parameter, `indexer`. The only supported indexer in gensim as of now is Annoy. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Approximate Neighbors\n",
      "('science', 0.9997558594041038)\n",
      "('astrobiology', 0.5987220406532288)\n",
      "('xenobiology', 0.5892171859741211)\n",
      "('scientific', 0.5891056060791016)\n",
      "('actuarial', 0.587224930524826)\n",
      "('robotics', 0.5860361754894257)\n",
      "('interdisciplinary', 0.5859909355640411)\n",
      "('multidisciplinary', 0.579128235578537)\n",
      "('sciences', 0.5784446597099304)\n",
      "('cryobiology', 0.5775857865810394)\n",
      "('protoscience', 0.5757511854171753)\n",
      "\n",
      "Normal (not Annoy-indexed) Neighbors\n",
      "('science', 1.0000001192092896)\n",
      "('fiction', 0.7420862913131714)\n",
      "('astrobiology', 0.6779519319534302)\n",
      "('vinge', 0.6737632155418396)\n",
      "('vernor', 0.6723923683166504)\n",
      "('xenobiology', 0.6625149846076965)\n",
      "('scientific', 0.6623317003250122)\n",
      "('actuarial', 0.659233570098877)\n",
      "('robotics', 0.6572679281234741)\n",
      "('interdisciplinary', 0.6571928262710571)\n",
      "('technology', 0.6474959850311279)\n"
     ]
    }
   ],
   "source": [
    "# 100 trees are being used in this example\n",
    "annoy_index = AnnoyIndexer(model, 100)\n",
    "# Derive the vector for the word \"science\" in our model\n",
    "vector = model[\"science\"]\n",
    "# The instance of AnnoyIndexer we just created is passed \n",
    "approximate_neighbors = model.most_similar([vector], topn=11, indexer=annoy_index)\n",
    "# Neatly print the approximate_neighbors and their corresponding cosine similarity values\n",
    "print(\"Approximate Neighbors\")\n",
    "for neighbor in approximate_neighbors:\n",
    "    print(neighbor)\n",
    "\n",
    "normal_neighbors = model.most_similar([vector], topn=11)\n",
    "print(\"\\nNormal (not Annoy-indexed) Neighbors\")\n",
    "for neighbor in normal_neighbors:\n",
    "    print(neighbor)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Analyzing the results"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The closer the cosine similarity of a vector is to 1, the more similar that word is to our query, which was the vector for \"science\". There are some differences in the ranking of similar words and the set of words included within the 10 most similar words."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 4. Verify & Evaluate performance"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Persisting Indexes\n",
    "You can save and load your indexes from/to disk to prevent having to construct them each time. This will create two files on disk, _fname_ and _fname.d_. Both files are needed to correctly restore all attributes. Before loading an index, you will have to create an empty AnnoyIndexer object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "fname = 'index'\n",
    "\n",
    "# Persist index to disk\n",
    "annoy_index.save(fname)\n",
    "\n",
    "# Load index back\n",
    "if os.path.exists(fname):\n",
    "    annoy_index2 = AnnoyIndexer()\n",
    "    annoy_index2.load(fname)\n",
    "    annoy_index2.model = model"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "('science', 0.9997558594041038)\n",
      "('astrobiology', 0.5987220406532288)\n",
      "('xenobiology', 0.5892171859741211)\n",
      "('scientific', 0.5891056060791016)\n",
      "('actuarial', 0.587224930524826)\n",
      "('robotics', 0.5860361754894257)\n",
      "('interdisciplinary', 0.5859909355640411)\n",
      "('multidisciplinary', 0.579128235578537)\n",
      "('sciences', 0.5784446597099304)\n",
      "('cryobiology', 0.5775857865810394)\n",
      "('protoscience', 0.5757511854171753)\n"
     ]
    }
   ],
   "source": [
    "# Results should be identical to above\n",
    "vector = model[\"science\"]\n",
    "approximate_neighbors2 = model.most_similar([vector], topn=11, indexer=annoy_index2)\n",
    "for neighbor in approximate_neighbors2:\n",
    "    print(neighbor)\n",
    "    \n",
    "assert approximate_neighbors == approximate_neighbors2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Be sure to use the same model at load that was used originally, otherwise you will get unexpected behaviors."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Save memory by memory-mapping indices saved to disk\n",
    "\n",
    "Annoy library has a useful feature that indices can be memory-mapped from disk. It saves memory when the same index is used by several processes.\n",
    "\n",
    "Below are two snippets of code. First one has a separate index for each process. The second snipped shares the index between two processes via memory-mapping. The second example uses less total RAM as it is shared."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Remove verbosity from code below (if logging active)\n",
    "\n",
    "if LOGS:\n",
    "    logging.disable(logging.CRITICAL)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "from multiprocessing import Process\n",
    "import os\n",
    "import psutil"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Bad Example: Two processes load the Word2vec model from disk and create there own Annoy indices from that model. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Process Id:  5756\n",
      "\n",
      "Memory used by process 5756:  pmem(rss=358707200, vms=3374735360, pfaults=150346, pageins=0) \n",
      "---\n",
      "Process Id:  5757\n",
      "\n",
      "Memory used by process 5757:  pmem(rss=358555648, vms=3374735360, pfaults=150311, pageins=0) \n",
      "---\n",
      "CPU times: user 505 ms, sys: 190 ms, total: 694 ms\n",
      "Wall time: 29.3 s\n"
     ]
    }
   ],
   "source": [
    "%%time\n",
    "\n",
    "model.save('/tmp/mymodel')\n",
    "\n",
    "def f(process_id):\n",
    "    print ('Process Id: ', os.getpid())\n",
    "    process = psutil.Process(os.getpid())\n",
    "    new_model = Word2Vec.load('/tmp/mymodel')\n",
    "    vector = new_model[\"science\"]\n",
    "    annoy_index = AnnoyIndexer(new_model,100)\n",
    "    approximate_neighbors = new_model.most_similar([vector], topn=5, indexer=annoy_index)\n",
    "    print('\\nMemory used by process {}: '.format(os.getpid()), process.memory_info(), \"\\n---\")\n",
    "\n",
    "# Creating and running two parallel process to share the same index file.\n",
    "p1 = Process(target=f, args=('1',))\n",
    "p1.start()\n",
    "p1.join()\n",
    "p2 = Process(target=f, args=('2',))\n",
    "p2.start()\n",
    "p2.join()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Good example. Two processes load both the Word2vec model and index from disk and memory-map the index\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Process Id:  5816\n",
      "\n",
      "Memory used by process 5816:  pmem(rss=312770560, vms=3466285056, pfaults=104920, pageins=0) \n",
      "---\n",
      "Process Id:  5817\n",
      "\n",
      "Memory used by process 5817:  pmem(rss=312623104, vms=3466285056, pfaults=104883, pageins=0) \n",
      "---\n",
      "CPU times: user 512 ms, sys: 200 ms, total: 712 ms\n",
      "Wall time: 2.66 s\n"
     ]
    }
   ],
   "source": [
    "%%time\n",
    "\n",
    "model.save('/tmp/mymodel')\n",
    "\n",
    "def f(process_id):\n",
    "    print('Process Id: ', os.getpid())\n",
    "    process = psutil.Process(os.getpid())\n",
    "    new_model = Word2Vec.load('/tmp/mymodel')\n",
    "    vector = new_model[\"science\"]\n",
    "    annoy_index = AnnoyIndexer()\n",
    "    annoy_index.load('index')\n",
    "    annoy_index.model = new_model\n",
    "    approximate_neighbors = new_model.most_similar([vector], topn=5, indexer=annoy_index)\n",
    "    print('\\nMemory used by process {}: '.format(os.getpid()), process.memory_info(), \"\\n---\")\n",
    "\n",
    "# Creating and running two parallel process to share the same index file.\n",
    "p1 = Process(target=f, args=('1',))\n",
    "p1.start()\n",
    "p1.join()\n",
    "p2 = Process(target=f, args=('2',))\n",
    "p2.start()\n",
    "p2.join()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 5. Evaluate relationship of `num_trees` to initialization time and accuracy"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "%matplotlib inline"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Build dataset of Initialization times and accuracy measures"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "exact_results = [element[0] for element in model.most_similar([model.wv.syn0norm[0]], topn=100)]\n",
    "\n",
    "x_values = []\n",
    "y_values_init = []\n",
    "y_values_accuracy = []\n",
    "\n",
    "for x in range(1, 200, 10):\n",
    "    x_values.append(x)\n",
    "    start_time = time.time()\n",
    "    annoy_index = AnnoyIndexer(model, x)\n",
    "    y_values_init.append(time.time() - start_time)\n",
    "    approximate_results = model.most_similar([model.wv.syn0norm[0]], topn=100, indexer=annoy_index)\n",
    "    top_words = [result[0] for result in approximate_results]\n",
    "    y_values_accuracy.append(len(set(top_words).intersection(exact_results)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Plot results"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.figure(1, figsize=(12, 6))\n",
    "plt.subplot(121)\n",
    "plt.plot(x_values, y_values_init)\n",
    "plt.title(\"num_trees vs initalization time\")\n",
    "plt.ylabel(\"Initialization time (s)\")\n",
    "plt.xlabel(\"num_trees\")\n",
    "plt.subplot(122)\n",
    "plt.plot(x_values, y_values_accuracy)\n",
    "plt.title(\"num_trees vs accuracy\")\n",
    "plt.ylabel(\"% accuracy\")\n",
    "plt.xlabel(\"num_trees\")\n",
    "plt.tight_layout()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Initialization:\n",
    "Initialization time of the annoy indexer increases in a linear fashion with num_trees. Initialization time will vary from corpus to corpus, in the graph above the lee corpus was used\n",
    "\n",
    "##### Accuracy:\n",
    "In this dataset, the accuracy seems logarithmically related to the number of trees. We see a pretty sharp improvement up until 100 trees, and then a less drastic change in improvement with more trees after that."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Recap\n",
    "In this notebook we used the Annoy module to build an indexed approximation of our word embeddings. To do so, did the following steps:\n",
    "1. Download Text8 Corpus\n",
    "2. Build Word2Vec Model\n",
    "3. Construct AnnoyIndex with model & make a similarity query\n",
    "4. Verify & Evaluate performance\n",
    "5. Evaluate relationship of `num_trees` to initialization time and accuracy"
   ]
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "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.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}