README.md

Get in touch on Twitter @axelmukwena

Be sure to checkout the API and Ruby Web Client

Axel MS Mukwena | Supervisor: Prof Liming Zhang | Computer Science, Faculty of Science and Technology | University of Macau

Academic Report

Final Year Project Academic Report

Documentation

Deep ECG Based Biometric Identification System, DEBBIS

Project Structure

Figure 1: Debbis Project Structure

The code to formulate Debbis is comprised of data processing and models development/training, API set up and client web application. Data processing development was on carried out on a Macintosh 2.4 GHz Quad-Core Intel Core i7 16 GB RAM computer and model developments were carried out on Google Colab Premium running on a Tesla P100-PCIE-16GB GPU.

Data Processing and Models Development

Data processing was developmed in Python 3 and hosted under the directory root_folder/biometricECG, preferably performed using the Pycharm software by JetBrains under a virtual environment.

NB: For any ModuleNotFoundError: No module named 'name', execute the following in the given directory

$ sudo python3 -m pip install 'name'

Figure 2: BMD101 Kit

Figure 3: BMD101 GUI Interface

Procedure:

NB: This experiments is optimized for the MIT-BIH Dataset

1. Getting the data:

   1. MIT-BIH
      1. Go to https://www.physionet.org/content/mitdb/1.0.0/ and download the zipped file.
      2. Extract the files into the folder root_folder/biometricECG/data/raw/mit/
   2. ECG-ID
      1. Go to https://physionet.org/content/ecgiddb/1.0.0/ and download the zipped file.
      2. Extract the files into the folder root_folder/biometricECG/data/raw/ecgid/
   3. BMD101
      1. Go to root_folder/BMD101_Kit/windows/, copy the folder contents into a folder on a windows operated device.
      2. Connect the BMD101 Sensor Kit in Figure 1 to bluetooth on Windows-OS.
      3. If requested for pin, enter '0000'.
      4. After successfully connected, run the executable file CardioChip.exe.
      5. After seeing the interface in Figure 2, at the top, click 'Connect'
      6. After successfull connection, ecg signals will start to reflect on the interface. Click 'Record' at the bottom.
      7. Ensure minimal vibration in the surroundings.
      8. Optimal recording takes around 20-25 minutes
      9. When desired time is reached, click 'Stop', save the file in the desired location.
      10. In the desired location above, obtain the text files and copy them into root_folder/biometricECG/data/raw/bmd101/raw/unique_id_folder/

2. Go to root folder

   $ cd folder/folder/biometricECG

3. Install virtualenv

   # Mac OS
   $ sudo -H pip install virtualenv
         
   # Windows
   $ pip install virtualenv

4. Create a virtual environment

   # Mac OS
   $ virtualenv -p python3 venv
   # Windows
   $ python3 -mvenv venv

5. Activate the environment

   # Mac OS
   $ source venv/bin/activate
   # Windows
   $ venv\Scripts\activate

6. Install the requirements.txt

   # Mac OS
   $ pip3 install -r requirements.txt
   # Windows
   $ python3 -m pip install -r requirements.txt

7. Once the data is fully set up, run the following commands to extract signals into readable csv file formats

   $ python3 run.py -s-mit
   $ python3 run.py -s-ecgid
   $ python3 run.py -s-bmd

8. For Feature Extraction, run. ECG segments of size 256 will be saved into the folder root_folder/biometricECG/data/ready/signals/ in pickle format

   $ python3 run.py -f-mit
   $ python3 run.py -f-ecgid
   $ python3 run.py -f-bmd
   

9. Set up data for Training, Only MIT-BIH is selected. Two pickle files 'cnn.pickle' for CNN and 'snn.pickle' for SNN model development will be created in the folder root_folder/biometricECG/data/ready/pickles/

   $ python3 run.py -setup
   

10. Train the SNN model. A model will be saved in Keras model.save() format into the folder root_folder/biometricECG/models/snn/ and all plots will be saved under root_folder/biometricECG/media/plots/

    $ python3 run.py -snn
    

11. Train the CNN model. A model will be saved in Keras model.save() format into the folder root_folder/biometricECG/models/cnn/ and all plots will be saved under root_folder/biometricECG/media/plots/

    $ python3 run.py -cnn
    

DEBBIS-API: Simulation API setup

The python API is available at https://github.com/axelmukwena/debbis-api

NB: Simulations only work with data created using the BMD101 Sensor

API setup was developmed in Python 3 and hosted under the directory root_folder/debbis-api. The API is developed using the Flask Framework to recieve HTTPS requests. The simulation utilizes the Siamese Neural Network Model since the SNN model completes all the requirements for Debbis.

After installation of all required packages and modules, obtain and copy the 'contents' of the SNN model titled debbis saved in biometricECG/models/snn/debbis/ and paste into debbis-api/model/.

File structure should resemble or similar:

• debbis-api - model - assets - variables - keras_metadata.pb - saved_model.pb

After setup, run

$ python3 app.py

which should start up the development server at the following url http://127.0.0.1:5000/

DEBBIS: Simulation, Client Web App

The framework is available at https://github.com/axelmukwena/debbis

The client web app is developed using the Ruby on Rails Framework and hosted under the directory root_folder/debbis .The RubyMine IDE by JetBrains is prefered. ruby '3.0.0' and rails '~> 6.1.3' should be installed.

Install the needed gems (while skipping any gems needed only in production):

$ bundle install --without production

Install JavaScript dependencies:

$ yarn install

Next, migrate the database:

$ rails db:migrate

Run the app in a local server:

$ rails server

The server should start and the app should be accessible at http://localhost:3000/

1. Once both the API and Web Client servers are operational, a Super User needs to create an account at http://localhost:3000/signup.
2. Once signed up and logged in, go to enroll, http://localhost:3000/members/new and add a new member to the system.
   1. Identity is a Unique integer ID key,
   2. Node should be set to 0
   3. Name, Age, Gender are optional
3. Once a member is enrolled, you will be redirected to the Members page, where you can upload the text file title starting ECGLog... obtained from the BMD101 Sensor. After submiting templates, the data will be sent to the Python API and the most representative ECG segments of that individual will be selected and saved.
4. Once templates are successfully saved, any enrolled member can use the home page, http://localhost:3000/, upload a new text file title starting ECGLog... obtained from the BMD101 Sensor, submit by clicking access and if such member is enrolled, they will be taken to an only-member accessible page.

Notes

Installing or updating packages

Just make sure env exists, otherwise create another one

• Go to folder

  $ cd folder/folder/biometricECG
  

• Activate env

  # Mac OS
  $ source venv/bin/activate
  
  # Windows
  $ venv\Scripts\activate
  

• Install or update package

  # specific command
  # MacOS
  $ pip install --upgrade package
  

• Update requirements.txt

  $ pip freeze > requirements.txt
  

Deactivate env

• Deactivate env

  # Mac OS
  $ deactivate
  
  # Windows
  $