✨ Add ResNet-20, corruptions and improve docs

.github/workflows/build-docs.yml

@@ -17,13 +17,14 @@ jobs:
   documentation:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
 
     - name: Set up Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ env.PYTHON_VERSION }}
         cache: "pip"
+        cache-dependency-path: "pyproject.toml"
 
     - name: Full Python version
       run: |
@@ -40,9 +41,10 @@ jobs:
     - name: Install dependencies
       run: |
         python3 -m pip install torch torchvision --extra-index-url https://download.pytorch.org/whl/cpu
-        python3 -m pip install .[dev,docs]
+        python3 -m pip install .[image,dev,docs]
 
     - name: Sphinx build
+      if: github.event.pull_request.draft == false
       run: |
         cd docs && make clean && make html
 

.github/workflows/pypi-publish.yml

@@ -10,10 +10,10 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "3.10"
 

.github/workflows/run-tests.yml

@@ -22,13 +22,14 @@ jobs:
     env:
       PYTHON_VERSION: ${{ matrix.python-version }}
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
 
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
         cache: "pip"
+        cache-dependency-path: "pyproject.toml"
 
     # Update full Python version
     - name: Full Python version
@@ -44,8 +45,11 @@ jobs:
           auto_tutorials_source/**
           data/**
           experiments/**
-          README.md
-          CONTRIBUTING.md
+          *.md
+          *.yaml
+          *.yml
+          LICENSE
+          .gitignore
 
     - name: Cache folder for Torch Uncertainty
       if: steps.changed-files-specific.outputs.only_changed != 'true'
@@ -60,12 +64,12 @@ jobs:
       if: steps.changed-files-specific.outputs.only_changed != 'true'
       run: |
         python3 -m pip install torch torchvision --extra-index-url https://download.pytorch.org/whl/cpu
-        python3 -m pip install .[dev,docs]
+        python3 -m pip install .[image,dev,docs]
 
     - name: Check style & format
       if: steps.changed-files-specific.outputs.only_changed != 'true'
       run: |
-        python3 -m ruff check torch_uncertainty tests --no-fix --exit-non-zero-on-fix
+        python3 -m ruff check torch_uncertainty tests --no-fix
         python3 -m ruff format torch_uncertainty tests --check
 
     - name: Test with pytest and compute coverage

.pre-commit-config.yaml

@@ -38,8 +38,3 @@ repos:
     language: python
     types_or: [python, pyi]
     exclude: ^auto_tutorials_source/
-  # - id: pytest-check
-  #   name: pytest-check
-  #   entry: pytest
-  #   language: system
-  #   pass_filenames: false

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2023 Adrien Lafage and Olivier Laurent
+   Copyright 2023-2024 Adrien Lafage and Olivier Laurent
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

auto_tutorials_source/tutorial_bayesian.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-
 """
 Train a Bayesian Neural Network in Three Minutes
 ================================================

auto_tutorials_source/tutorial_corruptions.py

@@ -0,0 +1,117 @@
+"""
+Image Corruptions
+=================
+
+This tutorial shows the impact of the different corruptions available in the
+TorchUncertainty library. These corruptions were first proposed in the paper
+Benchmarking Neural Network Robustness to Common Corruptions and Perturbations
+by Dan Hendrycks and Thomas Dietterich.
+
+For this tutorial, we will only load the corruption transforms available in 
+torch_uncertainty.transforms.corruptions. We also need to load utilities from
+torchvision and matplotlib.
+"""
+import torch
+from torchvision.datasets import CIFAR10
+from torchvision.transforms import Compose, ToTensor, Resize
+
+from torchvision.utils import make_grid
+import matplotlib.pyplot as plt
+plt.axis('off')
+ds = CIFAR10("./data", train=False, download=True)
+
+def get_images(main_transform, severity):
+    ds_transforms = Compose([ToTensor(), main_transform(severity), Resize(256)])
+    ds = CIFAR10("./data", train=False, download=False, transform=ds_transforms)
+    return make_grid([ds[i][0] for i in range(6)]).permute(1, 2, 0)
+
+def show_images(transform):
+    print("Original Images")
+    with torch.no_grad():
+        plt.axis('off')
+        plt.imshow(get_images(transform, 0))
+        plt.show()
+
+    for severity in range(1, 6):
+        print(f"Severity {severity}")
+        with torch.no_grad():
+            plt.axis('off')
+            plt.imshow(get_images(transform, severity))
+            plt.show()
+
+# %%
+# 1. Gaussian Noise
+# ~~~~~~~~~~~~~~~~~
+from torch_uncertainty.transforms.corruptions import GaussianNoise
+
+show_images(GaussianNoise)
+
+# %%
+# 2. Shot Noise
+# ~~~~~~~~~~~~~
+from torch_uncertainty.transforms.corruptions import ShotNoise
+
+show_images(ShotNoise)
+
+# %%
+# 3. Impulse Noise
+# ~~~~~~~~~~~~~~~~
+from torch_uncertainty.transforms.corruptions import ImpulseNoise
+
+show_images(ImpulseNoise)
+
+# %%
+# 4. Speckle Noise
+# ~~~~~~~~~~~~~~~~
+from torch_uncertainty.transforms.corruptions import SpeckleNoise
+
+show_images(SpeckleNoise)
+
+# %%
+# 5. Gaussian Blur
+# ~~~~~~~~~~~~~~~~
+from torch_uncertainty.transforms.corruptions import GaussianBlur
+
+show_images(GaussianBlur)
+
+# %%
+# 6. Glass Blur
+# ~~~~~~~~~~~~~
+from torch_uncertainty.transforms.corruptions import GlassBlur
+
+show_images(GlassBlur)
+
+# %%
+# 7. Defocus Blur
+# ~~~~~~~~~~~~~~~
+
+from torch_uncertainty.transforms.corruptions import DefocusBlur
+
+show_images(DefocusBlur)
+
+#%%
+# 8. JPEG Compression
+# ~~~~~~~~~~~~~~
+from torch_uncertainty.transforms.corruptions import JPEGCompression
+
+show_images(JPEGCompression)
+
+#%%
+# 9. Pixelate
+# ~~~~~~~~~~~
+from torch_uncertainty.transforms.corruptions import Pixelate
+
+show_images(Pixelate)
+
+#%% 
+# 10. Frost
+# ~~~~~~~~
+from torch_uncertainty.transforms.corruptions import Frost
+
+show_images(Frost)
+
+# %%
+# Reference
+# ---------
+#
+# - **Benchmarking Neural Network Robustness to Common Corruptions and Perturbations**, Dan Hendrycks and Thomas Dietterich. `ICLR 2019 <https://arxiv.org/pdf/1903.12261>`_.

auto_tutorials_source/tutorial_der_cubic.py

@@ -1,6 +1,3 @@
-#!/usr/bin/env python
-# coding: utf-8
-
 """
 Deep Evidential Regression on a Toy Example
 ===========================================
@@ -182,7 +179,7 @@ def optim_regression(
 plt.grid()
 
 # %%
-# References
-# ----------
+# Reference
+# ---------
 #
-# - **Deep Evidential Regression:** Alexander Amini, Wilko Schwarting, Ava Soleimany, & Daniela Rus (2022). Deep Evidential Regression. `NeurIPS 2020 <https://arxiv.org/pdf/1910.02600>`_.
+# - **Deep Evidential Regression:** Alexander Amini, Wilko Schwarting, Ava Soleimany, & Daniela Rus. `NeurIPS 2020 <https://arxiv.org/pdf/1910.02600>`_.

auto_tutorials_source/tutorial_evidential_classification.py

@@ -1,6 +1,3 @@
-#!/usr/bin/env python
-# coding: utf-8
-
 """
 Deep Evidential Classification on a Toy Example
 ===============================================
@@ -154,6 +151,7 @@ def rotated_mnist(angle: int) -> None:
     """
     rotated_images = F.rotate(images, angle)
     # print rotated images
+    plt.axis('off')
     imshow(torchvision.utils.make_grid(rotated_images[:4, ...]))
     print("Ground truth: ", " ".join(f"{labels[j]}" for j in range(4)))
 

auto_tutorials_source/tutorial_mc_dropout.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-
 """
 Training a LeNet with Monte-Carlo Dropout
 ==========================================

auto_tutorials_source/tutorial_pe_cifar10.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-
 """
 From a Vanilla Classifier to a Packed-Ensemble
 ==============================================

auto_tutorials_source/tutorial_scaler.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-
 """
 Improve Top-label Calibration with Temperature Scaling
 ======================================================

docs/source/api.rst

@@ -230,3 +230,20 @@ Post-Processing Methods
     TemperatureScaler
     VectorScaler
     MatrixScaler
+
+Datamodules
+-----------
+
+.. currentmodule:: torch_uncertainty.datamodules
+
+.. autosummary::
+    :toctree: generated/
+    :nosignatures:
+    :template: class.rst
+
+    CIFAR10DataModule
+    CIFAR100DataModule
+    MNISTDataModule
+    TinyImageNetDataModule
+    ImageNetDataModule
+    UCIDataModule

docs/source/conf.py

@@ -48,6 +48,8 @@
     },
 }
 
+# Use both the docstrings of the init and the class
+autoclass_content = "both"
 
 autosummary_generate = True
 napoleon_use_ivar = True

docs/source/installation.rst

@@ -52,3 +52,30 @@ Install the package using pip in editable mode:
     pip install -e .
 
 If PyTorch is not installed, the latest version will be installed automatically.
+
+Options
+-------
+
+You can install the package with the following options:
+
+* dev: includes all the dependencies for the development of the package
+including ruff and the pre-commits hooks.
+* docs: includes all the dependencies for the documentation of the package
+based on sphinx
+* image: includes all the dependencies for the image processing module
+including opencv and scikit-image
+* tabular: includes pandas
+* full: includes all the aforementioned dependencies
+
+For example, to install the package with the dependencies for the development
+and the documentation, run:
+
+.. parsed-literal::
+
+    pip install -e .[dev,docs]
+
+To install the package with all the dependencies, run:
+
+.. parsed-literal::
+
+    pip install -e .[full]

docs/source/references.rst

@@ -311,3 +311,12 @@ VGG
 
 * Authors: *Karen Simonyan and Andrew Zisserman*
 * Paper: `ICLR 2015 <https://arxiv.org/pdf/1409.1556.pdf>`__.
+
+Layers
+------
+
+**Filter Response Normalization Layer: Eliminating Batch Dependence in the
+Training of Deep Neural Networks**
+
+* Authors: *Saurabh Singh and Shankar Krishnan*
+* Paper: `CVPR 2020 <https://arxiv.org/pdf/1911.09737.pdf>`__.

experiments/classification/cifar10/resnet.py

@@ -29,6 +29,7 @@
     else:
         calibration_set = None
 
+    results = None
     if args.use_cv:
         list_dm = dm.make_cross_val_splits(args.n_splits, args.train_over)
         list_model = [
@@ -65,8 +66,9 @@
 
         results = cli_main(model, dm, args.exp_dir, args.exp_name, args)
 
-    for dict_result in results:
-        csv_writer(
-            Path(args.exp_dir) / Path(args.exp_name) / "results.csv",
-            dict_result,
-        )
+    if results is not None:
+        for dict_result in results:
+            csv_writer(
+                Path(args.exp_dir) / Path(args.exp_name) / "results.csv",
+                dict_result,
+            )

experiments/classification/cifar10/wideresnet.py

@@ -33,4 +33,4 @@
         **vars(args),
     )
 
-    cli_main(model, dm, root, args.exp_dir, args.exp_name, args)
+    cli_main(model, dm, args.exp_dir, args.exp_name, args)

experiments/classification/cifar100/resnet.py

@@ -33,4 +33,4 @@
         **vars(args),
     )
 
-    cli_main(model, dm, root, args.exp_dir, args.exp_name, args)
+    cli_main(model, dm, args.exp_dir, args.exp_name, args)