Release v0.2.2 => v1.0.0

* Rename AbstractMetaLearner to FewShotClassifier

* Remove episodic training logic from few-shot classifiers

* Make FewShotClassifier support backbones on CUDA at initialization

* Add 4 new methods: Finetune, Transductive Finetuning, TIM and BD-CSPN

* Add SOTA ResNets for Few-Shot Learning

* Make modules parameterizable in Relation Networks and Matching Networks

* Add abstract class FewShotDataset for all few-shot datasets

* Make transforms parameterizable in EasySet

* Add format restrictions in EasySet

* Add TieredImageNet and CUB constructors using EasySet

* Add Danish Fungi dataset

* Add MiniImageNet

* Add notebooks for episodic training and classical training

* Add Python 3.9 support

Author: ebennequin

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.2.2
+current_version = 1.0.0
 commit = True
 tag = False
 

.circleci/config.yml

@@ -79,13 +79,13 @@ workflows:
       - install:
           matrix:
             parameters:
-              python-version: ["3.6.13", "3.7.10", "3.8.8"]
+              python-version: ["3.6.13", "3.7.10", "3.8.8", "3.9.11"]
       - lint:
           requires:
             - install
       - test:
           matrix:
             parameters:
-              python-version: ["3.6.13", "3.7.10", "3.8.8"]
+              python-version: ["3.6.13", "3.7.10", "3.8.8", "3.9.11"]
           requires:
             - install

.pylintrc

@@ -38,6 +38,9 @@ suggestion-mode=yes
 # active Python interpreter and may run arbitrary code.
 unsafe-load-any-extension=no
 
+# As a temporary workaround for https://github.com/PyCQA/pylint/issues/4577
+init-hook = "import astroid; astroid.context.InferenceContext.max_inferred = 500"
+
 
 [MESSAGES CONTROL]
 
@@ -380,7 +383,7 @@ logging-modules=logging
 [DESIGN]
 
 # Maximum number of arguments for function / method
-max-args=8
+max-args=10
 
 # Maximum number of attributes for a class (see R0902).
 max-attributes=10
@@ -472,4 +475,4 @@ known-third-party=enchant
 
 # Exceptions that will emit a warning when being caught. Defaults to
 # "Exception"
-overgeneral-exceptions=Exception
+overgeneral-exceptions=Exception

README.md

@@ -1,9 +1,8 @@
 # Easy Few-Shot Learning
