python/VW_in_Python.ipynb

{
 "metadata": {
  "name": "",
  "signature": "sha256:adab691815f23e7956d65fcf2c383e571ab9ce7e1bfaf4fdc2c7d3130673a551"
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "This notebook demonstrates the most basic capabilities of the pyvw python->VW interface. The inferface (unlike the rest of VW :P) is extensively documented, so if you are confused, look at the python docs!\n",
      "\n",
      "Any pyvw application needs to begin by importing `pyvw`."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "import pyvw"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 2
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "One we've imported pyvw, we can initialize VW either by passing a command line string (e.g., \"--quiet -q ab --l2 0.01\") or, in a more python-friendly manner, providing those as named arguments. Here we do the latter."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "vw = pyvw.vw(quiet=True, q='ab', l2=0.01)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 3
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "VW objects can do a lot, but the most important thing the can do is create examples and train/predict on those examples.\n",
      "\n",
      "One way to create an example is to pass a string. This is the equivalent of a string in a VW file. For instance:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "ex = vw.example('1 |a two features |b more features here')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 4
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "As promised there is documentation; for instance:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "help(ex.learn)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Help on method learn in module pyvw:\n",
        "\n",
        "learn(self) method of pyvw.example instance\n",
        "    Learn on this example (and before learning, automatically\n",
        "    call setup_example if the example hasn't yet been setup).\n",
        "\n"
       ]
      }
     ],
     "prompt_number": 54
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Let's run that learn function and get a prediction:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "ex.learn()\n",
      "print 'current prediction =', ex.get_updated_prediction()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "current prediction = 0.823003947735\n"
       ]
      }
     ],
     "prompt_number": 5
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Here, `get_updated_prediction` retrieves the prediction made internally during learning. The \"updated\" aspect means \"if I were to make a prediction on this example *after* this call to `learn`, what would that prediction be?\"\n",
      "\n",
      "Okay, so the prediction isn't quite where we want it yet. Let's learn a few more times and then print the prediction."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "ex.learn() ; ex.learn() ; ex.learn() ; ex.learn()\n",
      "print 'current prediction =', ex.get_updated_prediction()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "current prediction = 0.999285042286\n"
       ]
      }
     ],
     "prompt_number": 6
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "This is now quite a bit closer to what is desired.\n",
      "\n",
      "Now let's create a new example using the other form of example creation: python dictionaries. Here, you must provide a dictionary that maps namespaces (eg, 'a' and 'b') to lists of features. Features can either be strings (eg `\"foo\"`), or pairs of string/floats (eg `(\"foo\", 0.5)`). We'll create an example that's similar, but not identical to, the previous example to see how well VW has generalized.\n",
      "\n",
      "Note that in this setup there is no label provided, which means that this will be considered a test example."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "ex2 = vw.example({ 'a': ['features'], 'b': ['more', 'features', 'there'] })"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 7
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Given this example, we execute `learn`. But since it's a test example (no label), this will only make a prediction!"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "ex2.learn()\n",
      "print 'current prediction =', ex2.get_simplelabel_prediction()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "current prediction = 0.498447239399\n"
       ]
      }
     ],
     "prompt_number": 8
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Because this is a test example, we can get the raw prediction with `get_simplelabel_prediction()`. This is `simplelabel` because it's a regression problem. If we were doing, for instance, One-Against-All multiclass prediction, we would use `get_multiclass_prediction`, etc.\n",
      "\n",
      "This prediction is only about half of what we want, but we're also missing a number of features.\n",
      "\n",
      "Let's now give this example a label and train on it a few times:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "ex2.set_label_string('-2.0')\n",
      "ex2.learn() ; ex2.learn() ; ex2.learn() ; ex2.learn() ; ex2.learn()\n",
      "print 'current prediction =', ex2.get_simplelabel_prediction()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "current prediction = -1.48386406898\n"
       ]
      }
     ],
     "prompt_number": 9
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Now we can go back and see how this has affected the prediction behavior on the original example `ex`. We do this first by removing the label and then calling `learn` to make a prediction."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "ex.set_label_string('')\n",
      "ex.learn()\n",
      "print 'current prediction =', ex.get_simplelabel_prediction()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "current prediction = -0.593429207802\n"
       ]
      }
     ],
     "prompt_number": 60
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Clearly this has had an impact on the prediction for the first example. Let's put the label back and then iterate between learning on `ex` and `ex2`:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "ex.set_label_string('1')\n",
      "for i in range(10):\n",
      "    ex.learn()\n",
      "    ex2.learn()\n",
      "    print 'ex prediction =', ex.get_updated_prediction(),\n",
      "    print 'ex2 prediction =', ex2.get_updated_prediction()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "ex prediction = 0.244248270988 ex2 prediction = -1.54065942764\n",
        "ex prediction = 0.553374171257 ex2 prediction = -1.55157399178\n",
        "ex prediction = 0.70502603054 ex2 prediction = -1.59672987461\n",
        "ex prediction = 0.787389457226 ex2 prediction = -1.64851796627\n",
        "ex prediction = 0.836634874344 ex2 prediction = -1.69708633423\n",
        "ex prediction = 0.868749797344 ex2 prediction = -1.73938345909\n",
        "ex prediction = 0.891242325306 ex2 prediction = -1.77498090267\n",
        "ex prediction = 0.907864630222 ex2 prediction = -1.80443906784\n",
        "ex prediction = 0.920608520508 ex2 prediction = -1.82860839367\n",
        "ex prediction = 0.930600643158 ex2 prediction = -1.84836173058\n"
       ]
      }
     ],
     "prompt_number": 10
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "After a handful of updates, we can see that the prediction for `ex` is going back toward `1.0` and for `ex2` back toward `-2.0`.\n",
      "\n",
      "Now that we're done, it's safest to tell VW that we're done with these examples and that it can garbage collect them. (This should happen by default when they pass out of scope per Python's build in garbage collector, but that may not run soon enough if you're manipulating large numbers of examples at once!)"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "ex.finish()\n",
      "ex2.finish()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 11
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Finally, when we're done with VW entirely, or perhaps want to start up a new VW instance, it's good behavior to close out any old ones. This is especially important if we wanted to save a model to disk: calling `vw.finish()` tells it to write the file. You can add `f='mymodel'` to the initialization line of the `vw` object if you want to play around with this!"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "vw.finish()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 12
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "This is the end of the intro. For more, look at `test.py` in the `python` directory of the VW distribution; this contains some more examples. For even more, look at the python docs in `pyvw.py`, for instance `help(pyvw.vw)` and so on!\n",
      "\n",
      "Happy VW-Pythoning!"
     ]
    }
   ],
   "metadata": {}
  }
 ]
}