Initial commit

.coveragerc

@@ -0,0 +1,23 @@
+[run]
+branch = True
+source =
+    cv4e_lecture13
+omit =
+    setup.py
+
+[report]
+exclude_lines =
+    pragma: no cover
+    # NOCC
+    raise NotImplementedError
+    if __name__ == .__main__.:
+precision = 1
+ignore_errors = True
+omit =
+    tests/*
+
+[html]
+directory = ./coverage/html/
+
+[xml]
+output = ./coverage/coverage.xml

.github/workflows/codeql-analysis.yml

@@ -0,0 +1,34 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  schedule:
+    - cron: '0 0 * * 1'
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'python' ]
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v1
+      with:
+        languages: ${{ matrix.language }}
+
+    - name: Autobuild
+      uses: github/codeql-action/autobuild@v1
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v1

.github/workflows/docker-publish.yaml

@@ -0,0 +1,25 @@
+name: Docker
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+    tags:
+      - v*
+  schedule:
+    - cron: '0 16 * * *' # Every day at 16:00 UTC (~09:00 PT)
+
+jobs:
+  deploy:
+    name: Build Docker Image
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Build
+        run: |
+          docker build . -t cv4e/lecture13:latest

.github/workflows/python-publish.yml

@@ -0,0 +1,74 @@
+name: Wheel
+
+# Build on every branch push, tag push, and pull request change:
+on: push
+
+jobs:
+
+  build_wheels:
+    name: Build on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: [3.8]
+
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          # This allows the setuptools_scm library to discover the tag version from git
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v2
+        name: Install Python
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Build wheel
+        run: |
+          pip install --upgrade pip
+          pip install build
+          python -m build --wheel --outdir dist/ .
+
+      - uses: actions/upload-artifact@v2
+        with:
+          path: ./dist/*.whl
+
+  build_sdist:
+    name: Build source distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: actions/setup-python@v2
+        name: Install Python
+        with:
+          python-version: '3.8'
+
+      - name: Build sdist
+        run: |
+          pip install --upgrade pip
+          pip install build
+          python -m build --sdist --outdir dist/ .
+
+      - uses: actions/upload-artifact@v2
+        with:
+          path: ./dist/*.tar.gz
+
+  # upload_pypi:
+  #   needs: [build_wheels, build_sdist]
+  #   runs-on: ubuntu-latest
+  #   # upload to PyPI on every tag starting with 'v'
+  #   if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags/v')
+  #   steps:
+  #     - uses: actions/download-artifact@v2
+  #       with:
+  #         name: artifact
+  #         path: dist
+
+  #     - uses: pypa/gh-action-pypi-publish@master
+  #       with:
+  #         user: __token__
+  #         password: ${{ secrets.PYPI_PASSWORD }}
+  #         # To test: repository_url: https://test.pypi.org/legacy/

.github/workflows/testing.yml

@@ -0,0 +1,49 @@
+# This workflow will install Python dependencies, run tests and lint with a single version of Python
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+
+name: Testing
+
+on: push
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Use the same Python version used the Dockerfile
+        python-version: [3.9]
+    env:
+      OS: ubuntu-latest
+      PYTHON: ${{ matrix.python-version }}
+    steps:
+      # Checkout and env setup
+      - uses: actions/checkout@v2
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+
+      - name: Lint with flake8
+        run: |
+          # stop the build if there are Python syntax errors or undefined names
+          flake8 . --count --show-source --statistics
+          # exit-zero treats all errors as warnings.
+          flake8 . --count --exit-zero --max-complexity=10 --statistics
+
+      - name: Run tests
+        run: |
+          set -ex
+          pytest --cov=./ --cov-append --random-order-seed=1
+
+      - name: Run coverage
+        run: |
+          coverage xml html
+        env:
+          LOG_WIDTH: 120

.gitignore

@@ -0,0 +1,12 @@
+.DS_Store
+output.*.jpg
+*.log*
+
+*.egg-info/
+
+cv4e_lecture13/datasets/
+.coverage
+coverage/
+
+__pycache__/
+docs/build

.pre-commit-config.yaml

@@ -0,0 +1,39 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+  - repo: https://github.com/asottile/pyupgrade
+    rev: v2.32.0
+    hooks:
+      - id: pyupgrade
+        name: pyupgrade
+        description: Run PyUpgrade on Python code.
+  - repo: https://github.com/pycqa/isort
+    rev: 5.10.1
+    hooks:
+      - id: isort
+        args: [--settings-path setup.cfg]
+        name: isort
+        description: Run import sorting (isort) on Python code.
+  - repo: local
+    hooks:
+      - id: brunette
+        name: brunette
+        description: Run Brunette on Python code (fork of Black).
+        entry: brunette --config=setup.cfg
+        language: system
+        types: [python]
+  - repo: https://gitlab.com/pycqa/flake8
+    rev: 3.8.3
+    hooks:
+      - id: flake8
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v3.1.0
+    hooks:
+      - id: check-ast
+      - id: check-executables-have-shebangs
+      - id: check-docstring-first
+      - id: double-quote-string-fixer
+      - id: trailing-whitespace
+      - id: mixed-line-ending
+      - id: end-of-file-fixer
+      - id: fix-encoding-pragma

.readthedocs.yaml

@@ -0,0 +1,23 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+   os: ubuntu-22.04
+   tools:
+     python: "3.10"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# Optionally declare the Python requirements required to build your docs
+python:
+   install:
+   - requirements: docs/requirements.txt
+   - method: pip
+     path: .

CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing
+
+All contributions are welcome and encouraged. There are a few guidelines and styling aspects that we require and encourage you to use so that we might see this project through many years of successful development.
+
+## Development Guidelines
+
+### Pull Request Checklist
+
+To submit a pull request (PR), we require the following standards to be enforced.  Details on how to configure and pass each of these required checks is detailed in the sections in this guideline section.
+
+* **Ensure that the PR is properly formatted**
+* **Ensure that the PR is properly rebased**
+* **Ensure that the PR is properly tested**
+* **Ensure that the PR is properly covered**
+* **Ensure that the PR is properly sanitized**
+* **Ensure that the PR is properly reviewed**
+
+## Code Style
+
+The code is generally in PEP8 compliance, enforced by flake8 via pre-commit.
+
+Our code uses Google-style docstrings. See examples of this in [Example Google Style Python Docstrings](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html#example-google).
+
+### Pre-commit
+
+It's recommended that you use `pre-commit` to ensure linting procedures are run
+on any commit you make. (See also [pre-commit.com](https://pre-commit.com/)
+
+Reference [pre-commit's installation instructions](https://pre-commit.com/#install) for software installation on your OS/platform. After you have the software installed, run ``pre-commit install`` on the command line. Now every time you commit to this project's code base the linter procedures will automatically run over the changed files.  To run pre-commit on files preemtively from the command line use:
+
+```bash
+  git add .
+  pre-commit run
+
+  # or
+
+  pre-commit run --all-files
+```
+
+See `.pre-commit-config.yaml` for a list of configured linters and fixers.

Dockerfile

@@ -0,0 +1,25 @@
+# FROM nvidia/cuda:11.3.1-cudnn8-runtime-ubuntu20.04
+FROM continuumio/anaconda3:latest
+
+ENV GRADIO_SERVER_PORT 5000
+
+# Install apt packages
+RUN set -ex \
+ && apt-get update \
+ && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+        git \
+        htop \
+ && rm -rf /var/cache/apt \
+ && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /code
+
+COPY ./ /code
+
+RUN conda install pip \
+ && pip install -r requirements.txt
+
+# Port for the web server
+EXPOSE 5000
+
+ENTRYPOINT ["python app.py"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) ECEO, EPFL. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE

MANIFEST.in

@@ -0,0 +1,7 @@
+include pyproject.toml
+
+# Include the README and SECURITY documents
+include *.rst
+
+# Include the license file
+include LICENSE

README.rst

@@ -0,0 +1,109 @@
+
+================================================
+Lecture 1: Dataset Prototyping and Visualization
+================================================
+
+.. contents:: Quick Links
+    :backlinks: none
+
+.. sectnum::
+
+Introduction
+------------
+
+.. image:: https://github.com/CV4EcologySchool/Lecture-1/raw/main/intro.jpg
+    :target: https://docs.google.com/presentation/d/1Bm9ZvQC6Y1SW_xAHHbMvhsRRb87tgzIimM0YKEXEA6w/edit?usp=sharing
+    :alt: "Lecture 1: Dataset Prototyping and Visualization"
+
+This repository holds the lecture materials for the `Computer Vision for Ecology workshop at CalTech <https://cv4ecology.caltech.edu>`_.  The goal of this lecture is to describe which qualities are idea for prototype ML datasets and a review of PyTorch's DataLoaders and Tensors.  Lecture 1 also reviews the overall lecture structure for the three week course, review the milestone due tomorrow (Week 1, Day 2), review the tools and technologies and terms that are common for ML applications.
+
+The associated slides for this lecture can be viewed by clicking on the image above.
+
+How to Install
+--------------
+
+You need to first install Anaconda on your machine.  Below are the instructions on how to install Anaconda on an Apple macOS machine, but it is possible to install on a Windows and Linux machine as well.  Consult the `official Anaconda page <https://www.anaconda.com>`_ to download and install on other systems.  For Windows computers, it is highly recommended that you intall the `Windows Subsystem for Linux <https://docs.microsoft.com/en-us/windows/wsl/install>`_.
+
+.. code:: bash
+
+   # Install Homebrew
+   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+   # Install Anaconda and expose conda to the terminal
+   brew install anaconda
+   export PATH="/opt/homebrew/anaconda3/bin:$PATH"
+   conda init zsh
+   conda update conda
+
+Once Anaconda is installed, you will need an environment and the following packages installed
+
+.. code:: bash
+   
+   # Create Environment
+   conda create --name cv4e
+   conda activate cv4e
+
+   # Install Python dependencies
+   conda install pip
+
+   conda install -r requirements.txt 
+   conda install pytorch torchvision -c pytorch-nightly
+
+How to Run
+----------
+
+The lecture materials will run as a single executable.  The MNIST dataset must be downloaded from the internet for this script to run correctly, so Internet access is required at first to download the files once.  It is recommended to use `ipython` and to copy sections of code into and inspecting the 
+
+.. code:: bash
+   
+   # Run with Python
+   python lecture.py
+
+   # Run with iPython
+   ipython lecture.py
+
+   # Run as an executable
+   ./lecture.py
+
+Logging
+-------
+
+The script uses Python's built-in logging functionality called `logging`.  All print functions are replaced with `log.info` within this script, which sends the output to two places: 1) the terminal window, 2) the file `lecture_1.log`.  Get into the habit of writing text logs and keeping date-specific versions for comparison and debugging.
+
+Code Formatting (Optional)
+--------------------------
+
+It's recommended that you use ``pre-commit`` to ensure linting procedures are run
+on any code you write. (See also `pre-commit.com <https://pre-commit.com/>`_)
+
+Reference `pre-commit's installation instructions <https://pre-commit.com/#install>`_ for software installation on your OS/platform. After you have the software installed, run ``pre-commit install`` on the command line. Now every time you commit to this project's code base the linter procedures will automatically run over the changed files.  To run pre-commit on files preemtively from the command line use:
+
+.. code:: bash
+
+    git add .
+    pre-commit run
+
+    # or
+
+    pre-commit run --all-files
+
+The code base has been formatted by Brunette, which is a fork and more configurable version of Black (https://black.readthedocs.io/en/stable/).  Furthermore, try to conform to PEP8.  You should set up your preferred editor to use flake8 as its Python linter, but pre-commit will ensure compliance before a git commit is completed.  This will use the flake8 configuration within ``setup.cfg``, which ignores several errors and stylistic considerations.  See the ``setup.cfg`` file for a full and accurate listing of stylistic codes to ignore.
+
+See Also
+--------
+
+- https://github.com/readthedocs-examples/example-sphinx-basic/
+- https://github.com/CV4EcologySchool/ct_classifier
+- https://docs.python.org/3/distutils/setupscript.html
+
+
+
+brew install openssl
+
+docker build . -t cv4e/lecture13:latest
+
+pytest
+
+coverage html
+
+sphinx-build -M html . _build/

app.py

@@ -0,0 +1,54 @@
+from cv4e_lecture13 import model, utils
+import torch
+from PIL import Image, ImageOps  # NOQA
+from torchvision.transforms import Compose, Resize, ToTensor
+import gradio as gr
+
+
+config = 'cv4e_lecture13/configs/mnist_resnet18.yaml'
+
+log = utils.init_logging()
+cfg = utils.init_config(config, log)
+device = cfg.get('device')
+
+cfg['output'] = 'cv4e_lecture13/%s' % (cfg['output'], )
+
+net, _, _ = model.load(cfg)
+net.eval()
+
+
+def predict(inp):
+    inp = ImageOps.grayscale(inp)
+
+    transforms = Compose([             
+        Resize((cfg['image_size'])), 
+        ToTensor()                   
+    ])
+    inp = transforms(inp).unsqueeze(0)
+    data = inp.to(device)
+
+    with torch.no_grad():
+        prediction = net(data)
+
+    confidences = torch.softmax(prediction[0], dim=0).cpu().numpy()
+    confidences = list(enumerate(confidences))
+    confidences = [
+        (str(label), float(conf) , )
+        for label, conf in confidences
+    ]
+    confidences = dict(confidences)
+
+    return confidences
+
+
+interface = gr.Interface(
+    fn=predict, 
+    inputs=gr.Image(type='pil'),
+    outputs=gr.Label(num_top_classes=3),
+    examples=[
+        f'examples/example_{index}.jpg'
+        for index in range(1, 31)
+    ]
+)
+
+interface.launch()

cv4e_lecture13/__init__.py

@@ -0,0 +1,9 @@
+'''
+    2022 Benjamin Kellenberger
+'''
+
+# Info: these "__init__.py" files go into every folder and subfolder that
+# contains Python code. It is required for Python to find all the scripts you
+# created and for you to be able to import them.
+version = '0.1.0'
+__version__ = version

cv4e_lecture13/configs/mnist_resnet18.yaml

@@ -0,0 +1,21 @@
+# Here's where you define experiment-specific hyperparameters.
+# You can also create lists and group parameters together into nested sub-parts.
+# In Python, this is all read as a dict.
+
+# environment/computational parameters
+seed: 1
+device: cuda
+num_workers: 4
+
+# dataset parameters
+num_classes: 10
+
+# training hyperparameters
+image_size: [32, 32]
+max_epochs: 16
+batch_size: 128
+learning_rate: 0.001
+weight_decay: 0.001
+
+# output params
+output: models

cv4e_lecture13/dataset.py

@@ -0,0 +1,51 @@
+'''
+    Model implementation.
+    We'll be using a "simple" ResNet-18 for image classification here.
+
+    2022 Benjamin Kellenberger
+'''
+import torch
+from torchvision import datasets
+from torchvision.transforms import Compose, Resize, ToTensor
+from os.path import abspath
+
+
+def load(cfg):
+    """
+    Load the MNIST dataset from PyTorch (download if needed) and return a DataLoader
+
+    MNIST is a sample dataset for machine learning, each image is 28-pixels high and 28-pixels wide (1 color channel)
+    """
+    root = abspath('datasets')
+
+    train = torch.utils.data.DataLoader(
+        datasets.MNIST(
+            root, 
+            train=True, 
+            transform=Compose([             
+                Resize((cfg['image_size'])), 
+                ToTensor()                   
+            ]),
+            download=True
+        ), 
+        batch_size=cfg.get('batch_size'), 
+        shuffle=True, 
+        num_workers=cfg.get('num_workers')
+    )
+    
+    test = torch.utils.data.DataLoader(
+        datasets.MNIST(
+            root, 
+            train=False, 
+            transform=Compose([             
+                Resize((cfg['image_size'])), 
+                ToTensor()                   
+            ]),
+            download=True
+        ), 
+        batch_size=cfg.get('batch_size'), 
+        shuffle=False, 
+        num_workers=cfg.get('num_workers')
+    )
+
+    return train, test

cv4e_lecture13/model.py

@@ -0,0 +1,96 @@
+'''
+    Model implementation.
+    We'll be using a "simple" ResNet-18 for image classification here.
+
+    2022 Benjamin Kellenberger
+'''
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+import numpy as np
+import glob
+import os
+from os.path import split, splitext, exists
+
+
+class SmallModel(nn.Module):
+
+    @classmethod
+    def load(cls, cfg):
+        log = cfg.get('log')
+
+        net = cls()
+
+        epoch = 0
+        best_loss = np.inf
+
+        output = cfg.get('output')
+
+        filepaths = sorted(glob.glob(f'{output}/*.pt'))
+
+        if len(filepaths) > 1:
+            filepaths = [
+                filepath 
+                for filepath in filepaths 
+                if 'best.pt' not in filepath
+            ]
+
+        if len(filepaths):
+            filepath = filepaths[-1]
+
+            log.info(f'Resuming from {filepath}')
+
+            state = torch.load(open(filepath, 'rb'), map_location='cpu')
+            net.load_state_dict(state['model'])
+
+            filename = split(filepath)[1]
+            try:
+                epoch = int(splitext(filename)[0])
+            except ValueError:
+                pass
+                
+            filepath = f'{output}/best.pt'
+            if exists(filepath):
+                state = torch.load(open(filepath, 'rb'), map_location='cpu')
+                best_loss = state['loss_val']
+        else:
+            log.info('Starting new network model')
+
+        device = cfg.get('device')
+        net.to(device)
+
+        return net, epoch, best_loss
+
+    def __init__(self):
+        super(SmallModel, self).__init__()
+        self.conv1 = nn.Conv2d(1, 16, 5)
+        self.conv2 = nn.Conv2d(16, 32, 5)
+        self.fc1 = nn.Linear(32 * 5 * 5, 128)
+        self.fc2 = nn.Linear(128, 128)
+        self.fc3 = nn.Linear(128, 10)
+
+    def forward(self, x):
+        x = F.max_pool2d(F.relu(self.conv1(x)), (2, 2))
+        x = F.max_pool2d(F.relu(self.conv2(x)), 2)
+        x = torch.flatten(x, 1) 
+        x = F.relu(self.fc1(x))
+        x = F.relu(self.fc2(x))
+        x = self.fc3(x)
+        return x
+
+    def save(self, cfg, epoch, stats, best=False):
+        output = cfg.get('output')
+
+        os.makedirs(output, exist_ok=True)
+
+        stats['model'] = self.state_dict()
+
+        torch.save(stats, open(f'{output}/{epoch:04d}.pt', 'wb'))
+
+        if best:
+            torch.save(stats, open(f'{output}/best.pt', 'wb'))
+
+
+def load(cfg):
+    return SmallModel.load(cfg)

cv4e_lecture13/train.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""
+The lecture materials for Lecture 1: Dataset Prototyping and Visualization
+"""
+from . import model, dataset, utils
+import torch
+import click
+import torch.nn as nn
+from tqdm import trange
+from torch.optim import Adam
+
+
+log = None
+
+
+def inference(cfg, dataloader, net, optimizer, criterion, update):
+    '''
+        Our actual training function.
+    '''
+    device = cfg.get('device')
+
+    torch.set_grad_enabled(update)
+    net.train() if update else net.eval()
+    type_str = 'Train' if update else 'Val'
+
+    loss, accuracy = 0.0, 0.0
+    total = len(dataloader)
+
+    prog = trange(total)
+    for index, (data, labels) in enumerate(dataloader):
+        data, labels = data.to(device), labels.to(device)
+
+        prediction = net(data)
+        gradient = criterion(prediction, labels)
+
+        if update:
+            optimizer.zero_grad()
+            gradient.backward()
+            optimizer.step()
+
+        # log statistics
+        loss += gradient.item()
+        label_ = torch.argmax(prediction, dim=1)
+        accuracy += torch.mean((label_ == labels).float()).item()
+
+        prog.set_description('[{:s}] Loss: {:.2f}; Acc: {:.2f}%'.format(type_str, loss / (index + 1), 100.0 * accuracy / (index + 1)))
+        prog.update(1)
+    prog.close()
+    
+    loss /= total
+    accuracy /= total
+
+    return loss, accuracy
+
+
+@click.command()
+@click.option('--config', help='Path to config file', default='configs/mnist_resnet18.yaml')
+def lecture(config):
+    """
+    Main function for Lecture 1: Dataset Prototyping and Visualization
+    """
+    global log
+
+    log = utils.init_logging()
+
+    cfg = utils.init_config(config, log)
+
+    # init random number generator seed (set at the start)
+    utils.init_seed(cfg.get('seed', None))
+
+    ################################################################################
+    # Load MNIST
+    train, test = dataset.load(cfg)
+
+    net, epoch, best_loss = model.load(cfg)
+
+    optimizer = Adam(
+        net.parameters(),
+        lr=cfg.get('learning_rate'),
+        weight_decay=cfg.get('weight_decay'),
+    )
+    criterion = nn.CrossEntropyLoss()
+
+    epochs = cfg.get('max_epochs')
+    while epoch < epochs:
+        log.info(f'Epoch {epoch}/{epochs}')
+
+        loss_train, accuracy_train = inference(cfg, train, net, optimizer, criterion, update=True)
+        loss_test, accuracy_test = inference(cfg, test, net, optimizer, criterion, update=False)
+
+        # combine stats and save
+        stats = {
+            'loss_train': loss_train,
+            'loss_val': loss_test,
+            'accuracy_train': accuracy_train,
+            'accuracy_test': accuracy_test
+        }
+
+        best = loss_test < best_loss
+        net.save(cfg, epoch, stats, best=best)
+        if not best:
+            log.warning('Stopping early')
+            break
+
+        best_loss = loss_test
+        epoch += 1
+
+
+if __name__ == '__main__':
+    # Common boiler-plating needed to run the code from the command line as `python lecture.py` or `./lecture.py`
+    # This if condition will be False if the file is imported
+    lecture()

cv4e_lecture13/utils.py

@@ -0,0 +1,111 @@
+'''
+    Various utility functions used (possibly) across scripts.
+
+    2022 Benjamin Kellenberger
+'''
+
+import random
+import torch
+from torch.backends import cudnn
+import logging
+from logging.handlers import TimedRotatingFileHandler
+import yaml
+
+
+DAYS = 21
+
+
+def init_logging():
+    """
+    Setup Python's built in logging functionality with on-disk logging, and prettier logging with Rich
+    """
+    # Import Rich
+    import rich
+    from rich.logging import RichHandler
+    from rich.style import Style
+    from rich.theme import Theme
+
+    name = 'lecture_1'
+
+    # Setup placeholder for logging handlers
+    handlers = []
+
+    # Configuration arguments for console, handlers, and logging
+    console_kwargs = {
+        'theme': Theme(
+            {
+                'logging.keyword': Style(bold=True, color='yellow'),
+                'logging.level.notset': Style(dim=True),
+                'logging.level.debug': Style(color='cyan'),
+                'logging.level.info': Style(color='green'),
+                'logging.level.warning': Style(color='yellow'),
+                'logging.level.error': Style(color='red', bold=True),
+                'logging.level.critical': Style(color='red', bold=True, reverse=True),
+                'log.time': Style(color='white'),
+            }
+        )
+    }
+    handler_kwargs = {
+        'rich_tracebacks': True,
+        'tracebacks_show_locals': True,
+    }
+    logging_kwargs = {
+        'level': logging.INFO,
+        'format': '[%(name)s] %(message)s',
+        'datefmt': '[%X]',
+    }
+
+    # Add file-baesd log handler
+    handlers.append(
+        TimedRotatingFileHandler(
+            filename=f'{name}.log',
+            when='midnight',
+            backupCount=DAYS,
+        ),
+    )
+
+    # Add rich (fancy logging) log handler
+    rich.reconfigure(**console_kwargs)
+    handlers.append(RichHandler(**handler_kwargs))
+
+    # Setup global logger with the handlers and set the default level to INFO
+    logging.basicConfig(handlers=handlers, **logging_kwargs)
+    logger = logging.getLogger()
+    logger.setLevel(logging.INFO)
+    log = logging.getLogger(name)
+
+    return log
+
+
+def init_seed(seed):
+    if seed is not None:
+        random.seed(seed)
+        # numpy.random.seed(seed)       # we don't use NumPy in this code, but you would want to set its random number generator seed, too
+        torch.manual_seed(seed)
+        torch.cuda.manual_seed(seed)
+        cudnn.benchmark = True
+        cudnn.deterministic = True
+
+
+def init_config(config, log):
+    # load config
+    log.info(f'Using config "{config}"')
+    cfg = yaml.safe_load(open(config, 'r'))
+
+    cfg['log'] = log
+
+    # check if GPU is available
+    device = cfg.get('device')
+    if device not in ['cpu']:
+        if torch.cuda.is_available():
+            cfg['device'] = 'cuda'
+        elif torch.backends.mps.is_available():
+            cfg['device'] = 'mps'
+        else:
+            log.warning(f'WARNING: device set to "{device}" but not available; falling back to CPU...')
+            cfg['device'] = 'cpu'
+
+    device = cfg.get('device')
+    log.info(f'Using device "{device}"')
+
+    return cfg

docs/conf.py

@@ -0,0 +1,63 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "CV4Ecology School, Lecture 13"
+copyright = "2022"
+author = "CV4EcologySchool"
+
+
+# -- General configuration ---------------------------------------------------
+# -- General configuration
+
+extensions = [
+    "sphinx.ext.duration",
+    "sphinx.ext.doctest",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+]
+
+intersphinx_mapping = {
+    "rtd": ("https://docs.readthedocs.io/en/stable/", None),
+    "python": ("https://docs.python.org/3/", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
+}
+intersphinx_disabled_domains = ["std"]
+
+templates_path = ["_templates"]
+
+# -- Options for EPUB output
+epub_show_urls = "footnote"
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]

docs/index.rst

@@ -0,0 +1,14 @@
+.. include:: ../README.rst
+
+.. note::
+
+   This project is under active development.
+
+Contents
+--------
+
+.. toctree::
+
+   Home <self>
+   usage
+   package

docs/package.rst

@@ -0,0 +1,39 @@
+Package
+=======
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Contents:
+
+
+dataset.py
+----------
+
+.. automodule:: cv4e_lecture13.dataset
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+model.py
+----------
+
+.. automodule:: cv4e_lecture13.model
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+train.py
+--------
+
+.. automodule:: cv4e_lecture13.train
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+utils.py
+--------
+
+.. automodule:: cv4e_lecture13.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/usage.rst

@@ -0,0 +1,19 @@
+Usage
+=====
+
+.. _installation:
+
+Installation
+------------
+
+To use this code, first install its dependencies using pip:
+
+.. code-block:: console
+
+   (.venv) $ pip install -r requirements.txt
+
+then, you can run the application via:
+
+.. code-block:: console
+
+   (.venv) $ python app.py