Skip to content

Commit

Permalink
Updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@jasonjewik
jasonjewik committed Dec 7, 2024
1 parent fb6ba25 commit 1ae706e
Show file tree
Hide file tree
Showing 9 changed files with 845 additions and 632 deletions.
10 changes: 3 additions & 7 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,6 @@ The following code snippets show how to train and evaluate a model on classifyin
```console
python -m phenocam_snow.train \
canadaojp \
--model resnet18 \
--learning_rate 5e-4 \
--weight_decay 0.01 \
--new \
--n_train 120 \
--n_test 30 \
Expand All @@ -31,10 +28,9 @@ This will print out the file path of the best model, which can be substituted in
```console
python -m phenocam_snow.predict \
canadaojp \
[path/to/best_model.ckpt] \
resnet18 \
--categories snow no_snow too_dark
--url https://phenocam.nau.edu/data/latest/canadaojp.jpg
canadaojp_lightning_logs/version_0/checkpoints/epoch=12-step=78.ckpt \
--categories snow no_snow too_dark \
--directory 'canadaojp/test'
```

Advanced usage details can be found in the [documentation](http://phenocamsnow.readthedocs.io/).
Expand Down
96 changes: 54 additions & 42 deletions docs/source/user-guide/predict.rst
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
Classifying New Images
======================
Models produced by PhenoCamSnow can be used to generate predictions for all
images in a local directory, or to generate a prediction for a single image as
pointed to by URL.
images in a local directory, or to generate a prediction for images pointed to
by their URLs.

Local Prediction
----------------
Expand All @@ -16,15 +16,13 @@ following command.
python -m phenocam_snow.predict \
canadaojp \
canadaojp_lightning_logs/version_0/checkpoints/epoch=12-step=78.ckpt \
resnet18 \
--categories snow no_snow too_dark
--directory canadaojp_test
--categories snow no_snow too_dark \
--directory 'canadaojp/test'
The file path provided in the third line is printed by the model training
script. It is also saved in a file called ``best_model_paths.csv``. Ensure that
the categories provided are the same name and in the same order as provided
during training. Similarly, ensure that the ResNet variant specified is the
same as in training.
during training.

The program will then print out its predictions to a CSV file that looks like
this:
Expand All @@ -37,43 +35,44 @@ this:
# 0. snow
# 1. no_snow
# 2. too_dark
timestamp,label
2016-04-01 17:29:59,snow
2017-11-13 13:59:59,snow
2019-01-24 16:59:59,snow
2016-04-09 20:29:59,snow
2020-02-26 09:59:59,snow
2016-12-21 11:29:59,snow
2017-03-19 11:59:59,snow
2020-10-29 13:29:59,snow
2018-03-01 19:00:00,snow
2016-04-24 07:29:59,no_snow
2016-05-14 04:00:00,no_snow
2019-09-25 09:30:00,no_snow
2018-07-20 17:00:00,no_snow
2017-05-27 16:29:59,no_snow
2016-08-28 20:29:59,no_snow
2017-06-06 09:30:00,no_snow
2017-09-02 08:29:59,no_snow
2019-09-09 16:00:00,no_snow
2019-01-07 01:29:59,too_dark
2020-01-07 23:30:00,too_dark
2017-09-05 01:59:59,too_dark
2018-07-24 01:30:00,too_dark
2017-11-21 18:59:59,too_dark
2020-01-01 03:29:59,too_dark
2019-02-01 05:29:59,too_dark
2020-10-14 06:30:00,too_dark
2020-05-31 02:59:59,too_dark
2018-12-22 02:29:59,too_dark
2019-05-01 04:30:00,too_dark
2020-07-22 04:00:00,too_dark
filename,label
canadaojp_2020_04_25_052959.jpg,snow
canadaojp_2019_11_14_073000.jpg,snow
canadaojp_2020_01_08_155959.jpg,snow
canadaojp_2018_10_06_182959.jpg,no_snow
canadaojp_2019_05_30_040000.jpg,no_snow
canadaojp_2018_10_23_142959.jpg,no_snow
canadaojp_2018_04_27_083000.jpg,no_snow
canadaojp_2020_08_05_100000.jpg,no_snow
canadaojp_2020_07_13_215959.jpg,no_snow
canadaojp_2020_04_26_045959.jpg,no_snow
canadaojp_2020_07_01_205959.jpg,no_snow
canadaojp_2018_06_01_082959.jpg,no_snow
canadaojp_2020_05_30_065959.jpg,no_snow
canadaojp_2020_06_11_033000.jpg,no_snow
canadaojp_2019_05_10_112959.jpg,no_snow
canadaojp_2020_04_09_232959.jpg,too_dark
canadaojp_2018_10_31_182959.jpg,too_dark
canadaojp_2019_08_31_000000.jpg,too_dark
canadaojp_2020_02_01_075959.jpg,too_dark
canadaojp_2018_12_18_185959.jpg,too_dark
canadaojp_2020_03_05_012959.jpg,too_dark
canadaojp_2020_04_22_035959.jpg,too_dark
canadaojp_2020_05_02_032959.jpg,too_dark
canadaojp_2018_12_29_052959.jpg,too_dark
canadaojp_2020_04_24_025959.jpg,too_dark
canadaojp_2020_04_11_232959.jpg,too_dark
canadaojp_2018_11_20_065959.jpg,too_dark
canadaojp_2019_02_25_192959.jpg,too_dark
canadaojp_2020_03_30_232959.jpg,too_dark
canadaojp_2018_06_15_003000.jpg,too_dark
Online Prediction
-----------------

PhenoCamSnow is also capable of generating a prediction for a single online
image, as pointed to by a URL. For example, using canadaojp again:
PhenoCamSnow is also capable of generating a prediction for online images as
as pointed to by their URLs. For example, using canadaojp again:

.. code-block:: bash
:linenos:
Expand All @@ -83,9 +82,22 @@ image, as pointed to by a URL. For example, using canadaojp again:
canadaojp_lightning_logs/version_0/checkpoints/epoch=12-step=78.ckpt \
resnet18 \
--categories snow no_snow too_dark
--url https://phenocam.nau.edu/data/latest/canadaojp.jpg
--urls urls.txt
Here, ``urls.txt`` is a file containing one image URL per line. The program
will write its predictions to a CSV file, formatted similarly to the one shown
for offline prediction.

Getting Help
------------

You can see a help message displayed by running:

.. code-block:: bash
:linenos:
python -m phenocam_snow.predict --help
The program will print its prediction to the console. E.g., ``no_snow``.
If you have further questions, please raise an
`issue on the GitHub repository <https://github.com/jasonjewik/PhenoCamSnow/issues/new/choose>`_.
90 changes: 72 additions & 18 deletions docs/source/user-guide/train.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,6 @@ spaces: use underscores instead.
python -m phenocam_snow.train \
canadaojp \
--model resnet18 \
--learning_rate 5e-4 \
--weight_decay 0.01 \
--new \
--n_train 120 \
--n_test 30 \
Expand All @@ -28,19 +25,9 @@ evaluating the model's performance. After each set of images is downloaded,
the program will prompt you to label the images. To do so, it will create
three sub-directories inside of the current directory, each named after one of
the classes. Move the images into their corresponding directory (e.g., all the
pictures with snow should go into the "snow" directory) to label them.

