sklearn presentation.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Scikit-learn pipelines and custom transformers/estimators"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "#### 07.03.2018\n",
    "Przemysław Pobrotyn"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "<img src=\"figures/sigmoidal.jpg\" width=\"300\" height=\"300\" align=\"right\" />"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Quick recap of sklearn's API"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "###### Built-in popular datasets"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 0.,  0.,  5., ...,  0.,  0.,  0.],\n",
       "       [ 0.,  0.,  0., ..., 10.,  0.,  0.],\n",
       "       [ 0.,  0.,  0., ..., 16.,  9.,  0.],\n",
       "       ...,\n",
       "       [ 0.,  0.,  1., ...,  6.,  0.,  0.],\n",
       "       [ 0.,  0.,  2., ..., 12.,  0.,  0.],\n",
       "       [ 0.,  0., 10., ..., 12.,  1.,  0.]])"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from sklearn import datasets\n",
    "digits = datasets.load_digits()\n",
    "digits.data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([0, 1, 2, ..., 8, 9, 8])"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "digits.target"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 0.,  0.,  5., 13.,  9.,  1.,  0.,  0.],\n",
       "       [ 0.,  0., 13., 15., 10., 15.,  5.,  0.],\n",
       "       [ 0.,  3., 15.,  2.,  0., 11.,  8.,  0.],\n",
       "       [ 0.,  4., 12.,  0.,  0.,  8.,  8.,  0.],\n",
       "       [ 0.,  5.,  8.,  0.,  0.,  9.,  8.,  0.],\n",
       "       [ 0.,  4., 11.,  0.,  1., 12.,  7.,  0.],\n",
       "       [ 0.,  2., 14.,  5., 10., 12.,  0.,  0.],\n",
       "       [ 0.,  0.,  6., 13., 10.,  0.,  0.,  0.]])"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "digits.images[0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "image/png": "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\nNyyRs2/TGgiSAAAAAElFTkSuQmCC\n",
      "text/plain": [
       "<matplotlib.figure.Figure at 0x111320668>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "plt.imshow(digits.images[0], cmap=plt.cm.gray_r)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "###### Supervised learning"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "SVC(C=100.0, cache_size=200, class_weight=None, coef0=0.0,\n",
       "  decision_function_shape='ovr', degree=3, gamma=0.001, kernel='rbf',\n",
       "  max_iter=-1, probability=False, random_state=None, shrinking=True,\n",
       "  tol=0.001, verbose=False)"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from sklearn import svm\n",
    "clf = svm.SVC(gamma=0.001, C=100.)\n",
    "clf"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "![title](figures/svm.png)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "SVC(C=100.0, cache_size=200, class_weight=None, coef0=0.0,\n",
       "  decision_function_shape='ovr', degree=3, gamma=0.001, kernel='rbf',\n",
       "  max_iter=-1, probability=False, random_state=None, shrinking=True,\n",
       "  tol=0.001, verbose=False)"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "clf.fit(digits.data[:-1], digits.target[:-1])  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([8])"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "clf.predict(digits.data[-1:])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAPgAAAD8CAYAAABaQGkdAAAABHNCSVQICAgIfAhkiAAAAAlwSFlz\nAAALEgAACxIB0t1+/AAACsxJREFUeJzt3e9rnfUZx/HPZ1HZ/NVC2xVpa6MgBRnMSihIQWndRp2i\nE/agBcXIoI8Uwwaie+Y/IN2DIUi1KdgpW1UQcTpBoxM2Z1q7zZo6unJGs+qaMorVwUr12oOcQtdl\n5E7P9/6Ry/cLivlxyPc61rf3nZM799cRIQA5fa3tAQDUh8CBxAgcSIzAgcQIHEiMwIHECBxIjMCB\nxAgcSOyiOr7o8uXLY3h4uI4v3aper9foeqdOnWpsrWXLljW21sqVKxtba2hoqLG1mtTr9XTixAnP\n97haAh8eHtbk5GQdX7pVo6Ojja43MTHR2FpNPrexsbHG1lq6dGljazVpZGSk0uM4RQcSI3AgMQIH\nEiNwIDECBxIjcCAxAgcSI3AgsUqB295i+yPbh20/UvdQAMqYN3DbQ5J+Luk2SddL2mb7+roHAzC4\nKkfwDZIOR8SRiDgt6TlJd9U7FoASqgS+StLRc96f7n8MQMdVCXyu31j5n5up295ue9L25MzMzOCT\nARhYlcCnJa055/3Vko6d/6CIeDIiRiJiZMWKFaXmAzCAKoG/J+k629fYvkTSVkkv1TsWgBLm/X3w\niDhj+wFJr0kakvR0RBysfTIAA6t0w4eIeEXSKzXPAqAwrmQDEiNwIDECBxIjcCAxAgcSI3AgMQIH\nEiNwILFadjZpUpPbCe3evbuxtSRp7dq1ja2VcaspcAQHUiNwIDECBxIjcCAxAgcSI3AgMQIHEiNw\nIDECBxKrsrPJ07aP2/6giYEAlFPlCD4uaUvNcwCowbyBR8Tbkv7ZwCwACuN7cCCxYoGzdRHQPcUC\nZ+sioHs4RQcSq/Jjsmcl/U7SOtvTtn9U/1gASqiyN9m2JgYBUB6n6EBiBA4kRuBAYgQOJEbgQGIE\nDiRG4EBiBA4ktui3Lmpyy50lS5Y0tpYknTx5srG1mtwCqsm/syb/HXYRR3AgMQIHEiNwIDECBxIj\ncCAxAgcSI3AgMQIHEiNwIDECBxKrctPFNbbftD1l+6Dth5oYDMDgqlyLfkbSTyJiv+0rJO2z/XpE\nfFjzbAAGVGVvso8jYn//7VOSpiStqnswAINb0PfgtoclrZf07hyfY+sioGMqB277cknPSxqLiE/P\n/zxbFwHdUylw2xdrNu49EfFCvSMBKKXKq+iW9JSkqYh4vP6RAJRS5Qi+UdK9kjbbPtD/8/2a5wJQ\nQJW9yd6R5AZmAVAYV7IBiRE4kBiBA4kROJAYgQOJETiQGIEDiRE4kNii35usSePj442ud/fddze2\n1mOPPdbYWvfdd19ja33VcQQHEiNwIDECBxIjcCAxAgcSI3AgMQIHEiNwIDECBxKrctPFr9v+g+0/\n9rcuau6SJwADqXKp6r8lbY6Iz/q3T37H9q8j4vc1zwZgQFVuuhiSPuu/e3H/T9Q5FIAyqm58MGT7\ngKTjkl6PCLYuAhaBSoFHxBcRcYOk1ZI22P7WHI9h6yKgYxb0KnpEnJQ0IWlLLdMAKKrKq+grbC/t\nv/0NSd+RdKjuwQAMrsqr6FdJ2m17SLP/Q/hlRLxc71gASqjyKvqfNLsnOIBFhivZgMQIHEiMwIHE\nCBxIjMCBxAgcSIzAgcQIHEiMrYsWYMeOHY2ut2TJkkbXa0qv12t7hK8MjuBAYgQOJEbgQGIEDiRG\n4EBiBA4kRuBAYgQOJEbgQGKVA+/fG/1929yPDVgkFnIEf0jSVF2DACiv6s4mqyXdLmlnveMAKKnq\nEXyHpIclfVnjLAAKq7LxwR2SjkfEvnkex95kQMdUOYJvlHSn7Z6k5yRttv3M+Q9ibzKge+YNPCIe\njYjVETEsaaukNyLintonAzAwfg4OJLagO7pExIRmdxcFsAhwBAcSI3AgMQIHEiNwIDECBxIjcCAx\nAgcSI3AgsUW/ddHExERja7311luNrSVJu3btamyt4eHhxtbatGlTY2uNj483tpYkjY6ONrrefDiC\nA4kROJAYgQOJETiQGIEDiRE4kBiBA4kROJAYgQOJVbqSrX9H1VOSvpB0JiJG6hwKQBkLuVR1U0Sc\nqG0SAMVxig4kVjXwkPQb2/tsb69zIADlVD1F3xgRx2x/U9Lrtg9FxNvnPqAf/nZJuvrqqwuPCeBC\nVDqCR8Sx/j+PS3pR0oY5HsPWRUDHVNl88DLbV5x9W9L3JH1Q92AABlflFH2lpBdtn338LyLi1Vqn\nAlDEvIFHxBFJ325gFgCF8WMyIDECBxIjcCAxAgcSI3AgMQIHEiNwIDECBxJj66IOa/K5Nbl1UZN6\nvV7bI7SKIziQGIEDiRE4kBiBA4kROJAYgQOJETiQGIEDiRE4kFilwG0vtb3X9iHbU7ZvqnswAIOr\neqnqzyS9GhE/tH2JpEtrnAlAIfMGbvtKSTdLGpWkiDgt6XS9YwEoocop+rWSZiTtsv2+7Z39+6MD\n6LgqgV8k6UZJT0TEekmfS3rk/AfZ3m570vbkzMxM4TEBXIgqgU9Lmo6Id/vv79Vs8P+FrYuA7pk3\n8Ij4RNJR2+v6H7pV0oe1TgWgiKqvoj8oaU//FfQjku6vbyQApVQKPCIOSBqpeRYAhXElG5AYgQOJ\nETiQGIEDiRE4kBiBA4kROJAYgQOJETiQ2KLfm2xsbKztEWrT5N5kTa51yy23NLZW5v8+quAIDiRG\n4EBiBA4kRuBAYgQOJEbgQGIEDiRG4EBiBA4kNm/gttfZPnDOn09tf7UvDwIWiXkvVY2IjyTdIEm2\nhyT9XdKLNc8FoICFnqLfKumvEfG3OoYBUNZCA98q6dm5PsHWRUD3VA68v+nBnZJ+Ndfn2boI6J6F\nHMFvk7Q/Iv5R1zAAylpI4Nv0f07PAXRTpcBtXyrpu5JeqHccACVV3ZvsX5KW1TwLgMK4kg1IjMCB\nxAgcSIzAgcQIHEiMwIHECBxIjMCBxBwR5b+oPSNpob9SulzSieLDdEPW58bzas/aiJj3t7pqCfxC\n2J6MiJG256hD1ufG8+o+TtGBxAgcSKxLgT/Z9gA1yvrceF4d15nvwQGU16UjOIDCOhG47S22P7J9\n2PYjbc9Tgu01tt+0PWX7oO2H2p6pJNtDtt+3/XLbs5Rke6ntvbYP9f/ubmp7pkG0forev9f6XzR7\nx5hpSe9J2hYRH7Y62IBsXyXpqojYb/sKSfsk/WCxP6+zbP9Y0oikKyPijrbnKcX2bkm/jYid/RuN\nXhoRJ9ue60J14Qi+QdLhiDgSEaclPSfprpZnGlhEfBwR+/tvn5I0JWlVu1OVYXu1pNsl7Wx7lpJs\nXynpZklPSVJEnF7McUvdCHyVpKPnvD+tJCGcZXtY0npJ77Y7STE7JD0s6cu2BynsWkkzknb1v/3Y\nafuytocaRBcC9xwfS/PSvu3LJT0vaSwiPm17nkHZvkPS8YjY1/YsNbhI0o2SnoiI9ZI+l7SoXxPq\nQuDTktac8/5qScdamqUo2xdrNu49EZHljrQbJd1pu6fZb6c2236m3ZGKmZY0HRFnz7T2ajb4RasL\ngb8n6Trb1/Rf1Ngq6aWWZxqYbWv2e7mpiHi87XlKiYhHI2J1RAxr9u/qjYi4p+WxioiITyQdtb2u\n/6FbJS3qF0Ur3Ta5ThFxxvYDkl6TNCTp6Yg42PJYJWyUdK+kP9s+0P/YTyPilRZnwvwelLSnf7A5\nIun+lucZSOs/JgNQny6cogOoCYEDiRE4kBiBA4kROJAYgQOJETiQGIEDif0HVS6tDxH36PgAAAAA\nSUVORK5CYII=\n",
      "text/plain": [
       "<matplotlib.figure.Figure at 0x111310710>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "plt.imshow(digits.images[-1], cmap=plt.cm.gray_r)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "###### Unsupervised learning"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 120,
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "from sklearn.cluster import KMeans\n",
    "from sklearn.datasets import load_iris\n",
    "from sklearn.decomposition import PCA\n",
    "from sklearn.preprocessing import StandardScaler\n",
    "\n",
    "np.random.seed(5)\n",
    "\n",
    "iris = datasets.load_iris()\n",
    "X = iris.data\n",
    "y = iris.target\n",
    "\n",
    "# rescale the data\n",
    "scaler = StandardScaler()\n",
    "X = scaler.fit_transform(X)\n",
    "\n",
    "# decompose\n",
    "pca = PCA(n_components=2)\n",
    "pca.fit(X)\n",
    "X_reduced = pca.transform(X)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 122,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [
    {
     "data": {
      "image/png": "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\nRK5CYII=\n",
      "text/plain": [
       "<matplotlib.figure.Figure at 0x10388b128>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# fit k-means\n",
    "kmeans = KMeans(n_clusters=3)\n",
    "kmeans.fit(X)\n",
    "clusters = kmeans.labels_\n",
    "# kmeans.predict(new_data)\n",
    "\n",
    "plt.figure(figsize=(14,4))\n",
    "plt.subplot(1,2,1)\n",
    "plt.scatter(X_reduced[:,0],X_reduced[:,1], c=clusters)\n",
    "plt.title('K-means', fontsize=14)\n",
    "plt.subplot(1,2,2)\n",
    "plt.scatter(X_reduced[:,0], X_reduced[:,1], c=y)\n",
    "plt.title('Ground truth', fontsize=14)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "###### Model selection and evaluation tools"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 99,
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "from sklearn.model_selection import train_test_split\n",
    "from sklearn.model_selection import GridSearchCV\n",
    "from sklearn.metrics import classification_report\n",
    "from sklearn.svm import SVC\n",
    "\n",
    "n_samples = len(digits.images)\n",
    "X = digits.images.reshape((n_samples, -1))\n",
    "y = digits.target\n",
    "\n",
    "X_train, X_test, y_train, y_test = train_test_split(\n",
    "    X, y, test_size=0.2, random_state=0)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 100,
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "param_grid = [{'kernel': ['rbf'], 'gamma': [1e-3, 1e-4], 'C': [1, 10, 100, 1000]},\n",
    "              {'kernel': ['linear'], 'C': [1, 10, 100, 1000]}]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 113,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "GridSearchCV(cv=5, error_score='raise',\n",
       "       estimator=SVC(C=1.0, cache_size=200, class_weight=None, coef0=0.0,\n",
       "  decision_function_shape='ovr', degree=3, gamma='auto', kernel='rbf',\n",
       "  max_iter=-1, probability=False, random_state=None, shrinking=True,\n",
       "  tol=0.001, verbose=False),\n",
       "       fit_params=None, iid=True, n_jobs=1,\n",
       "       param_grid=[{'kernel': ['rbf'], 'gamma': [0.001, 0.0001], 'C': [1, 10, 100, 1000]}, {'kernel': ['linear'], 'C': [1, 10, 100, 1000]}],\n",
       "       pre_dispatch='2*n_jobs', refit=True, return_train_score='warn',\n",
       "       scoring='f1_micro', verbose=0)"
      ]
     },
     "execution_count": 113,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "clf = GridSearchCV(SVC(), param_grid, cv=5, scoring='f1_micro')\n",
    "clf.fit(X_train, y_train)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 114,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'C': 1, 'gamma': 0.001, 'kernel': 'rbf'}"
      ]
     },
     "execution_count": 114,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "clf.best_params_"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 115,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.9902574808629089"
      ]
     },
     "execution_count": 115,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "clf.best_score_"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 116,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "             precision    recall  f1-score   support\n",
      "\n",
      "          0       1.00      1.00      1.00        27\n",
      "          1       0.97      1.00      0.99        35\n",
      "          2       1.00      1.00      1.00        36\n",
      "          3       1.00      1.00      1.00        29\n",
      "          4       1.00      1.00      1.00        30\n",
      "          5       0.97      0.97      0.97        40\n",
      "          6       1.00      1.00      1.00        44\n",
      "          7       1.00      1.00      1.00        39\n",
      "          8       1.00      0.97      0.99        39\n",
      "          9       0.98      0.98      0.98        41\n",
      "\n",
      "avg / total       0.99      0.99      0.99       360\n",
      "\n"
     ]
    }
   ],
   "source": [
    "y_true, y_pred = y_test, clf.predict(X_test)\n",
    "print(classification_report(y_true, y_pred))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Sklearn provides many more model selection and evaluation tools: cross validation tools, data splitting tools (`GroupShuffleSplit`, `TimeSeriesSplit`), randomized grid search, various metrics, ROC curves, precision/recall curves, learning/validation curves etc."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "![title](figures/sklearn_docs.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Typical supervised learning workflow:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "![title](figures/workflow1.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "![title](figures/workflow2.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Possible problems:\n",
    "* a lot of hyperparams to tune -> fugly code with embedded loops\n",
    "* data leakage, eg: standarizing on test data when doing cross validation\n",
    "* having to manually string a lot of transformers together"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Some pseudocode example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "input_data\n",
    "x, y = transform_1(input_data)\n",
    "x, y = transform_2(x, y)\n",
    "etc\n",
    "x, y = transform_n(x, y)\n",
    "model.fit(x,y)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Example of badly written grid search on such a string of transformations:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "![title](figures/bad_code.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### SOLUTION\n",
    "*Pipelines* to the rescue!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "From sklearn's documentation:\n",
    "\n",
    "Pipeline can be used to chain multiple estimators into one. This is useful as there is often a fixed sequence of steps in processing the data, for example feature selection, normalization and classification. Pipeline serves three purposes here:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "* **Convenience and encapsulation** - You only have to call `fit` and `predict` once on your data to fit a whole sequence of estimators.\n",
    "* **Joint parameter selection** - You can grid search over parameters of all estimators in the pipeline at once.\n",
    "* **Safety** - Pipelines help avoid leaking statistics from your test data into the trained model in cross-validation, by ensuring that the same samples are used to train the transformers and predictors.\n",
    "\n",
    "**All estimators in a pipeline, except the last one, must be transformers (i.e. must have a `transform` method). The last estimator may be any type (transformer, classifier, etc.).**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Simple example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Pipeline(memory=None,\n",
       "     steps=[('reduce_dim', PCA(copy=True, iterated_power='auto', n_components=None, random_state=None,\n",
       "  svd_solver='auto', tol=0.0, whiten=False)), ('clf', SVC(C=1.0, cache_size=200, class_weight=None, coef0=0.0,\n",
       "  decision_function_shape='ovr', degree=3, gamma='auto', kernel='rbf',\n",
       "  max_iter=-1, probability=False, random_state=None, shrinking=True,\n",
       "  tol=0.001, verbose=False))])"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from sklearn.pipeline import Pipeline\n",
    "from sklearn.decomposition import PCA\n",
    "from sklearn.svm import SVC\n",
    "\n",
    "estimators = [('reduce_dim', PCA()), ('clf', SVC())]\n",
    "pipe = Pipeline(estimators)\n",
    "pipe"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Another tool to create piplines:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Pipeline(memory=None,\n",
       "     steps=[('binarizer', Binarizer(copy=True, threshold=0.0)), ('multinomialnb', MultinomialNB(alpha=1.0, class_prior=None, fit_prior=True))])"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from sklearn.pipeline import make_pipeline\n",
    "from sklearn.naive_bayes import MultinomialNB\n",
    "from sklearn.preprocessing import Binarizer\n",
    "make_pipeline(Binarizer(), MultinomialNB()) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Accessing estimators and their hyperparameters:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('reduce_dim',\n",
       " PCA(copy=True, iterated_power='auto', n_components=None, random_state=None,\n",
       "   svd_solver='auto', tol=0.0, whiten=False))"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pipe.steps[0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "PCA(copy=True, iterated_power='auto', n_components=None, random_state=None,\n",
       "  svd_solver='auto', tol=0.0, whiten=False)"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pipe.named_steps['reduce_dim']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'auto'"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pipe.named_steps['reduce_dim'].svd_solver"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Parameters of the estimators in the pipeline can be accessed using the <estimator>__<parameter> syntax:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "SVC(C=1.0, cache_size=200, class_weight=None, coef0=0.0,\n",
       "  decision_function_shape='ovr', degree=3, gamma='auto', kernel='rbf',\n",
       "  max_iter=-1, probability=False, random_state=None, shrinking=True,\n",
       "  tol=0.001, verbose=False)"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pipe.get_params()['clf']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Pipeline(memory=None,\n",
       "     steps=[('reduce_dim', PCA(copy=True, iterated_power='auto', n_components=None, random_state=None,\n",
       "  svd_solver='auto', tol=0.0, whiten=False)), ('clf', SVC(C=10, cache_size=200, class_weight=None, coef0=0.0,\n",
       "  decision_function_shape='ovr', degree=3, gamma='auto', kernel='rbf',\n",
       "  max_iter=-1, probability=False, random_state=None, shrinking=True,\n",
       "  tol=0.001, verbose=False))])"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pipe.set_params(clf__C=10) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Grid search with a pipeline\n",
    "This notation is mostly used for doing grid searches."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "GridSearchCV(cv=None, error_score='raise',\n",
       "       estimator=Pipeline(memory=None,\n",
       "     steps=[('reduce_dim', PCA(copy=True, iterated_power='auto', n_components=None, random_state=None,\n",
       "  svd_solver='auto', tol=0.0, whiten=False)), ('clf', SVC(C=10, cache_size=200, class_weight=None, coef0=0.0,\n",
       "  decision_function_shape='ovr', degree=3, gamma='auto', kernel='rbf',\n",
       "  max_iter=-1, probability=False, random_state=None, shrinking=True,\n",
       "  tol=0.001, verbose=False))]),\n",
       "       fit_params=None, iid=True, n_jobs=1,\n",
       "       param_grid={'reduce_dim__n_components': [2, 5, 10], 'clf__C': [0.1, 10, 100]},\n",
       "       pre_dispatch='2*n_jobs', refit=True, return_train_score='warn',\n",
       "       scoring=None, verbose=0)"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from sklearn.model_selection import GridSearchCV\n",
    "param_grid = dict(reduce_dim__n_components=[2, 5, 10], clf__C=[0.1, 10, 100])\n",
    "grid_search = GridSearchCV(pipe, param_grid=param_grid)\n",
    "grid_search"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "We can even substitute individual steps of the pipeline, and ignore them if necessary by setting them to `None`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "from sklearn.linear_model import LogisticRegression\n",
    "param_grid = dict(reduce_dim=[None, PCA(5), PCA(10)],\n",
    "                  clf=[SVC(), LogisticRegression()],\n",
    "                   clf__C=[0.1, 10, 100])\n",
    "grid_search = GridSearchCV(pipe, param_grid=param_grid)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Calling `fit` on the pipeline is the same as calling `fit` on each estimator in turn, transform the input and pass it on to the next step. The pipeline has all the methods that the last estimator in the pipeline has, i.e. if the last estimator is a classifier, the Pipeline can be used as a classifier. If the last estimator is a transformer, again, so is the pipeline."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Caching transformers"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Fitting transformers may be computationally expensive. With its memory parameter set, Pipeline will cache each transformer after calling `fit`. A typical example is the case of a grid search in which the transformers can be fitted only once and reused for each configuration."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "The parameter `memory` is needed in order to cache the transformers. `memory` can be either a string containing the directory where to cache the transformers or a `joblib.Memory` object (see https://pythonhosted.org/joblib/memory.html for details):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Pipeline(memory='/var/folders/3p/6tvd1q517d3_bm8z5fbtd4p80000gn/T/tmpjfztovcu',\n",
       "     steps=[('reduce_dim', PCA(copy=True, iterated_power='auto', n_components=None, random_state=None,\n",
       "  svd_solver='auto', tol=0.0, whiten=False)), ('clf', SVC(C=1.0, cache_size=200, class_weight=None, coef0=0.0,\n",
       "  decision_function_shape='ovr', degree=3, gamma='auto', kernel='rbf',\n",
       "  max_iter=-1, probability=False, random_state=None, shrinking=True,\n",
       "  tol=0.001, verbose=False))])"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from tempfile import mkdtemp\n",
    "from shutil import rmtree\n",
    "from sklearn.decomposition import PCA\n",
    "from sklearn.svm import SVC\n",
    "from sklearn.pipeline import Pipeline\n",
    "estimators = [('reduce_dim', PCA()), ('clf', SVC())]\n",
    "cachedir = mkdtemp()\n",
    "pipe = Pipeline(estimators, memory=cachedir)\n",
    "pipe"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "rmtree(cachedir)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Warning! Side effect of caching transformers"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Inspecting a fitted pipeline with caching disabled:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Pipeline(memory=None,\n",
       "     steps=[('reduce_dim', PCA(copy=True, iterated_power='auto', n_components=None, random_state=None,\n",
       "  svd_solver='auto', tol=0.0, whiten=False)), ('clf', SVC(C=1.0, cache_size=200, class_weight=None, coef0=0.0,\n",
       "  decision_function_shape='ovr', degree=3, gamma='auto', kernel='rbf',\n",
       "  max_iter=-1, probability=False, random_state=None, shrinking=True,\n",
       "  tol=0.001, verbose=False))])"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from sklearn.datasets import load_digits\n",
    "digits = load_digits()\n",
    "pca1 = PCA()\n",
    "svm1 = SVC()\n",
    "pipe = Pipeline([('reduce_dim', pca1), ('clf', svm1)])\n",
    "pipe.fit(digits.data, digits.target)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[[ -1.77484909e-19  -1.73094651e-02  -2.23428835e-01 ...,  -8.94184677e-02\n",
      "   -3.65977111e-02  -1.14684954e-02]\n",
      " [  3.27805401e-18  -1.01064569e-02  -4.90849204e-02 ...,   1.76697117e-01\n",
      "    1.94547053e-02  -6.69693895e-03]\n",
      " [ -1.68358559e-18   1.83420720e-02   1.26475543e-01 ...,   2.32084163e-01\n",
      "    1.67026563e-01   3.48043832e-02]\n",
      " ..., \n",
      " [ -0.00000000e+00   1.24542422e-16   3.75737130e-16 ...,   1.10631603e-16\n",
      "   -5.75432090e-17  -7.40228347e-17]\n",
      " [  0.00000000e+00   1.90890701e-16  -7.82648298e-17 ...,  -4.23467114e-18\n",
      "   -7.42124207e-17   1.32700914e-16]\n",
      " [  1.00000000e+00  -1.68983002e-17   5.73338351e-18 ...,   8.66631300e-18\n",
      "   -1.57615962e-17   4.07058917e-18]]\n"
     ]
    }
   ],
   "source": [
    "# The pca instance can be inspected directly\n",
    "print(pca1.components_)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Enabling caching triggers a clone of the transformers before fitting. Therefore, the transformer instance given to the pipeline cannot be inspected directly. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Pipeline(memory='/var/folders/3p/6tvd1q517d3_bm8z5fbtd4p80000gn/T/tmp4_5xekb7',\n",
       "     steps=[('reduce_dim', PCA(copy=True, iterated_power='auto', n_components=None, random_state=None,\n",
       "  svd_solver='auto', tol=0.0, whiten=False)), ('clf', SVC(C=1.0, cache_size=200, class_weight=None, coef0=0.0,\n",
       "  decision_function_shape='ovr', degree=3, gamma='auto', kernel='rbf',\n",
       "  max_iter=-1, probability=False, random_state=None, shrinking=True,\n",
       "  tol=0.001, verbose=False))])"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "cachedir = mkdtemp()\n",
    "pca2 = PCA()\n",
    "svm2 = SVC()\n",
    "cached_pipe = Pipeline([('reduce_dim', pca2), ('clf', svm2)],\n",
    "                         memory=cachedir)\n",
    "cached_pipe.fit(digits.data, digits.target)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [
    {
     "ename": "AttributeError",
     "evalue": "'PCA' object has no attribute 'components_'",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mAttributeError\u001b[0m                            Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-24-b552e51a0fc3>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m()\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0mprint\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mpca2\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mcomponents_\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;31mAttributeError\u001b[0m: 'PCA' object has no attribute 'components_'"
     ]
    }
   ],
   "source": [
    "print(pca2.components_)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[[ -1.77484909e-19  -1.73094651e-02  -2.23428835e-01 ...,  -8.94184677e-02\n",
      "   -3.65977111e-02  -1.14684954e-02]\n",
      " [  3.27805401e-18  -1.01064569e-02  -4.90849204e-02 ...,   1.76697117e-01\n",
      "    1.94547053e-02  -6.69693895e-03]\n",
      " [ -1.68358559e-18   1.83420720e-02   1.26475543e-01 ...,   2.32084163e-01\n",
      "    1.67026563e-01   3.48043832e-02]\n",
      " ..., \n",
      " [ -0.00000000e+00   1.24542422e-16   3.75737130e-16 ...,   1.10631603e-16\n",
      "   -5.75432090e-17  -7.40228347e-17]\n",
      " [  0.00000000e+00   1.90890701e-16  -7.82648298e-17 ...,  -4.23467114e-18\n",
      "   -7.42124207e-17   1.32700914e-16]\n",
      " [  1.00000000e+00  -1.68983002e-17   5.73338351e-18 ...,   8.66631300e-18\n",
      "   -1.57615962e-17   4.07058917e-18]]\n"
     ]
    }
   ],
   "source": [
    "print(cached_pipe.named_steps['reduce_dim'].components_)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "rmtree(cachedir)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "So far our workflow has been linear.\n",
    "\n",
    "*input --> transform_1 -- > transform_2 --> ... ---> transform_n ---> estimator*\n",
    "\n",
    "Sklearn supports concatenation of multiple transformers executed in parallel."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "![title](figures/workflow3.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Feature Union"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "`FeatureUnion` combines several transformer objects into a new transformer that combines their output. A `FeatureUnion` takes a list of transformer objects. During fitting, each of these is fit to the data independently. For transforming data, the transformers are applied in parallel, and the sample vectors they output are concatenated end-to-end into larger vectors."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "`FeatureUnion` serves the same purposes as Pipeline - convenience and joint parameter estimation and validation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Note: A `FeatureUnion` has no way of checking whether two transformers might produce identical features. It only produces a union when the feature sets are disjoint, and making sure they are is the caller’s responsibility."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Usage"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "FeatureUnion(n_jobs=1,\n",
       "       transformer_list=[('linear_pca', PCA(copy=True, iterated_power='auto', n_components=None, random_state=None,\n",
       "  svd_solver='auto', tol=0.0, whiten=False)), ('kernel_pca', KernelPCA(alpha=1.0, coef0=1, copy_X=True, degree=3, eigen_solver='auto',\n",
       "     fit_inverse_transform=False, gamma=None, kernel='linear',\n",
       "     kernel_params=None, max_iter=None, n_components=None, n_jobs=1,\n",
       "     random_state=None, remove_zero_eig=False, tol=0))],\n",
       "       transformer_weights=None)"
      ]
     },
     "execution_count": 27,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from sklearn.pipeline import FeatureUnion\n",
    "from sklearn.decomposition import PCA\n",
    "from sklearn.decomposition import KernelPCA\n",
    "estimators = [('linear_pca', PCA()), ('kernel_pca', KernelPCA())]\n",
    "combined = FeatureUnion(estimators)\n",
    "combined "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Custom transformers & estimators"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Scikit-learn comes equipped with multiple in-built data transformers:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "* `Binarizer`\n",
    "* `KernelCenterer`\n",
    "* `MaxAbsScaler`\n",
    "* `MinMaxScaler`\n",
    "* `Normalizer`\n",
    "* `OneHotEncoder`\n",
    "* `PolynomialFeatures`\n",
    "* `StandardScaler`\n",
    "\n",
    "And many others."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "However... more often than not, these transformations are not enough and we need to preprocess our data in a custom way. Sklearn provides easy integration of custom transformations (and estimators) into pipelines, giving us ability to use the full power of sklearn's API with our custom workflow."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Let's start simple. Suppose we want to apply the same custom function to the entire dataset X. We can use the `FunctionTransformer`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 0.        ,  0.69314718],\n",
       "       [ 1.09861229,  1.38629436]])"
      ]
     },
     "execution_count": 28,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import numpy as np\n",
    "from sklearn.preprocessing import FunctionTransformer\n",
    "transformer = FunctionTransformer(np.log1p)\n",
    "X = np.array([[0, 1], [2, 3]])\n",
    "transformer.transform(X)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "*Note*: if `lambda` is used as the callable, then the resulting transformer is not pickleable!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "If we want to go fancier than that, we can build one of the following types of objects and package them into a sklearn API:\n",
    "* `Transformer`\n",
    "* `Classifier`\n",
    "* `Regressor`\n",
    "* `Clustering`\n",
    "\n",
    "Each of them has a corresponding mixin class. These are `TransformerMixin`, `ClassifierMixin`, `RegressorMixin`, `ClusterMixin`, respectively."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Transformer"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "from sklearn.base import BaseEstimator, TransformerMixin\n",
    "\n",
    "def MyTransformerm(BaseEstimator, TransformerMixin):\n",
    "    \n",
    "    def __init__(self, arg1=1, arg2=2):\n",
    "        # pass arguments, do no more than that\n",
    "        self.arg1 = arg1\n",
    "        self.arg2 = arg2\n",
    "        pass\n",
    "        \n",
    "    def fit(self, X, y=None):\n",
    "        # do something if needed\n",
    "        return self # this is standard in sklearn\n",
    "    \n",
    "    def transform(self, X):\n",
    "        # real meat here\n",
    "        pass"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "* `BaseEstimator` provides `get_params` and `set_params` methods for free.\n",
    "* `TransformerMixin` combines `fit` and `transform` methods into a `fit_transform` method. It should also be included for clarity, to indicate that your class is a transformer\n",
    "* add `y=None` to list of args of `fit` method even if no `y` is needed. This ensures `GridSearch` can work properly"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Classifier/Regressor"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "from sklearn.base import BaseEstimator, ClassifierMixin # RegressorMixin for regressors\n",
    "\n",
    "def MyClassifier(BaseEstimator, ClassifierMixin):\n",
    "    \n",
    "    def __init__(self, arg1=1, arg2=2):\n",
    "        # pass arguments\n",
    "        self.arg1 = arg1\n",
    "        self.arg2 = arg2\n",
    "        pass\n",
    "    \n",
    "    def fit(self, X, y):\n",
    "        # do the fitting, but return self\n",
    "        return self \n",
    "    \n",
    "    def predict(self, X):\n",
    "        # do the prediction\n",
    "        pass\n",
    "    \n",
    "    def score(self, X, y=None):\n",
    "        # add custom scoring if necessary\n",
    "        pass"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### More concrete example of custom classifier: \n",
    "Bayesian generative classification with KDE"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "from sklearn.base import BaseEstimator, ClassifierMixin\n",
    "from sklearn.neighbors import KernelDensity\n",
    "\n",
    "class KDEClassifier(BaseEstimator, ClassifierMixin):\n",
    "    \"\"\"Bayesian generative classification based on KDE\n",
    "    \n",
    "    Parameters\n",
    "    ----------\n",
    "    bandwidth : float\n",
    "        the kernel bandwidth within each class\n",
    "    kernel : str\n",
    "        the kernel name, passed to KernelDensity\n",
    "    \"\"\"\n",
    "    def __init__(self, bandwidth=1.0, kernel='gaussian'):\n",
    "        self.bandwidth = bandwidth\n",
    "        self.kernel = kernel\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "    def fit(self, X, y):\n",
    "        self.classes_ = np.sort(np.unique(y))\n",
    "        training_sets = [X[y == yi] for yi in self.classes_]\n",
    "        self.models_ = [KernelDensity(bandwidth=self.bandwidth,\n",
    "                                      kernel=self.kernel).fit(Xi)\n",
    "                        for Xi in training_sets]\n",
    "        self.logpriors_ = [np.log(Xi.shape[0] / X.shape[0])\n",
    "                           for Xi in training_sets]\n",
    "        return self\n",
    "        \n",
    "    def predict_proba(self, X):\n",
    "        logprobs = np.array([model.score_samples(X)\n",
    "                             for model in self.models_]).T\n",
    "        result = np.exp(logprobs + self.logpriors_)\n",
    "        return result / result.sum(1, keepdims=True)\n",
    "        \n",
    "    def predict(self, X):\n",
    "        return self.classes_[np.argmax(self.predict_proba(X), 1)]\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "*Source: * https://jakevdp.github.io/PythonDataScienceHandbook/05.13-kernel-density-estimation.html"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### General rules for making custom estimators"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "There are several internal rules of scikit learn you should obey when implementing your own estimators.\n",
    "You can check if you estimator obeyes these rules by using `sklearn.utils.estimator_checks.check_estimator`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "from sklearn.utils.estimator_checks import check_estimator\n",
    "from sklearn.ensemble import RandomForestClassifier\n",
    "check_estimator(RandomForestClassifier) #pass"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### `__init__` method:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "* The object’s `__init__` method might accept constants as arguments that determine the estimator’s behavior (like the C constant in SVMs). It should not, however, take the actual training data as an argument, as this is left to the fit() method\n",
    "* The arguments accepted should all be keyword arguments with a default value. In other words, a user should be able to instantiate an estimator without passing any arguments to it.\n",
    "* In addition, every keyword argument accepted by `__init__` should correspond to an attribute on the instance. Scikit-learn relies on this to find the relevant attributes to set on an estimator when doing model selection.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "To summarise, `__init__` method should look like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "def __init__(self, param1=1, param2=2):\n",
    "    self.param1 = param1\n",
    "    self.param2 = param2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Moreover, there should be no logic, not even input validation, and the parameters should not be changed. The corresponding logic should be put where the parameters are used, typically in fit. The following is wrong:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "def __init__(self, param1=1, param2=2, param3=3):\n",
    "    # WRONG: parameters should not be modified\n",
    "    if param1 > 1:\n",
    "        param2 += 1\n",
    "    self.param1 = param1\n",
    "    # WRONG: the object's attributes should have exactly the name of\n",
    "    # the argument in the constructor\n",
    "    self.param3 = param2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "The reason for postponing the validation is that the same validation would have to be performed in `set_params`, which is used in algorithms like `GridSearchCV`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### The `fit` method\n",
    "* `fit` method should always, return `self` \n",
    "* Attributes that have been estimated from the data must always have a name ending with trailing underscore, for example the coefficients of some regression estimator would be stored in a `coef_` attribute after `fit` has been called\n",
    "* The last-mentioned attributes are expected to be overridden when you call `fit` a second time without taking any previous value into account: `fit` should be idempotent."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Inheritance\n",
    "\n",
    "Scikit-learn tends to use “duck typing”, so building an estimator which follows the API suffices for compatibility, without needing to inherit from or even import any scikit-learn classes.\n",
    "\n",
    "However, if a dependency on scikit-learn is acceptable in your code, you can prevent a lot of boilerplate code by deriving a class from `BaseEstimator` and optionally the mixin classes in `sklearn.base`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Cloning\n",
    "\n",
    "For use with the `model_selection` module, an estimator must support the `base.clone` function to replicate an estimator. This can be done by providing a `get_params` method. If `get_params` is present, then `clone(estimator)` will be an instance of `type(estimator)` on which `set_params` has been called with clones of the result of `estimator.get_params()`.\n",
    "\n",
    "Objects that do not provide this method will be deep-copied (using the Python standard function `copy.deepcopy`) if `safe=False` is passed to clone."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Full scikit-learn guidlines to extending their API can be found at http://scikit-learn.org/dev/developers/contributing.html#rolling-your-own-estimator"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### One last elaborate example of a pipeline"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "pipeline = Pipeline([\n",
    "    # Extract the subject & body\n",
    "    ('subjectbody', SubjectBodyExtractor()),\n",
    "\n",
    "    # Use FeatureUnion to combine the features from subject and body\n",
    "    ('union', FeatureUnion(\n",
    "        transformer_list=[\n",
    "\n",
    "            # Pipeline for pulling features from the post's subject line\n",
    "            ('subject', Pipeline([\n",
    "                ('selector', ItemSelector(key='subject')),\n",
    "                ('tfidf', TfidfVectorizer(min_df=50)),\n",
    "            ])),\n",
    "\n",
    "            # Pipeline for standard bag-of-words model for body\n",
    "            ('body_bow', Pipeline([\n",
    "                ('selector', ItemSelector(key='body')),\n",
    "                ('tfidf', TfidfVectorizer()),\n",
    "                ('best', TruncatedSVD(n_components=50)),\n",
    "            ])),\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "\n",
    "            # Pipeline for pulling ad hoc features from post's body\n",
    "            ('body_stats', Pipeline([\n",
    "                ('selector', ItemSelector(key='body')),\n",
    "                ('stats', TextStats()),  # returns a list of dicts\n",
    "                ('vect', DictVectorizer()),  # list of dicts -> feature matrix\n",
    "            ])),\n",
    "\n",
    "        ],\n",
    "\n",
    "        # weight components in FeatureUnion\n",
    "        transformer_weights={\n",
    "            'subject': 0.8,\n",
    "            'body_bow': 0.5,\n",
    "            'body_stats': 1.0,\n",
    "        },\n",
    "    )),\n",
    "\n",
    "    # Use a SVC classifier on the combined features\n",
    "    ('svc', SVC(kernel='linear')),\n",
    "])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "To access, say, `n_components` attributed of `TruncatedSVD`, we can use the following:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "'union__body_bow__best__n_components'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "This way we can create a dict for `GridSearchCV` of all hyperparamters of interest and search them all by calling a single `fit` method."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# THANK YOU!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Sources:\n",
    "* scikit-learn official documentation\n",
    "* http://scikit-learn.org/stable/auto_examples/hetero_feature_union.html#example-hetero-feature-union-py\n",
    "* http://danielhnyk.cz/creating-your-own-estimator-scikit-learn/\n",
    "* https://jakevdp.github.io/PythonDataScienceHandbook/05.13-kernel-density-estimation.html\n",
    "* http://zacstewart.com/2014/08/05/pipelines-of-featureunions-of-pipelines.html"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Slideshow",
  "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.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}