Merge pull request #17 from AdamMiltonBarker/main

1.0.2
AMLResearchProject · Jul 19, 2021 · 3b4c63d · 3b4c63d
2 parents f9bd1e8 + 041b09b
commit 3b4c63d
Show file tree

Hide file tree

Showing 10 changed files with 52 additions and 30 deletions.
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@
 
 ![Acute Lymphoblastic Leukemia Arduino Nano 33 BLE Sense Classifier](assets/images/project-banner.jpg)
 
-[![CURRENT RELEASE](https://img.shields.io/badge/CURRENT%20RELEASE-1.0.0-blue.svg)](https://github.com/AMLResearchProject/ALL-Arduino-Nano-33-BLE-Sense-Classifier/tree/1.0.0) [![UPCOMING RELEASE](https://img.shields.io/badge/CURRENT%20DEV%20BRANCH-2.0.0-blue.svg)](https://github.com/AMLResearchProject/ALL-Arduino-Nano-33-BLE-Sense-Classifier/tree/2.0.0) [![Contributions Welcome!](https://img.shields.io/badge/Contributions-Welcome-lightgrey.svg)](CONTRIBUTING.md)  [![Issues](https://img.shields.io/badge/Issues-Welcome-lightgrey.svg)](issues)
+[![CURRENT RELEASE](https://img.shields.io/badge/CURRENT%20RELEASE-1.0.2-blue.svg)](https://github.com/AMLResearchProject/ALL-Arduino-Nano-33-BLE-Sense-Classifier/tree/1.0.2) [![UPCOMING RELEASE](https://img.shields.io/badge/CURRENT%20DEV%20BRANCH-2.0.0-blue.svg)](https://github.com/AMLResearchProject/ALL-Arduino-Nano-33-BLE-Sense-Classifier/tree/2.0.0) [![Contributions Welcome!](https://img.shields.io/badge/Contributions-Welcome-lightgrey.svg)](CONTRIBUTING.md)  [![Issues](https://img.shields.io/badge/Issues-Welcome-lightgrey.svg)](issues)
 
 [![PEP8](https://img.shields.io/badge/code%20style-pep8-orange.svg)](https://www.python.org/dev/peps/pep-0008/) [![Documentation Status](https://readthedocs.org/projects/all-arduino-nano-33-ble-sense-classifier/badge/?version=latest)](https://all-arduino-nano-33-ble-sense-classifier.readthedocs.io/en/latest/?badge=latest) [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/5065/badge)](https://bestpractices.coreinfrastructure.org/projects/5065)
 
@@ -33,7 +33,13 @@
 
 # Introduction
 
-The **Acute Lypmhoblastic Leukemia Arduino Nano 33 BLE Sense Classifier** is an experiment to explore how low powered microcontrollers, specifically the Arduino Nano 33 BLE Sense, can be used to detect Acute Lymphoblastic Leukemia. The Arduino Nano 33 BLE Sense is the latest Arduino Board  which supports  Tensorflow Lite, allowing machine learning on Arduino.
+The **Acute Lypmhoblastic Leukemia Arduino Nano 33 BLE Sense Classifier** is an experiment to explore how low powered microcontrollers, specifically the Arduino Nano 33 BLE Sense, can be used to detect Acute Lymphoblastic Leukemia. The [Arduino Nano 33 BLE Sense](https://store.arduino.cc/arduino-nano-33-ble-sense) is the latest Arduino Board  which supports  Tensorflow Lite, allowing machine learning on Arduino.
+
+![Acute Lymphoblastic Leukemia Arduino Nano 33 BLE Sense Classifier](assets/images/all-arduino-nano-33-ble-classifier.gif)
+
+The model you will train is a 6 layer Convoluntional Neural Network trained using [Intel® Optimization for Tensorflow*](https://software.intel.com/content/www/us/en/develop/articles/intel-optimization-for-tensorflow-installation-guide.html) from the  [Intel® oneAPI AI Analytics Toolkit](https://software.intel.com/content/www/us/en/develop/tools/oneapi/ai-analytics-toolkit/download.html?operatingsystem=linux) to optimize and accelerate the training process.
+
+Checkout the [official video](https://www.youtube.com/watch?v=CDJEXdj2KZs) for the project.
 
 &nbsp;
 
@@ -54,13 +60,16 @@ The motivation for this project was to explore how low powered devices such as A
 &nbsp;
 
 # Acute Lymphoblastic Leukemia
-[Acute lymphoblastic leukemia (ALL)](https://www.leukemiaairesearch.com/research/leukemia), also known as Acute Lymphocytic Leukemia, is a cancer that affects the lymphoid blood cell lineage. It is the most common leukemia in children, and it accounts for 10-20% of acute leukemias in adults. The prognosis for both adult and especially childhood ALL has improved substantially since the 1970s. The 5- year survival is approximately 95% in children. In adults, the 5-year survival varies between 25% and 75%, with more favorable results in younger than in older patients.
+[Acute lymphoblastic leukemia (ALL)](https://www.leukemiaairesearch.com/research/leukemia), also known as acute lymphocytic leukemia, is a cancer that affects the lymphoid blood cell lineage. It is the most common leukemia in children, and it accounts for 10-20% of acute leukemias in adults. The prognosis for both adult and especially childhood ALL has improved substantially since the 1970s. The 5- year survival is approximately 95% in children. In adults, the 5-year survival varies between 25% and 75%, with more favorable results in younger than in older patients.
 
 For more information about Acute Lymphoblastic Leukemia  please visit our [Leukemia Information Page](https://www.leukemiaairesearch.com/research/leukemia)
 
 &nbsp;
 
 # ALL-IDB
+
+![Acute Lymphoblastic Leukemia Arduino Nano 33 BLE Sense Classifier](assets/images/all-idb.jpg)
+
 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, we would be very happy to find additional AML & ALL datasets.
 
 &nbsp;

diff --git a/assets/images/all-arduino-nano-33-ble-classifier.gif b/assets/images/all-arduino-nano-33-ble-classifier.gif
diff --git a/assets/images/all-idb.jpg b/assets/images/all-idb.jpg
diff --git a/assets/images/project-banner.jpg b/assets/images/project-banner.jpg
diff --git a/docs/img/project-banner.jpg b/docs/img/project-banner.jpg
diff --git a/docs/index.md b/docs/index.md
@@ -4,11 +4,7 @@
 
 # Welcome
 
-Welcome to the **ALL Arduino Nano 33 BLE Sense Classifier** official documentation.
-
-The **Acute Lypmhoblastic Leukemia Arduino Nano 33 BLE Sense Classifier** is an experiment to explore how low powered microcontrollers, specifically the Arduino Nano 33 BLE Sense, can be used to detect Acute Lymphoblastic Leukemia. The Arduino Nano 33 BLE Sense is the latest Arduino Board  which supports  Tensorflow Lite, allowing machine learning on Arduino.
-
-The motivation for this project was to explore how low powered devices such as Arduino can be used to detect Acute Lymphoblastic Leukemia. The project will be submitted to the Tensorflow For Microcontroller Challenge and the Eyes on Edge: tinyML Vision Challenge.
+Welcome to the [ALL Arduino Nano 33 BLE Sense Classifier](https://github.com/AMLResearchProject/ALL-Arduino-Nano-33-BLE-Sense-Classifier) official documentation.
 
 &nbsp;
 
@@ -24,7 +20,7 @@ _Developers that have contributed to this repository have experience in using Ar
 
 # Installation
 
-Use the following installation guides to set up your project:
+Use the following installation guides to set up your project.:
 
 - [Ubuntu Installation Guide](installation/ubuntu.md)
 - [Arduino Installation Guide](installation/arduino.md)

diff --git a/docs/installation/arduino.md b/docs/installation/arduino.md
@@ -24,17 +24,17 @@ The following hardware is required for this project:
 # Software
 The following Arduino software libraries are used with this project:
 
-- [Arduino Tensorflow Lite](https://github.com/tensorflow/tflite-micro)
+- [Arduino IDE](https://www.arduino.cc/en/software)
+- [Arduino Tensorflow Lite For Microcontrollers](https://github.com/tensorflow/tflite-micro)
 - [JpegDecoder](https://github.com/Bodmer/JPEGDecoder)
 
 &nbsp;
 
 # Prerequisites
-You will need to ensure you have installed the following software and followed the provided guides:
+You will need to ensure you have followed the provided guides below:
 
 - [Ubuntu Installation Guide](../installation/ubuntu.md)
 - [Python Usage Guide](../usage/python.md) or [Jupyter Notebooks Usage Guide](../usage/notebooks.md)
-- [Arduino IDE](https://www.arduino.cc/en/software)
 - [Getting started with the Arduino Nano 33 BLE Sense](https://www.arduino.cc/en/Guide/NANO33BLESense)
 - [Why doesn't the 5V pin work in the Arduino Nano 33 BLE boards?](https://support.arduino.cc/hc/en-us/articles/360014779679-Why-doesn-t-the-5V-pin-work-in-the-Arduino-Nano-33-BLE-boards-)
 
@@ -44,7 +44,18 @@ You will need to ensure you have installed the following software and followed t
 
 ![ALL Arduino Nano 33 BLE Sense Classifier](../img/arduino-nano-33-ble-sense-sd_bb.jpg)
 
-Follow the diagram above to connect your SD card reader to the Arduino Nano 33 BLE Sense.
+Follow the diagram above to connect your SD card reader to the Arduino Nano 33 BLE Sense. Remember you need to follow the steps in  [Why doesn't the 5V pin work in the Arduino Nano 33 BLE boards?](https://support.arduino.cc/hc/en-us/articles/360014779679-Why-doesn-t-the-5V-pin-work-in-the-Arduino-Nano-33-BLE-boards-) to enable 5V on the Arduino Nano BLE Sense.
+
+ Below is a pin guide to help.
+
+| Arduino Pin | SD Card Pin |
+| ---------- | ---------- |
+| D10 | CS |
+| D11 | MOSI |
+| D12 | MISO |
+| D13 | SCK |
+| 5v | VCC |
+| GND | GND |
 
 &nbsp;
 

diff --git a/docs/installation/ubuntu.md b/docs/installation/ubuntu.md
@@ -40,7 +40,7 @@ To clone the repository and install the project, make sure you have Git installe
  git clone https://github.com/AMLResearchProject/ALL-Arduino-Nano-33-BLE-Sense-Classifier.git
 ```
 
-This will clone the ALL Arduino Nano 33 BLE Sense Classifier repository and move the cloned repository to the agents directory in the HIAS project (components/agents/mqtt/).
+This will clone the ALL Arduino Nano 33 BLE Sense Classifier repository.
 
 ``` bash
  ls
@@ -59,10 +59,10 @@ Navigate to the **ALL-Arduino-Nano-33-BLE-Sense-Classifier** directory, this is
 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.
 
 ``` bash
- git clone -b "1.0.0" https://github.com/AMLResearchProject/ALL-Arduino-Nano-33-BLE-Sense-Classifier.git
+ git clone -b "2.0.0" https://github.com/AMLResearchProject/ALL-Arduino-Nano-33-BLE-Sense-Classifier.git
 ```
 
-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.
+The **-b "2.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.
 
 &nbsp;
 

diff --git a/docs/usage/arduino.md b/docs/usage/arduino.md
@@ -36,8 +36,13 @@ Now you need to import your C array model into the Arduino project. On your deve
 
 &nbsp;
 
+# Test Data
+During training the test data was resized and moved to the **model/data/test/** directory. Before you can continue you need to upload these files to the SD card.
+
+&nbsp;
+
 # Run The Classifier
-Now it is time to run your classifier on the Arduino Nano 33 BLE Sense. Make sure you are connected to your Arduino and click on the **upload** button. Once the model is uploaded it will start to run, open your serial monitor and watch the output.
+Now it is time to run your classifier on the Arduino Nano 33 BLE Sense. Make sure you are connected to your Arduino and click on the **upload** button. Once the model is uploaded it will start to run, open your serial monitor and watch the output. You will see the onboard LED on the Arduino Nano 33 BLE Sense turn **red** if Acute Lymphoblastic Leukemia is detected and **green** if it is not.
 
 ``` bash
 19:22:40.139 -> Initialising SD card...
@@ -183,7 +188,7 @@ Now it is time to run your classifier on the Arduino Nano 33 BLE Sense. Make sur
 
 # Conclusion
 
-We see that our model that can correctly classify all twenty images only gets 11/20 when running on Arduino. There are some additional testing steps we can take which will be introduced in V2 that will allow us to test the Arduino model on our development machine to help identify where the bug is coming from. For now this is a good first attempt at building a classifier to  detect Acute Lymphoblastic Leukemia detection on Arduino. If you would like to view the ongoing issue in the Tensorflow Micro repository [click here](https://github.com/tensorflow/tflite-micro/issues/287), thanks to [Advait Jain](https://github.com/advaitjain) for the asistance with this issue.
+We see that our model that can correctly classify all twenty images only gets 11/20 when running on Arduino. There are some additional testing steps we can take which will be introduced in V2 that will allow us to test the Arduino model on our development machine to help identify where the bug is coming from. For now this is a good first attempt at building a classifier to  detect Acute Lymphoblastic Leukemia detection on Arduino. If you would like to view the ongoing issue in the Tensorflow Micro repository [click here](https://github.com/tensorflow/tflite-micro/issues/287) thanks to [Advait Jain](https://github.com/advaitjain) for the asistance with this issue.
 
 &nbsp;
 

diff --git a/docs/usage/python.md b/docs/usage/python.md
@@ -221,29 +221,30 @@ _________________________________________________________________
 ## Training Results
 Below are the training results for 28 epochs.
 
-<img src="../img/plots/accuracy.png" alt="Adam Optimizer Results" />
+![Accuracy](../img/plots/accuracy.png)
 
-_Fig 2. Accuracy_
+_Fig 1. Accuracy_
 
-<img src="../img/plots/loss.png" alt="Loss" />
+![Loss](../img/plots/loss.png)
 
-_Fig 3. Loss_
+_Fig 2. Loss_
 
-<img src="../img/plots/precision.png" alt="Precision" />
+![Precision](../img/plots/precision.png)
 
-_Fig 4. Precision_
+_Fig 3. Precision_
 
-<img src="../img/plots/recall.png" alt="Recall" />
+![Recall](../img/plots/recall.png)
 
-_Fig 5. Recall_
+_Fig 4. Recall_
 
-<img src="../img/plots/auc.png" alt="AUC" />
+![AUC](../img/plots/auc.png)
 
-_Fig 6. AUC_
+_Fig 5. AUC_
 
-<img src="../img/plots/confusion-matrix.png" alt="AUC" />
+![Confusion Matrix](../img/plots/confusion-matrix.png)
+
+_Fig 6. Confusion Matrix_
 
-_Fig 7. Confusion Matrix_
 
 ``` bash
 2021-07-18 17:47:55,953 - Classifier - INFO - Metrics: loss 0.2371470034122467