You can also change the model. Currently, PhenocamSnow only supports training
`ResNet <https://arxiv.org/abs/1512.03385/>`_ variants: ResNet-18, ResNet-34,
ResNet-50, ResNet-101, and ResNet-152. The expected format is "resnet{number}".
The larger the number, the more expressive the model, but the slower it might
be to train.

The learning rate and weight decay arguments are hyperparameters for the model.
The "new" flag indicates that you need to download the training and testing
images. In this case, we will be getting 120 training images and 30 testing
images. Empirically, I found this to work well for canadaojp (93% accuracy
on the testing images).
pictures with snow should go into the "snow" directory) to label them. After
the images are labeled, they will be moved out of the sub-directories back into
the original top-level directory.

When the program has finished training the model, it will print out the model's
performance on the testing images and the file path of the saved best model.
Expand All @@ -53,8 +40,75 @@ which will look something like this:
timestamp,site_name,best_model
2023-05-24T15:45:59.642605,canadaojp,/home/jason/Development/test/canadaojp_lightning_logs/version_0/checkpoints/epoch=12-step=78.ckpt
To get the model's predictions for a set of images, see the next section of the
documentation.
To get the model's predictions for a set of images, see the User Guide page
called "Classifying New Images".

Advanced Usage
--------------

Overriding Model and Hyperparameter Defaults
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Currently, PhenoCamSnow only supports training models which use `ResNet <https://arxiv.org/abs/1512.03385/>`_
variants as the feature extraction backbone: ResNet-18, ResNet-34, ResNet-50,
ResNet-101, and ResNet-152. The expected format is "resnet{number}". The larger
the number, the more expressive the model, but the slower it might be to train.
PhenoCamSnow also allows you to specify learning rate, weight decay, and max
epochs hyperparameters. I have picked what I determined to be sensible
defaults, but these all should be tuned for your specific use-case. In short:

* The learning rate affects the speed at which the model learns (too small and the model will learn slowly, too high and the model might overshoot its optimal parameters).

* The weight decay affects the model's generalization abilities (too low and the model might "memorize" the training set and perform poorly on images it has not seen in training).

* The max epochs determines how many training "sessions" the model will run, at most (too few and the model might not have sufficient time to learn well, too many and the model might simply "memorize" the training set).

Previous example with the ResNet-50 model and some hyperparameter overrides:

.. code-block:: bash
:linenos:
python -m phenocam_snow.train \
canadaojp \
--new \
--n_train 120 \
--n_test 30 \
--classes snow no_snow too_dark
--model resnet50
--learning_rate 1e-3
--weight_decay 1e-3
--max_epochs 25
Training a Model with Already-Downloaded Images
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The "new" flag in the given examples indicates that you need to download the
training and testing images. In this case, we will be getting 120 training
images and 30 testing images.

However, if you already have downloaded and labeled images, then you can train
a model like this (assuming the directories provided for ``train_dir`` and
``test_dir`` actually exist and contain the required images and labels files).

.. code-block:: bash
:linenos:
python -m phenocam_snow.train \
canadaojp \
--existing
--train_dir 'canadaojp/train'
--test_dir 'canadaojp/test'
--classes snow no_snow too_dark
Getting Help
^^^^^^^^^^^^

You can see a help message displayed by running:

.. code-block:: bash
:linenos:
python -m phenocam_snow.train --help
If you have further questions, please raise an
`issue on the GitHub repository <https://github.com/jasonjewik/PhenoCamSnow/issues/new/choose>`_.
Loading

0 comments on commit 1ae706e

Please sign in to comment.