.. _sec_imgquick:

Image Classification - Quick Start
==================================


In this quick start, we'll use the task of image classification to
illustrate how to use AutoGluon’s APIs.

In this tutorial, we load images and the corresponding labels into
AutoGluon and use this data to obtain a neural network that can classify
new images. This is different from traditional machine learning where we
need to manually define the neural network and then specify the
hyperparameters in the training process. Instead, with just a single
call to AutoGluon's
`fit </api/autogluon.task.html#autogluon.vision.ImageClassification.fit>`__
function, AutoGluon automatically trains many models with different
hyperparameter configurations and returns the model that achieved the
highest level of accuracy.

We begin by specifying
`ImageClassification </api/autogluon.task.html#autogluon.vision.ImageClassification>`__
as our task of interest as follows:

.. code:: python

    import autogluon.core as ag
    from autogluon.vision import ImageClassification as task

Create AutoGluon Dataset
------------------------

For demonstration purposes, we use a subset of the `Shopee-IET
dataset <https://www.kaggle.com/c/shopee-iet-machine-learning-competition/data>`__
from Kaggle. Each image in this data depicts a clothing item and the
corresponding label specifies its clothing category. Our subset of the
data contains the following possible labels: ``BabyPants``,
``BabyShirt``, ``womencasualshoes``, ``womenchiffontop``.

We download the data subset and unzip it using the following commands:

.. code:: python

    filename = ag.download('https://autogluon.s3.amazonaws.com/datasets/shopee-iet.zip')
    ag.unzip(filename)


.. parsed-literal::
    :class: output

    100%|██████████| 40895/40895 [00:01<00:00, 39821.37KB/s]




.. parsed-literal::
    :class: output

    'data'



After the dataset is downloaded, we load it into a
`Dataset </api/autogluon.task.html#autogluon.vision.ImageClassification.Dataset>`__
object:

.. code:: python

    dataset = task.Dataset('data/train')

Load the test dataset as follows:

.. code:: python

    test_dataset = task.Dataset('data/test', train=False)

If you don't have a GPU, change the dataset to 'FashionMNIST' to ensure
that it doesn't take too long to run:

.. code:: python

    if ag.get_gpu_count() == 0:
        dataset = task.Dataset(name='FashionMNIST')
        test_dataset = task.Dataset(name='FashionMNIST', train=False)

Use AutoGluon to Fit Models
---------------------------

Now, we fit a classifier using AutoGluon as follows:

.. code:: python

    classifier = task.fit(dataset,
                          epochs=5,
                          ngpus_per_trial=1,
                          verbose=False)


.. parsed-literal::
    :class: output

    scheduler: FIFOScheduler(
    DistributedResourceManager{
    (Remote: Remote REMOTE_ID: 0, 
    	<Remote: 'inproc://172.31.35.213/4917/1' processes=1 threads=8, memory=33.24 GB>, Resource: NodeResourceManager(8 CPUs, 1 GPUs))
    })
    



.. parsed-literal::
    :class: output

    HBox(children=(HTML(value=''), FloatProgress(value=0.0, max=2.0), HTML(value='')))


.. parsed-literal::
    :class: output

    
      0%|          | 0/5 [00:00<?, ?it/s]
    [Epoch 1] training: accuracy=0.292:   0%|          | 0/5 [00:08<?, ?it/s]
    [Epoch 1] Validation: 0.331:   0%|          | 0/5 [00:09<?, ?it/s]       
    [Epoch 1] Validation: 0.331:  20%|██        | 1/5 [00:09<00:39,  9.80s/it]
    [Epoch 2] training: accuracy=0.405:  20%|██        | 1/5 [00:18<00:39,  9.80s/it]
    [Epoch 2] Validation: 0.425:  40%|████      | 2/5 [00:19<00:29,  9.72s/it]
    
    [Epoch 3] training: accuracy=0.463:  40%|████      | 2/5 [00:27<00:29,  9.72s/it]
    [Epoch 3] Validation: 0.463:  40%|████      | 2/5 [00:28<00:29,  9.72s/it]       
    [Epoch 3] Validation: 0.463:  60%|██████    | 3/5 [00:28<00:19,  9.66s/it]
    [Epoch 4] training: accuracy=0.527:  60%|██████    | 3/5 [00:37<00:19,  9.66s/it]
    [Epoch 4] Validation: 0.481:  60%|██████    | 3/5 [00:38<00:19,  9.66s/it]       
    [Epoch 4] Validation: 0.481:  80%|████████  | 4/5 [00:38<00:09,  9.64s/it]
    [Epoch 5] training: accuracy=0.512:  80%|████████  | 4/5 [00:46<00:09,  9.64s/it]
    [Epoch 5] Validation: 0.500: 100%|██████████| 5/5 [00:48<00:00,  9.62s/it]
    
    [Epoch 5] Validation: 0.500: 100%|██████████| 5/5 [00:48<00:00,  9.60s/it]

.. parsed-literal::
    :class: output

    


.. parsed-literal::
    :class: output

    [Epoch 5] Validation: 0.544: 100%|██████████| 5/5 [00:48<00:00,  9.65s/it]
    [Epoch 5] training: accuracy=0.538: 100%|██████████| 5/5 [00:51<00:00, 10.28s/it]


Within ``fit``, the dataset is automatically split into training and
validation sets. The model with the best hyperparameter configuration is
selected based on its performance on the validation set. The best model
is finally retrained on our entire dataset (i.e., merging
training+validation) using the best configuration.

The best Top-1 accuracy achieved on the validation set is as follows:

.. code:: python

    print('Top-1 val acc: %.3f' % classifier.results['best_reward'])


.. parsed-literal::
    :class: output

    Top-1 val acc: 0.544


Predict on a New Image
----------------------

Given an example image, we can easily use the final model to ``predict``
the label (and the conditional class-probability):

.. code:: python

    # skip this if training FashionMNIST on CPU.
    if ag.get_gpu_count() > 0:
        image = 'data/test/BabyShirt/BabyShirt_323.jpg'
        ind, prob, _ = classifier.predict(image, plot=True)
    
        print('The input picture is classified as [%s], with probability %.2f.' %
              (dataset.init().classes[ind.asscalar()], prob.asscalar()))
    
        image = 'data/test/womenchiffontop/womenchiffontop_184.jpg'
        ind, prob, _ = classifier.predict(image, plot=True)
    
        print('The input picture is classified as [%s], with probability %.2f.' %
              (dataset.init().classes[ind.asscalar()], prob.asscalar()))



.. figure:: output_beginner_7db196_15_0.png


.. parsed-literal::
    :class: output

    The input picture is classified as [BabyShirt], with probability 0.55.



.. figure:: output_beginner_7db196_15_2.png


.. parsed-literal::
    :class: output

    The input picture is classified as [BabyShirt], with probability 0.37.


Evaluate on Test Dataset
------------------------

We now evaluate the classifier on a test dataset.

The validation and test top-1 accuracy are:

.. code:: python

    test_acc = classifier.evaluate(test_dataset)
    print('Top-1 test acc: %.3f' % test_acc)


.. parsed-literal::
    :class: output

    accuracy: 0.71875: 100%|██████████| 1/1 [00:01<00:00,  1.74s/it]

.. parsed-literal::
    :class: output

    Top-1 test acc: 0.719


.. parsed-literal::
    :class: output