tutorials/1-getting-started.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Getting started with steps\n",
    "\n",
    "This notebook shows how to **create** steps, **fit** them to data, **transform** new data and take advantage of persistence"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%load_ext autoreload\n",
    "%autoreload 2\n",
    "\n",
    "import numpy as np\n",
    "import matplotlib.pyplot as plt\n",
    "%matplotlib inline\n",
    "\n",
    "from steppy.base import Step, BaseTransformer\n",
    "\n",
    "EXPERIMENT_DIR = './ex1'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import shutil\n",
    "\n",
    "# By default pipelines will try to load previously trained models so we delete the cache to ba sure we're starting from scratch\n",
    "shutil.rmtree(EXPERIMENT_DIR, ignore_errors=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Grabbing some data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We'll import a dataset from scikit-learn for our experiments and divide it into training and test sets"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from sklearn.datasets import load_digits\n",
    "from sklearn.model_selection import train_test_split\n",
    "\n",
    "digits = load_digits()\n",
    "X_digits, y_digits = digits.data, digits.target\n",
    "\n",
    "X_train, X_test, y_train, y_test = train_test_split(X_digits, y_digits, test_size=0.2, stratify=y_digits, random_state=42)\n",
    "\n",
    "print('{} samples for training'.format(len(y_train)))\n",
    "print('{} samples for test'.format(len(y_test)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Steps communicate data between each other with plain **Python dictionaries**. This makes it easy to pass collections of **arbitrary data types** (Numpy arrays, Pandas dataframes, etc.). The basic structure is as follows (you can get much more fancy but we leave that to the next example)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "data_train = {'input':\n",
    "                {\n",
    "                     'X': X_train,\n",
    "                     'y': y_train,\n",
    "                }\n",
    "            }\n",
    "\n",
    "data_test = {'input':\n",
    "                {\n",
    "                     'X': X_test,\n",
    "                     'y': y_test,\n",
    "                }\n",
    "            }"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Creating steps"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The main component of a step is a transformer. You just have to define a class following a **simple API** of ` BaseTransformer` and then it's up to you to be as creative as you want!\n",
    "\n",
    "... or you can just **wrap you favorite Scikit-learn estimator** like we do here:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from sklearn.ensemble import RandomForestClassifier\n",
    "from sklearn.externals import joblib\n",
    "\n",
    "class RandomForestTransformer(BaseTransformer):\n",
    "    def __init__(self):\n",
    "        self.estimator = RandomForestClassifier()\n",
    "        \n",
    "    def fit(self, X, y):\n",
    "        self.estimator.fit(X, y)\n",
    "        return self\n",
    "\n",
    "    def transform(self, X, **kwargs):\n",
    "        y_pred  = self.estimator.predict(X)\n",
    "        return {'y_pred': y_pred}\n",
    "    \n",
    "    def persist(self, filepath):\n",
    "        joblib.dump(self.estimator, filepath)\n",
    "        \n",
    "    def load(self, filepath):\n",
    "        self.estimator = joblib.load(filepath)\n",
    "        return self"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So what does the transformer do? It must be able to:\n",
    "* **initialize** itself\n",
    "* **fit** and **transform** the incoming data prepared by the adapter; when transforming, the result should be returned as a **dictionary** that can be **passed on to the next step**\n",
    "* **persist** and **load** its parameters; this is handy when you're trying to avoid re-computing things over and over.\n",
    "\n",
    "See how flexible this is? You can just as easily wrap your Keras or Pytorch models."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now let's turn our transformer into a step:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "classifier_step = Step(name='classifier',\n",
    "                       transformer=RandomForestTransformer(),\n",
    "                       input_data=['input'],\n",
    "                       experiment_directory=EXPERIMENT_DIR,\n",
    "                       is_fittable=True\n",
    "                       )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And that's our one-step pipeline finished. You can visualize it too:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "classifier_step"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is just about the simplest pipeline you can imagine. Now let's train it!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Training\n",
    "\n",
    "Training a pipeline is a one-liner:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "preds_train = classifier_step.fit_transform(data_train);"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's see how well we do on our training data:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from sklearn.metrics import accuracy_score\n",
    "acc_train = accuracy_score(data_train['input']['y'], preds_train['y_pred'])\n",
    "print('Training accuracy = {:.4f}'.format(acc_train))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Generating test predictions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Running test data through our pipeline is a one-liner too:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "preds_test = classifier_step.transform(data_test)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "How good is our test score?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "acc_test = accuracy_score(data_test['input']['y'], preds_test['y_pred'])\n",
    "print('Test accuracy = {:.4f}'.format(acc_test))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "That's pretty good for a first attempt!\n",
    "\n",
    "Let's have a look at some predictions to make sure they're sensible"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fix, axs = plt.subplots(4, 8, figsize=(10, 6))\n",
    "for i, ax in enumerate(axs.ravel()):\n",
    "    ax.imshow(data_test['input']['X'][i].reshape(8, 8), cmap='gray')\n",
    "    ax.axis('off')\n",
    "    ax.set_title('pred = {}'.format(preds_test['y_pred'][i]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And that's about it for a start! As you can see:\n",
    "* It's easy to create steps by inheriting from `BaseTransformer`\n",
    "* Transferring data between steps with Python dicts gives you a lot of flexibility\n",
    "* Steps wrap easily around Scikit-learn estimators\n",
    "* You can display a graph showing the structure of your pipeline\n",
    "* Training and testing are pretty much one-liners\n",
    "\n",
    "At this point it may seem like a lot of work for not much benefit but once we start moving towards more complex pipelines, the reasoning behind all the components will become more clear. Have a look at the next notebook for a more advanced, multi-step pipeline!"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}