Resolves #8 Data Processing/Analysis / Training / Converting and Documentation

Author: AdamMiltonBarker

classifier.py

@@ -57,7 +57,6 @@ def train(self):
 		self.model.prepare_network()
 		self.model.train()
 		self.model.evaluate()
-		self.mqtt.disconnect()
 
 	def set_model(self):
 		""" Loads the model class """
@@ -116,11 +115,11 @@ def main():
 		classifier.inference()
 
 	elif mode == "server":
-		classifier.set_model("CNN")
+		classifier.set_model()
 		classifier.server()
 
 	elif mode == "classify_http":
-		classifier.set_model("CNN")
+		classifier.set_model()
 		classifier.inference_http()
 
 

configuration/config.json

@@ -1,7 +1,7 @@
 {
     "agent": {
         "cores": 8,
-        "server": "",
+        "ip": "",
         "port": 1234,
         "params": [
             "train",
@@ -16,7 +16,7 @@
         "labels": [0, 1],
         "rotations": 10,
         "seed": 2,
-        "split": 0.3,
+        "split": 0.255,
         "test": "model/data/test",
         "test_data": [
             "Im006_1.jpg",

docs/img/plots/accuracy.png

@@ -3,37 +3,34 @@
 ![ALL Arduino Nano 33 BLE Sense Classifier](../img/project-banner.jpg)
 
 # Introduction
-This guide will guide you through the installation process for the **ALL Arduino Nano 33 BLE Sense Classifier** Project.
-
-<font color='red'>DEVELOPER TO EXPLAIN/UPDATE THE PROJECT DETAILS</font>
-
-&nbsp;
-
-# Prerequisites
-You will need to ensure you have the following prerequisites installed and setup.
-
-<font color='red'>DEVELOPER TO EXPLAIN/UPDATE THE PREQUISITE DETAILS</font>
+This guide will take you through the installation process for the **ALL Arduino Nano 33 BLE Sense Classifier** trainer.
 
 &nbsp;
 
 # Operating System
-The ALL Arduino Nano 33 BLE Sense Classifier Jupyter Notebook supports the following operating system(s).
+This project supports the following operating system(s), but may work as described on other OS.
 
-<font color='red'>DEVELOPER TO LIST COMPATIBLE OPERATING SYSTEM(S). MUST BE TESTED BEFORE LISTING</font>
+- [Ubuntu 20.04](https://releases.ubuntu.com/20.04/)
 
 &nbsp;
 
 # Software
-The ALL Arduino Nano 33 BLE Sense Classifier Jupyter Notebook project uses the following libraries.
-
-<font color='red'>DEVELOPER TO LIST SOFTWARE LIBRARIES USED</font>
+This project uses the following libraries.
+
+- Conda
+- Intel® oneAPI AI Analytics Toolkit
+- Jupyter Notebooks
+- NBConda
+- Mlxtend
+- Pillow
+- Opencv
+- Scipy
+- Scikit Image
+- Scikit Learn
 
 &nbsp;
 
-# Installation
-You are now ready to install the ALL Arduino Nano 33 BLE Sense Classifier Project.
-
-## Clone the repository
+# Clone the repository
 
 Clone the [ALL Arduino Nano 33 BLE Sense Classifier](https://github.com/AMLResearchProject/ALL-Arduino-Nano-33-BLE-Sense-Classifier " ALL Arduino Nano 33 BLE Sense Classifier") repository from the [Peter Moss Acute Myeloid & Lymphoblastic Leukemia AI Research Project](https://github.com/AMLResearchProject "Peter Moss Acute Myeloid & Lymphoblastic Leukemia AI Research Project") Github Organization.
 
@@ -57,7 +54,7 @@ Using the ls command in your home directory should show you the following.
 
 Navigate to the **ALL-Arduino-Nano-33-BLE-Sense-Classifier** directory, this is your project root directory for this tutorial.
 
-### Developer forks
+## Developer forks
 
 Developers from the Github community that would like to contribute to the development of this project should first create a fork, and clone that repository. For detailed information please view the [CONTRIBUTING](https://github.com/AMLResearchProject/ALL-Arduino-Nano-33-BLE-Sense-Classifier/blob/master/CONTRIBUTING.md "CONTRIBUTING") guide. You should pull the latest code from the development branch.
 
@@ -67,20 +64,33 @@ Developers from the Github community that would like to contribute to the develo
 
 The **-b "1.0.0"** parameter ensures you get the code from the latest master branch. Before using the below command please check our latest master branch in the button at the top of the project README.
 
-## Installation script
-All software requirements are included in **scripts/install.sh**. You can run this file on your machine from the project root in terminal. Use the following command:
+&nbsp;
 
+# Installation
+You are now ready to install the ALL Arduino Nano 33 BLE Sense Classifier trainer. All software requirements are included in **scripts/install.sh**. You can run this file on your machine from the project root in terminal. Use the following command:
+
+``` bash
  sh scripts/install.sh
+```
+
+**WARNING:** This script assumes you have not already installed the oneAPI Basekit.
+
+**WARNING:** This script assumes you have not already installed the oneAPI AI Analytics Toolkit.
+
+**WARNING:** This script assumes you have an Intel GPU.
+
+**WARNING:** This script assumes you have already installed the Intel GPU drivers.
 
-<font color='red'>DEVELOPER TO PROVIDE FULL INSTALLATION INSTRUCTIONS</font>
+**HINT:** If any of the above are not relevant to you, please comment out the relevant sections below before running this installation script.
 
 &nbsp;
 
-## Configuration
+# Continue
 
-All configuration can be found in the **configuration/config.json** file.
+Choose one of the following usage guides to train your model:
 
-<font color='red'>DEVELOPER TO EDIT CONFIG FILE AND PROVIDE FULL DESCRIPTION OF CONFIGURATION</font>
+- [Python Usage Guide](../usage/python.md)
+- [Jupyter Notebooks Usage Guide](../usage/notebooks.md)
 
 &nbsp;
 

docs/img/plots/auc.png

@@ -0,0 +1,104 @@
+# Notebooks Usage
+
+![ALL Arduino Nano 33 BLE Sense Classifier](../img/project-banner.jpg)
+
+# Introduction
+This guide will take you through using the **ALL Arduino Nano 33 BLE Sense Classifier** Jupyter Notebook to train and test your classifier.
+
+ 
+
+# Installation
+First you need to install the required software for training the model. Below are the available installation guides:
+
+- [Ubuntu installation guide](../installation/ubuntu.md).
+
+ 
+
+# Network Architecture
+We will build a Convolutional Neural Network with the following architecture:
+
+- Average pooling layer
+- Conv layer
+- Depthwise conv layer
+- Flatten layer
+- Fully connected layer
+- Softmax layer
+
+ 
+
+# Data
+You need to be granted access to use the Acute Lymphoblastic Leukemia Image Database for Image Processing dataset. You can find the application form and information about getting access to the dataset on [this page](https://homes.di.unimi.it/scotti/all/#download) as well as information on how to contribute back to the project [here](https://homes.di.unimi.it/scotti/all/results.php).
+
+_If you are not able to obtain a copy of the dataset please feel free to try this tutorial on your own dataset._
+
+Once you have your data you need to add it to the project filesystem. You will notice the data folder in the Model directory, **model/data**, inside you have **train** & **test**. Add all of the images from the ALL_IDB1 dataset to the **model/data/train** folder.
+
+## Data Augmentation
+
+We will create an augmented dataset based on the [Leukemia Blood Cell Image Classification Using Convolutional Neural Network](http://www.ijcte.org/vol10/1198-H0012.pdf "Leukemia Blood Cell Image Classification Using Convolutional Neural Network") by T. T. P. Thanh, Caleb Vununu, Sukhrob Atoev, Suk-Hwan Lee, and Ki-Ryong Kwon.
+
+## Application testing data
+
+In the data processing stage, ten negative images and ten positive images are removed from the dataset and moved to the **model/data/test/** directory. This data is not seen by the network during the training process, and is used to test the performance of the model.
+
+To ensure your model gets the same results, you should use the same test images. You can also try with your own image selection, however results may vary.
+
+ 
+
+# Start Jupyter Notebooks
+Now you need to start Jupyter Notebooks. In your project root execute the following command, replacing the IP and port as desired.
+
+``` bash
+jupyter notebook --ip YourIP --port 8888
+```
+
+ 
+
+# Open The Training Notebook
+
+Navigate to the URL provided when starting Jupyter Notebooks and you should be in the project root. Now navigate to **notebooks/classifier.ipynb**. With everything set up you can now begin training. Run the Jupyter Notebook and wait for it to finish.
+
+ 
+
+# Preparing For Arduino
+
+During training the model was converted to TFLite and optimized with full integer quantization. The TFLite model was then converted to C array ready to be deployed to our Arduino Nano 33 BLE Sense. The test data that was removed before training was converted to 100px x 100px so as not to require additional resizing on the Arduino.
+
+ 
+
+# Conclusion
+
+Here we trained a deep learning model for Acute Lymphoblastic Leukemia detection utilizing Intel® Optimization for Tensorflow* from the Intel® oneAPI AI Analytics Toolkit to optimize and accelarate training. We introduced a 6 layer deep learning model and applied data augmentation to increase the training data.
+
+We trained our model with a target of 150 epochs and used early stopping to avoid overfitting. The model trained for 27 epochs resulting in a fairly good fit, and accuracy/precision/recall and AUC are satisfying. In addition the model reacts well during testing classifying each of the twenty unseen test images correctly.
+
+ 
+
+# Continue
+
+Now you are ready to set up your Arduino Nano 33 BLE Sense. Head over to the [Arduino Installation Guide](../installation/arduino.md) to prepare your Arduino.
+
+ 
+
+# Contributing
+Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss encourages and welcomes code contributions, bug fixes and enhancements from the Github community.
+
+Please read the [CONTRIBUTING](https://github.com/AMLResearchProject/ALL-Arduino-Nano-33-BLE-Sense-Classifier/blob/main/CONTRIBUTING.md "CONTRIBUTING") document for a full guide to forking our repositories and submitting your pull requests. You will also find our code of conduct in the [Code of Conduct](https://github.com/AMLResearchProject/ALL-Arduino-Nano-33-BLE-Sense-Classifier/blob/main/CODE-OF-CONDUCT.md) document.
+
+## Contributors
+- [Adam Milton-Barker](https://www.leukemiaairesearch.com/association/volunteers/adam-milton-barker "Adam Milton-Barker") - [Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss](https://www.leukemiaresearchassociation.ai "Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss") President/Founder & Lead Developer, Sabadell, Spain
+
+ 
+
+# Versioning
+We use [SemVer](https://semver.org/) for versioning.
+
+ 
+
+# License
+This project is licensed under the **MIT License** - see the [LICENSE](https://github.com/AMLResearchProject/ALL-Arduino-Nano-33-BLE-Sense-Classifier/blob/main/LICENSE "LICENSE") file for details.
+
+ 
+
+# Bugs/Issues
+We use the [repo issues](https://github.com/AMLResearchProject/ALL-Arduino-Nano-33-BLE-Sense-Classifier/issues "repo issues") to track bugs and general requests related to using this project. See [CONTRIBUTING](https://github.com/AMLResearchProject/ALL-Arduino-Nano-33-BLE-Sense-Classifier/blob/main/CONTRIBUTING.md "CONTRIBUTING") for more info on how to submit bugs, feature requests and proposals.