skl_classifier_demo.ipynb

{
  "metadata": {
    "name": "Using scikit-learn classifiers with PyMVPA"
  }, 
  "nbformat": 3, 
  "nbformat_minor": 0, 
  "worksheets": [
    {
      "cells": [
        {
          "cell_type": "heading", 
          "level": 1, 
          "metadata": {}, 
          "source": [
            "Using scikit-learn classifiers with PyMVPA"
          ]
        }, 
        {
          "cell_type": "markdown", 
          "metadata": {}, 
          "source": [
            "\n\n", 
            "Scikit-learn is a rich library of algorithms, many of them implementing the\n", 
            "[estimator and predictor API](http://scikit-learn.org/stable/developers/#apis-of-scikit-learn-objects). PyMVPA provides the wrapper class,\n", 
            "[SKLLearnerAdapter](http://pymvpa.org/generated/mvpa2.clfs.skl.base.SKLLearnerAdapter.html#mvpa2-clfs-skl-base-skllearneradapter) that enables the use\nof all of these algorithms within the PyMVPA framework. With this adaptor\nthese aspects of the scikit-learn API are presented through a PyMVPA\nlearner interface that is fully compatible with all other building blocks of\nPyMVPA.\n\n", 
            "In this example we demonstrate this interface by mimicking the \"", 
            "[Nearest Neighbors Classification](http://scikit-learn.org/stable/auto_examples/neighbors/plot_classification.html)\" example from the scikit-learn documentation --\napplying the minimal modifications necessary to run two variants of the\nscikit-learn k-nearest neighbors algorithm implementation on PyMVPA datasets."
          ]
        }, 
        {
          "cell_type": "code", 
          "collapsed": false, 
          "input": [
            "print(__doc__)\n\nimport numpy as np\nimport pylab as pl\nfrom matplotlib.colors import ListedColormap\nfrom sklearn import neighbors\n\nn_neighbors = 15"
          ], 
          "language": "python", 
          "metadata": {}, 
          "outputs": []
        }, 
        {
          "cell_type": "markdown", 
          "metadata": {}, 
          "source": [
            "\n\n", 
            "So far the code has been identical. The first difference is the import of the\nadaptor class. We also load the scikit-learn demo dataset, but also with the\nhelp of a wrapper function that yields a PyMVPA dataset."
          ]
        }, 
        {
          "cell_type": "code", 
          "collapsed": false, 
          "input": [
            "# this first import is only required to run the example a part of the test suite\nfrom mvpa2 import cfg\nfrom mvpa2.clfs.skl.base import SKLLearnerAdapter\n\n# load the iris dataset\nfrom mvpa2.datasets.sources.skl_data import skl_iris\niris = skl_iris()\n# compact dataset summary\nprint iris"
          ], 
          "language": "python", 
          "metadata": {}, 
          "outputs": []
        }, 
        {
          "cell_type": "markdown", 
          "metadata": {}, 
          "source": [
            "\n\n", 
            "The original example uses only the first two features of the dataset,\nsince it intends to visualize learned classification boundaries in 2-D.\nWe can do the same slicing directly on our PyMVPA dataset."
          ]
        }, 
        {
          "cell_type": "code", 
          "collapsed": false, 
          "input": [
            "iris=iris[:,[0,1]]\n\nd = {'setosa':0, 'versicolor':1, 'virginica':2}"
          ], 
          "language": "python", 
          "metadata": {}, 
          "outputs": []
        }, 
        {
          "cell_type": "markdown", 
          "metadata": {}, 
          "source": [
            "\n\n", 
            "For visualization we will later map the literal class labels onto\nnumerival values. Besides that, we continue with practically identical code."
          ]
        }, 
        {
          "cell_type": "code", 
          "collapsed": false, 
          "input": [
            "h = .02  # step size in the mesh\n\ncmap_light = ListedColormap(['#FFAAAA', '#AAFFAA', '#AAAAFF'])\ncmap_bold = ListedColormap(['#FF0000', '#00FF00', '#0000FF'])\n\nfor weights in ['uniform', 'distance']:\n    # create an instance of the algorithm from scikit-learn,\n    # wrap it by SKLLearnerAdapter and finally train it\n    clf = neighbors.KNeighborsClassifier(n_neighbors, weights=weights)\n    wrapped_clf=SKLLearnerAdapter(clf)\n    wrapped_clf.train(iris)"
          ], 
          "language": "python", 
          "metadata": {}, 
          "outputs": []
        }, 
        {
          "cell_type": "markdown", 
          "metadata": {}, 
          "source": [
            "\n\n", 
            "The following lines are an example of the only significant modification\nwith respect to a pure scikit-learn implementation: the classifier is\nwrapped into the adaptor.  The result is a PyMVPA classifier, hence can\nbe called with a dataset that contains both samples and targets."
          ]
        }, 
        {
          "cell_type": "code", 
          "collapsed": false, 
          "input": [
            "\u00bb    # shortcut\n     X = iris.samples\n     # Plot the decision boundary. For that, we will assign a color to each\n     # point in the mesh [x_min, m_max]x[y_min, y_max].\n     x_min, x_max = X[:, 0].min() - 1, X[:, 0].max() + 1\n     y_min, y_max = X[:, 1].min() - 1, X[:, 1].max() + 1\n     xx, yy = np.meshgrid(np.arange(x_min, x_max, h),\n                          np.arange(y_min, y_max, h))\n     Z = wrapped_clf.predict(np.c_[xx.ravel(), yy.ravel()])\n\n     # to put the result into a color plot we now need numerical values\n     # this can be done nicely in PyMVPA\n     from mvpa2.datasets.formats import AttributeMap\n     Z = AttributeMap().to_numeric(Z)\n     Z = Z.reshape(xx.shape)\n\n     pl.figure()\n     pl.pcolormesh(xx, yy, Z, cmap=cmap_light)\n\n     # For plotting the training points we convert to numerical values again\n     pl.scatter(X[:, 0], X[:, 1], c=AttributeMap().to_numeric(iris.targets),\n                                  cmap=cmap_bold)\n     pl.xlim(xx.min(), xx.max())\n     pl.ylim(yy.min(), yy.max())\n     pl.title(\"3-Class classification (k = %i, weights = '%s')\"\n              % (n_neighbors, weights))"
          ], 
          "language": "python", 
          "metadata": {}, 
          "outputs": []
        }, 
        {
          "cell_type": "markdown", 
          "metadata": {}, 
          "source": [
            "\n\n", 
            "This example shows that a PyMVPA classifier can be used in pretty much the\nsame way as the corresponding scikit-learn API. What this example does not show\nis that with the ", 
            "[SKLLearnerAdapter](http://pymvpa.org/generated/mvpa2.clfs.skl.base.SKLLearnerAdapter.html#mvpa2-clfs-skl-base-skllearneradapter) class any\nscikit-learn classifier can be employed in arbitrarily complex PyMVPA\nprocessing pipelines and is enhanced with automatic training and all other\nfunctionality of PyMVPA classifier implementations."
          ]
        }
      ], 
      "metadata": {}
    }
  ]
}