# Python Assignment: scikit-learn

Giulia Gallico, Tyler Bass, Niklas Natter

## Purpose

The purpose of this assignment is to introduce you to the python machine learning library scikit-learn. The scikit-learn framework is built on numpy, scipy and matplotlib and provides simple and efficient tools for data mining and data analysis.

While completing this assignment, you will create a basic image classification application with the scikit-learn framework. Have you ever wondered how the photos app of your phone knows that there is a mountain on that picture you took on your holiday? This assignment might be a good start for getting to the answer of that question :)

## Background

In this assignment you will use the machine learning capabilities of the scikit-learn framework for implementing an image classification application.
To keep things simple, there will be only three different types of images: images of ships, images of frogs and images of trucks. Therefore, the goal of your application will be to predict if a given image contains either a ship, a frog or a truck.

When implementing an application which uses machine learning, it is common practice to split up the data into two sets: The training set contains the labeled data which is used to train your application. The test set contains the data which is used to test the trained application.
In the assignment folder, you will find a training.csv file which contains the file names of the images which you will use to train your application with their respective classification. Additionally, you will find a test.csv file which contains the file names of the test images with their correct classification. The respective images are stored in the provided training folder and test folder.

The following resources might be helpful for completing this assignment:

- scikit-learn documentation: http://scikit-learn.org/stable/documentation.html
- python image library documentation: http://www.pythonware.com/products/pil/
- tutorial on image classification with scikit-learn: http://www.pyimagesearch.com/2016/08/08/k-nn-classifier-for-image-classification/

## Assignment

The objective of this assignment is to create a basic image classification application for images of ships, frogs and trucks.
Your application should use the provided training data set to train your image classifier, and use the trained classifier to predict the classification for the images of the test data set.
The assignment.py file already contains some basic code for such an application. To complete the implementation, it might be helpful to go along with the tasks described below:

### Task 1: data set and image data reading

The provided assignment folder contains the files training.csv and test.csv which are defining the training data set and the test data set for your application. A data set for this application is defined by a set of image file names and their respective classifications. To work with this data sets, you have to read the content of the stated files in an appropriate data structure.
Additionally, you need to read the data of the images which are assigned to the image file names of the data sets.
For this assignment, it is recommended to use the python image library PIL to load this data.
HINT: As training a classifier takes its time, it might be helpful to limit the number of entries which is loaded from the training data set, while testing your implementation.

### Task 2: image data conversion

After reading the data sets and the assigned images, you have to convert the images to an appropriate format format to passing them to the classifier.
A classifier can handle arrays with one dimension only. Therefore, you need to extract the color information for each pixel of the image into a one dimensional array. To do this, the numpy library can be used to convert images which were read with the python image library PIL.
At a later point, you can try to apply filters to an image, before converting it to a one dimensional array, to increase the prediction score of your application. To do this, the python image library PIL provides a simple interface for applying filters on images.
You can also pass more information to the classifier, by concatenating multiple one dimensional arrays.
For example, you could concatenate the one dimensional array of an image with the one dimensional array of the result of an edge filter on that image.
HINT: You can also implement your own logic for extracting information, which then can be passed to the classifier, from an image. An example for this can be found in the 'get_number_of_edge_pixels()' function of the provided code.

### Task 3: classifier creation and training

Your application will use a classifier which is trained with the training data set to predict classifications for the images of the test data set.
The scikit-learn framework provides a couple of different types of classifiers which are suitable for different types of data.
In this assignment, you should try at least classifiers of the types KNeighborsClassifier, SVC and RandomForestClassifier, and choose the one which leads to the best results.
To train a classifier, you have to instantiate the classifier and call the respective method with the data from the training data set. Remember to pass the converted image data from task 2 to the classifier.

### Task 4: predicting, reporting and plotting

After you have trained your classifier, you can use it to predict the classifications for the images of the test data set by calling the respective method. Remember again to pass the converted image data from task 2 to the classifier.
After gathering the predicted classifications, you should print a classification report which includes the percentage of correct predicted classifications. To do this, the report methods of the scikit-learn framework might be helpful.
Additionally you should plot at least 10 images with their predicted classification. It should be recognizable from your plot, if the predicted classification is correct or incorrect. The plot_example.png file shows an example of such a plot.

## What does this Assignment include?

- assignment.py
  File which contains the code of the application. The provided file already contains some lines of code which should guide you in the right direction.

- training.csv
  Training data set for the application. This data set should be used to train the classifier of your application.
  Each row contains the file name of an image and the respective classification for the image.

- training directory
  Directory which contains the images of the training set in the .png format.

- test.csv
  Test data set for the application. You should use your trained classifier to predict the classifications for this data set.
  Each row contains the file name of an image and the respective classification for the image.

- test directory
  Directory which contains the images of the test set in the .png format.

- plot_example.png
  Example plot including images with predicted classifications and a prediction score diagram.

## Grading - 100 points possible

- 20 points: data set and image data reading
  Your application successfully loads the given data sets and the respective images.

- 20 points: image data conversion
  Your application converts the data of the loaded images to an one dimensional array which can be passed to a classifier.

- 20 points: classifier creation and training
  Your application instantiates a classifier and trains the classifier to the data of the training data set.

- 10 points: predicting and reporting
  Your application uses the trained classifier to predict classifications for the images of the test data set and prints a classification report.

- 10 points: plotting predictions
  Your application plots at least 10 images with their predicted classifications to a single figure. It should be recognizable from your figure, if the predicted classification is correct or incorrect.

- 10 points: 50% prediction score
  Your application predicts the correct classification for at least 50% of the images of the test data set.

- 10 points: 70% prediction score
  Your application predicts the correct classification for at least 70% of the images of the test data set.