tutorials/03_tutorial_RCDT-NS_classifier.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Radon-Cumulative Distribution Transform Nearest Subspace (RCDT-NS) Classifier\n",
    "\n",
    "This tutorial will demonstrate how to use the RCDT-NS classifier in the *PyTransKit* package."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Class:: RCDT_NS\n",
    "**Functions**:\n",
    "\n",
    "1. Constructor function:\n",
    "        rcdt_ns_obj = RCDT_NS(num_classes, thetas, rm_edge)\n",
    "        \n",
    "        Inputs:\n",
    "        ----------------\n",
    "        num_classes : integer value\n",
    "            totale number of classes in the dataset.\n",
    "        thetas : 1d array\n",
    "            angles in degrees for taking radon projections. Example: thetas=numpy.linspace(0,180,45)\n",
    "        rm_edge : boolean \n",
    "            IF TRUE the first and last points of RCDTs will be removed.\n",
    "            \n",
    "        Outputs:\n",
    "        ----------------\n",
    "        rcdt_ns_obj : class object\n",
    "            Instance of the class RCDT_NS.\n",
    "            \n",
    "2. Fit function:\n",
    "        rcdt_ns_obj.fit(Xtrain, Ytrain, no_deform_model)\n",
    "        \n",
    "        Inputs:\n",
    "        ----------------\n",
    "        Xtrain : 3d array, shape (n_samples, n_rows, n_columns)\n",
    "            Image data for training.\n",
    "        Ytrain : 1d array, shape (n_samples,)\n",
    "            Labels of the training images.\n",
    "        no_deform_model : boolean\n",
    "            IF TRUE, no deformation model will be added\n",
    "  \n",
    "3. Predict function:\n",
    "        preds = rcdt_ns_obj.predict(Xtest, use_gpu)\n",
    "        \n",
    "        Inputs:\n",
    "        ----------------\n",
    "        Xtest : 3d array, shape (n_samples, n_rows, n_columns)\n",
    "            Image data for testing.\n",
    "        use_gpu : boolean \n",
    "            IF TRUE, use gpu for calculations.\n",
    "            \n",
    "        Outputs:\n",
    "        ----------------\n",
    "        preds : 1d array, shape (n_samples,)\n",
    "           Predicted labels for test samples.\n",
    "    "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example\n",
    "The following example will demonstrate how to:\n",
    "* create and initialize an instance of the class RCDT_NS\n",
    "* train the model with training images\n",
    "* apply the model to predict calss labels of the test images\n",
    "In this example we have used MNIST dataset stored in the *data* folder"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Import some python libraries"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "from sklearn.metrics import accuracy_score\n",
    "from pathlib import Path\n",
    "import sys\n",
    "sys.path.append('../')\n",
    "from pytranskit.classification.utils import *\n",
    "\n",
    "use_gpu = False"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Import RCDT-NS class from *PyTransKit* package"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pytranskit.classification.rcdt_ns import RCDT_NS"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Load dataset\n",
    "For loading data we have used *load_data* function from the *pytranskit/classifier/utils.py* script. It takes name and directory of the dataset, and total number of classes as input. Returns both train and test images in two separate 3d arrays of shape (n_samples, n_rows, n_columns), and corresponding class labels. User can use there own implementation to load data, just need to make sure that the output arrays are consistent."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "loading data from mat files\n",
      "x_train.shape (60000, 28, 28) x_test.shape (10000, 28, 28)\n",
      "saved to ./data/MNIST/dataset.hdf5\n"
     ]
    }
   ],
   "source": [
    "datadir = './data'\n",
    "dataset = 'MNIST'\n",
    "num_classes = 10          # total number of classes in the dataset\n",
    "(x_train, y_train), (x_test, y_test) = load_data(dataset, num_classes, datadir)  # load_data function from utils.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this example we have used 512 randomly chosen samples per class to train the model. We have used another function *take_train_samples* function from *utils.py* script for this. User can use their own script."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "n_samples_perclass = 512  # total number of training samples per class used in this example\n",
    "x_train_sub, y_train_sub = take_train_samples(x_train, y_train, n_samples_perclass, \n",
    "                                              num_classes, repeat=0) # function from utils.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Create an instance of RCDT_NS class"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "theta = np.linspace(0, 176, 45)    # choose the angles in degrees that will be used to calculate Radon projections\n",
    "rcdt_ns_obj = RCDT_NS(num_classes, theta, rm_edge=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Training phase\n",
    "This function takes the train samples and labels as input, and stores the basis vectors for corresponding classes in a *private* variable. This variable will be used in the *predict* function in the test phase"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Calculating RCDTs for training images ...\n",
      "Generating basis vectors for each class ...\n"
     ]
    }
   ],
   "source": [
    "rcdt_ns_obj.fit(x_train_sub, y_train_sub)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Testing phase\n",
    "*predict* function takes the train samples as input and returns the predicted class labels"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Calculating RCDTs for testing images ...\n",
      "Finding nearest subspace for each test sample ...\n"
     ]
    }
   ],
   "source": [
    "preds = rcdt_ns_obj.predict(x_test, use_gpu)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Test accuracy: 95.41%\n"
     ]
    }
   ],
   "source": [
    "print('\\nTest accuracy: {}%'.format(100*accuracy_score(y_test, preds)))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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.7.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}