Labelled Images to HDF5.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Demo on how to create a HDF5 dataset from raw images\n",
    "\n",
    "### Contents\n",
    "\n",
    "1. Prepare your data\n",
    "2. Define all expected common parameters\n",
    "3. Call generate_h5(...) to generate HDF5 dataset file\n",
    "4. Call load_all_data(...) to extract the data as np.array objects into your python env\n",
    "5. Check on the shape or content of the various np.array\n",
    "6. Check to visualize a randomly chosen image\n",
    "7. Sample code for Mini-batch access for bigger dataset\n",
    "8. References"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "from random import shuffle\n",
    "import os\n",
    "import glob\n",
    "import scipy\n",
    "from scipy import ndimage\n",
    "import numpy as np\n",
    "import h5py\n",
    "import matplotlib.pyplot as plt\n",
    "from data_util import *\n",
    "\n",
    "%matplotlib inline\n",
    "plt.rcParams['figure.figsize'] = (5.0, 4.0) # set default size of plots\n",
    "plt.rcParams['image.interpolation'] = 'nearest'\n",
    "plt.rcParams['image.cmap'] = 'gray'\n",
    "\n",
    "%load_ext autoreload\n",
    "%autoreload 2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 1. Prepare your data\n",
    "Put all images with the same label into each separate folder. Name the folder\n",
    "with the name of the target class. For example, if you have a binary classification \n",
    "task to identify cats vs non-cats. Put all your cats photo into a folder named \"cat\" and\n",
    "all the non-cats photos into another folder named \"non-cat\". We will use this as example in this notebook.\n",
    "\n",
    "For multi-class classification with classes named \"A\", \"B\", \"C\", and \"D\", create 4 folders with those\n",
    "names and place your images under each.\n",
    "\n",
    "#### 2. Define all expected common parameters\n",
    "* __data_path__ is the root directory containing all the folders holding images of each class (see above).\n",
    "* __shuffled_data__ is a boolean to determine if we should shuffle the data before saving into h5 file\n",
    "* __height, width__ are the resized height and width. It is assumed that in general, your photos may have different height and width, and they will have to be resized to these fixed values.\n",
    "* __data_order__ can either be 'tf' or 'th' (tensorflow vs. theano). I have only tested 'tf' for now, so just stick with that. The only difference I am aware of is 'tf' uses \"channel last\" with shape (m, h, w, c) and 'th' uses \"channel first\" with shape (m, c, h, w)\n",
    "* __outfile_path__ is the name of the output HDF5 file name.\n",
    "* __labels_to_classes_dictionary__ is a python dictionary with numeric string as key and the name of the class as values. E.g. {\"0\": \"non-cat\", \"1\": \"cat\"}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "shuffle_data = True\n",
    "data_order = 'tf'      # channel last\n",
    "\n",
    "# root directory where the data is stored.\n",
    "data_path = '.'   # current directory\n",
    "\n",
    "# resize dimensions\n",
    "height = 224      \n",
    "width = 224\n",
    "\n",
    "# the hdf5 file to write to\n",
    "outfile_path = \"train_\" + str(height) + \"_\" + str(width) + \".hdf5\"\n",
    "\n",
    "target_label_dictionary = {\"0\": \"non-cat\", \"1\": \"cat\"}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 3. Call generate_h5(...) to generate HDF5 dataset file\n",
    "generate_h5 takes a few argument. Please see data_util.py for all details. Most of the important arguments are explained in Part 2 above. The method will save a file with name __outfile_path__ that is an HDF5 dataset."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "generate_h5(data_path, labels_to_classes_dictionary=target_label_dictionary, \n",
    "            outfile_path=outfile_path, resize_height=height, resize_width=width, \n",
    "            train_dev_test_ratio=[0.6, 0.2, 0.2])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 4. Call load_all_data(...) to extract the data as np.array objects into your python env"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "train_set_x_orig, train_set_y_orig, dev_set_x_orig, dev_set_y_orig, test_set_x_orig, test_set_y_orig, classes = load_all_data(outfile_path)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 5. Check on the shape or content of the various np.array"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "print(\"X_train shape: \" + str(train_set_x_orig.shape))\n",
    "print(\"Y_train shape: \" + str(train_set_y_orig.shape))\n",
    "print(\"X_dev shape: \" + str(dev_set_x_orig.shape))\n",
    "print(\"Y_dev shape: \" + str(dev_set_y_orig.shape))\n",
    "print(\"X_test shape: \" + str(test_set_x_orig.shape))\n",
    "print(\"Y_test shape: \" + str(test_set_y_orig.shape))\n",
    "\n",
    "print(\"Classes are: \" + str(classes))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 6. Check to visualize a randomly chosen image"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# Randomly visualize some X\n",
    "\n",
    "plt.figure(figsize = (6, 6))\n",
    "index = np.random.randint(len(train_set_y_orig))\n",
    "print(target_label_dictionary[str(train_set_y_orig[index][0])])\n",
    "plt.imshow(train_set_x_orig[index])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "#### 7. Sample code for Mini-batch access for bigger dataset"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "from math import ceil\n",
    "\n",
    "hdf5_file = h5py.File(outfile_path, \"r\")\n",
    "\n",
    "batch_size = 32\n",
    "train_size = hdf5_file[\"train_set_x\"].shape[0]\n",
    "num_of_classes = len(classes)\n",
    "\n",
    "# create list of batches\n",
    "batches_list = list(range(int(ceil(float(train_size) / batch_size))))\n",
    "shuffle(batches_list)\n",
    "\n",
    "for n, i in enumerate(batches_list):\n",
    "    i_s = i * batch_size  # index of the first image in this batch\n",
    "    i_e = min([(i + 1) * batch_size, train_size])  # index of the last image in this batch\n",
    "    \n",
    "    # read batch images and remove training mean\n",
    "    images = hdf5_file[\"train_set_x\"][i_s:i_e, ...]\n",
    "\n",
    "    # read labels and convert to one hot encoding\n",
    "    labels = hdf5_file[\"train_set_y\"][i_s:i_e]\n",
    "    labels_one_hot = np.zeros((labels.shape[0], num_of_classes))\n",
    "    labels_one_hot[np.arange(labels.shape[0]), labels] = 1\n",
    "    \n",
    "    print n+1, '/', len(batches_list)\n",
    "    print labels[0], labels_one_hot[0, :]\n",
    "    plt.imshow(images[0])\n",
    "    plt.show()\n",
    "    \n",
    "    if n == 5:  # break after 5 batches\n",
    "        break\n",
    "\n",
    "hdf5_file.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Conclusion\n",
    "\n",
    "You can now collect your own images with their own classes. Create a folder for each class and place all images belonging to that class under it. Edit and re-run this notebook. Then you can start using the h5 file and numpy data output and try your own experiments with the same code in some programming exercise in the Deep Learning Specialization on Coursera."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### References:\n",
    "* Notation and format inspired by Deep Learning Specialization from Coursera/deeplearning.ai. \n",
    "* http://machinelearninguru.com/deep_learning/data_preparation/hdf5/hdf5.html\n",
    "* https://docs.scipy.org/doc/\n",
    "* The few sample photos come from https://www.kaggle.com/c/dogs-vs-cats"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}