-![Python Versions](https://img.shields.io/badge/python-3.6%20|%203.7%20|%203.8-%23EBBD68.svg)
+![Python Versions](https://img.shields.io/pypi/pyversions/easyfsl?style=flat)
 ![CircleCI](https://img.shields.io/circleci/build/github/sicara/easy-few-shot-learning)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/python/black)
 ![License: MIT](https://img.shields.io/badge/license-MIT-green)
-[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/sicara/easy-few-shot-learning/blob/master/notebooks/my_first_few_shot_classifier.ipynb)
 
 Ready-to-use code and tutorial notebooks to boost your way into few-shot image classification. 
 This repository is made for you if:
@@ -18,130 +17,131 @@ of code to be covered by a tutorial.
 ### Notebooks: learn and practice
 You want to learn few-shot learning and don't know where to start? Start with our tutorial.
 
-- **[First steps into few-shot image classification](notebooks/my_first_few_shot_classifier.ipynb)** 
-  
+- **[First steps into few-shot image classification](notebooks/my_first_few_shot_classifier.ipynb)**: 
+basically Few-Shot Learning 101, in less than 15mn.
+
     [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/sicara/easy-few-shot-learning/blob/master/notebooks/my_first_few_shot_classifier.ipynb)
 
+- **[Example of episodic training](notebooks/episodic_training.ipynb)**: 
+use it as a starting point if you want to design a script for episodic training using EasyFSL.
+
+- **[Example of classical training](notebooks/episodic_training.ipynb)**: 
+use it as a starting point if you want to design a script for classical training using EasyFSL.
+
 ### Code that you can use and understand
 
-**Models:**
+**State-Of-The-Art Few-Shot Learning methods:**
 
-- [AbstractMetaLearner](easyfsl/methods/abstract_meta_learner.py): an abstract class with methods that can be used for 
-  any meta-trainable algorithm
+- [FewShotClassifier](easyfsl/methods/few_shot_classifier.py): an abstract class with methods that can be used for 
+  any few-shot classification algorithm
 - [Prototypical Networks](easyfsl/methods/prototypical_networks.py)
 - [Matching Networks](easyfsl/methods/matching_networks.py)
 - [Relation Networks](easyfsl/methods/relation_networks.py)
+- [Fine-Tune](easyfsl/methods/finetune.py)
+- [BD-CSPN](easyfsl/methods/bd_cspn.py)
+- [Transductive Fine-Tuning](easyfsl/methods/transductive_finetuning.py)
+- [Transductive Information Maximization](easyfsl/methods/tim.py)
+
+To reproduce their results, you can use the [standard network architectures](easyfsl/modules/predesigned_modules.py) 
+used in Few-Shot Learning research. They're also a feature of EasyFSL!
 
 **Tools for data loading:**
 
-- [EasySet](easyfsl/data_tools/easy_set.py): a ready-to-use Dataset object to handle datasets of images with a class-wise directory split
-- [TaskSampler](easyfsl/data_tools/task_sampler.py): samples batches in the shape of few-shot classification tasks
+Data loading in FSL is a bit different from standard classification because we sample batches of
+instances in the shape of few-shot classification tasks. No sweat! In EasyFSL you have:
+
+- [TaskSampler](easyfsl/samplers/task_sampler.py): an extension of the standard PyTorch Sampler object, to sample batches in the shape of few-shot classification tasks
+- [FewShotDataset](easyfsl/datasets/few_shot_dataset.py): an abstract class to standardize the interface of any dataset you'd like to use
+- [EasySet](easyfsl/datasets/easy_set.py): a ready-to-use FewShotDataset object to handle datasets of images with a class-wise directory split
+
+**And also:** [some utilities](easyfsl/utils.py) that I felt I often used in my research, so I'm sharing with you.
 
 ### Datasets to test your model
 
-- [CU-Birds](http://www.vision.caltech.edu/visipedia/CUB-200.html): we provide [a script](scripts/download_CUB.sh) to download
-and extract the dataset, along with [(train / val / test) split](data/CUB) along classes. The dataset is
-  ready-to-use with [EasySet](easyfsl/data_tools/easy_set.py).
-- [tieredImageNet](https://paperswithcode.com/dataset/tieredimagenet): we provide the 
-  [train, val and test specification files](data/tiered_imagenet) to be used by [EasySet](easyfsl/data_tools/easy_set.py).
-  To use it, you need the [ILSVRC2015](https://image-net.org/challenges/LSVRC/index.php) dataset. Once you have 
-  downloaded and extracted the dataset, ensure that its localisation on disk is consistent with the class paths
-  specified in the specification files.
+There are enough datasets used in Few-Shot Learning for anyone to get lost in them. They're all here, 
+explicited, downloadable and easy-to-use, in EasyFSL. 
 
-## QuickStart
-1. Install the package with pip: 
-   
-```pip install easyfsl```
+**[CU-Birds](http://www.vision.caltech.edu/visipedia/CUB-200.html)**
 
-Note: alternatively, you can clone the repository so that you can modify the code as you wish.
-   
-2. Download [CU-Birds](http://www.vision.caltech.edu/visipedia/CUB-200.html) and the few-shot train/val/test split:
+We provide [a script](scripts/download_CUB.sh) to download and extract the dataset, 
+along with the standard [(train / val / test) split](data/CUB) along classes. 
+Once you've downloaded the dataset, you can instantiate the Dataset objects in your code
+with this super complicated process:
 
+```python
+from easyfsl.datasets import CUB
+
+train_set = CUB(split="train", training=True)
+test_set = CUB(split="test", training=False)
 ```
-mkdir -p data/CUB && cd data/CUB
-wget --load-cookies /tmp/cookies.txt "https://docs.google.com/uc?export=download&confirm=$(wget --quiet --save-cookies /tmp/cookies.txt --keep-session-cookies --no-check-certificate 'https://docs.google.com/uc?export=download&id=1GDr1OkoXdhaXWGA8S3MAq3a522Tak-nx' -O- | sed -rn 's/.*confirm=([0-9A-Za-z_]+).*/\1\n/p')&id=1GDr1OkoXdhaXWGA8S3MAq3a522Tak-nx" -O images.tgz
-rm -rf /tmp/cookies.txt
-tar  --exclude='._*' -zxvf images.tgz
-wget https://raw.githubusercontent.com/sicara/easy-few-shot-learning/master/data/CUB/train.json
-wget https://raw.githubusercontent.com/sicara/easy-few-shot-learning/master/data/CUB/val.json
-wget https://raw.githubusercontent.com/sicara/easy-few-shot-learning/master/data/CUB/test.json
-cd ...
-```
-   
-3. Check that you have a 680,9MB `images` folder in `./data/CUB` along with three JSON files.
 
-4. From the training subset of CUB, create a dataloader that yields few-shot classification tasks:
+**[tieredImageNet](https://paperswithcode.com/dataset/tieredimagenet)**
+
+To use it, you need the [ILSVRC2015](https://image-net.org/challenges/LSVRC/index.php) dataset. Once you have 
+downloaded and extracted the dataset, ensure that its localisation on disk is consistent with the class paths
+specified in the [specification files](data/tiered_imagenet). Then:
+
 ```python
-from easyfsl.data_tools import EasySet, TaskSampler
-from torch.utils.data import DataLoader
-
-train_set = EasySet(specs_file="./data/CUB/train.json", training=True)
-train_sampler = TaskSampler(
-    train_set, n_way=5, n_shot=5, n_query=10, n_tasks=40000
-)
-train_loader = DataLoader(
-    train_set,
-    batch_sampler=train_sampler,
-    num_workers=12,
-    pin_memory=True,
-    collate_fn=train_sampler.episodic_collate_fn,
-)
+from easyfsl.datasets import TieredImageNet
+
+train_set = TieredImageNet(split="train", training=True)
+test_set = TieredImageNet(split="test", training=False)
 ```
 
-5. Create and train a model
+**[miniImageNet](https://paperswithcode.com/dataset/miniimagenet)**
+
+Same as tieredImageNet, we provide the [specification files](data/mini_imagenet), 
+but you need the [ILSVRC2015](https://image-net.org/challenges/LSVRC/index.php) dataset.
+Once you have it:
 
 ```python
-from easyfsl.methods import PrototypicalNetworks
-from torch import nn
-from torch.optim import Adam
-from torchvision.models import resnet18
+from easyfsl.datasets import MiniImageNet
+
+train_set = MiniImageNet(root="where/imagenet/is", split="train", training=True)
+test_set = MiniImageNet(root="where/imagenet/is", split="test", training=False)
+```
 
-convolutional_network = resnet18(pretrained=False)
-convolutional_network.fc = nn.Flatten()
-model = PrototypicalNetworks(convolutional_network).cuda()
+Since miniImageNet is relatively small, you can also load it on RAM directly at instantiation simply by
+adding `load_on_ram=True` to the constructor. 
+It takes a few minutes but it can make your training significantly faster!
 
-optimizer = Adam(params=model.parameters())
+**[Danish Fungi](https://paperswithcode.com/paper/danish-fungi-2020-not-just-another-image)**
 
-model.fit(train_loader, optimizer)
-```
-   **Note:** you can also define a validation data loader and use as an additional argument to `fit`
-in order to use validation during your training.
+I've recently started using it as a Few-Shot Learning benchmarks, and I can tell you it's a great
+playing field. To use it, first download the data:
 
-   **Troubleshooting:** a ResNet18 with a batch size of (5 * (5+10)) = 75 would use about 4.2GB on your GPU.
-If you don't have it, switch to CPU, choose a smaller model or reduce the batch size (in `TaskSampler` above).
+```shell
+# Download the original dataset (/!\ 110GB)
+wget http://ptak.felk.cvut.cz/plants/DanishFungiDataset/DF20-train_val.tar.gz
+# Or alternatively the images reduced to 300px (6.5Gb)
+wget http://ptak.felk.cvut.cz/plants/DanishFungiDataset/DF20-300px.tar.gz
+# And finally download the metadata (83Mb) to data/fungi/
+wget https://public-sicara.s3.eu-central-1.amazonaws.com/easy-fsl/DF20_metadata.csv  -O data/fungi/DF20_metadata.csv
+```
 
-6. Evaluate your model on the test set
+And then instantiate the dataset with the same process as always:
 
 ```python
-test_set = EasySet(specs_file="./data/CUB/test.json", training=False)
-test_sampler = TaskSampler(
-    test_set, n_way=5, n_shot=5, n_query=10, n_tasks=100
-)
-test_loader = DataLoader(
-    test_set,
-    batch_sampler=test_sampler,
-    num_workers=12,
-    pin_memory=True,
-    collate_fn=test_sampler.episodic_collate_fn,
-)
-
-accuracy = model.evaluate(test_loader)
-print(f"Average accuracy : {(100 * accuracy):.2f}")
+from easyfsl.datasets import DanishFungi
+
+dataset = DanishFungi(root="where/fungi/is")
 ```
 
-## Roadmap
-
-- [ ] Integrate more methods: 
-  - [X] Matching Networks
-  - [X] Relation Networks
-  - [ ] MAML
-  - [ ] Transductive Propagation Network
-  - [ ] TADAM
-- [ ] Integrate non-episodic training
-- [ ] Integrate more benchmarks:
-  - [X] tieredImageNet
-  - [ ] miniImageNet
-  - [ ] Meta-Dataset
+Note that I didn't specify a train and test set because the CSV I gave you describes the whole dataset.
+I recommend to use it to test models with weights trained on an other dataset (like ImageNet).
+But if you want to propose a train/val/test split along classes, you're welcome to contribute!
+
+## QuickStart
+
+
+1. Install the package: ```pip install easyfsl``` \
+Note: alternatively, you can clone the repository so that you can modify the code as you wish.
+   
+2. [Download your data](#datasets-to-test-your-model).
+
+3. Design your training and evaluation scripts. You can use our example notebooks for 
+[episodic training](notebooks/episodic_training.ipynb) 
+or [classical training](notebooks/classical_training.ipynb)
 
 ## Contribute
 This project is very open to contributions! You can help in various ways:

data/fungi/.gitignore

@@ -0,0 +1,3 @@
+DF20_metadata.csv
+
+images/