Skip to main content

Ready-to-use PyTorch code to boost your way into few-shot image classification

Project description

Easy Few-Shot Learning

Python Versions License: MIT CircleCI PyPi Downloads Last Release Github Issues

Ready-to-use code and tutorial notebooks to boost your way into few-shot image classification. This repository is made for you if:

  • you're new to few-shot learning and want to learn;
  • or you're looking for reliable, clear and easily usable code that you can use for your projects.

Don't get lost in large repositories with hundreds of methods and no explanation on how to use them. Here, we want each line of code to be covered by a tutorial.

What's in there?

Notebooks: learn and practice

You want to learn few-shot learning and don't know where to start? Start with our tutorials.

Notebook Description Colab
First steps into few-shot image classification Basically Few-Shot Learning 101, in less than 15min. Open In Colab
Example of episodic training Use it as a starting point if you want to design a script for episodic training using EasyFSL. Open In Colab
Example of classical training Use it as a starting point if you want to design a script for classical training using EasyFSL. Open In Colab
Test with pre-extracted embeddings Most few-shot methods use a frozen backbone at test-time. With EasyFSL, you can extract all embeddings for your dataset once and for all, and then perform inference directly on embeddings. Open In Colab

Code that you can use and understand

State-Of-The-Art Few-Shot Learning methods:

With 11 built-in methods, EasyFSL is the most comprehensive open-source Few-Shot Learning library!

We also provide a FewShotClassifier class to quickstart your implementation of any few-shot classification algorithm, as well as commonly used architectures.

See the benchmarks section below for more details on the methods.

Tools for data loading:

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: an extension of the standard PyTorch Sampler object, to sample batches in the shape of few-shot classification tasks
  • FewShotDataset: an abstract class to standardize the interface of any dataset you'd like to use
  • EasySet: a ready-to-use FewShotDataset object to handle datasets of images with a class-wise directory split
  • WrapFewShotDataset: a wrapper to transform any dataset into a FewShotDataset object
  • FeaturesDataset: a dataset to handle pre-extracted features
  • SupportSetFolder: a dataset to handle support sets stored in a directory

Scripts to reproduce our benchmarks:

  • scripts/predict_embeddings.py to extract all embeddings from a dataset with a given pre-trained backbone
  • scripts/benchmark_methods.py to evaluate a method on a test dataset using pre-extracted embeddings.

And also: some utilities that I felt I often used in my research, so I'm sharing with you.

Datasets to test your model

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.

CU-Birds

We provide a make download-cub recipe to download and extract the dataset, along with the standard (train / val / test) split along classes. Once you've downloaded the dataset, you can instantiate the Dataset objects in your code with this super complicated process:

from easyfsl.datasets import CUB

train_set = CUB(split="train", training=True)
test_set = CUB(split="test", training=False)

tieredImageNet

To use it, you need the ILSVRC2015 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. Then:

from easyfsl.datasets import TieredImageNet

train_set = TieredImageNet(split="train", training=True)
test_set = TieredImageNet(split="test", training=False)

miniImageNet

Same as tieredImageNet, we provide the specification files, but you need the ILSVRC2015 dataset. Once you have it:

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)

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!

Danish Fungi

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:

# 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

And then instantiate the dataset with the same process as always:

from easyfsl.datasets import DanishFungi

dataset = DanishFungi(root="where/fungi/is")

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 or simply fork the repository.

  2. Download your data.

  3. Design your training and evaluation scripts. You can use our example notebooks for episodic training or classical training.

Contribute

This project is very open to contributions! You can help in various ways:

  • raise issues
  • resolve issues already opened
  • tackle new features from the roadmap
  • fix typos, improve code quality

Benchmarks

We used EasyFSL to benchmark a dozen methods. Inference times are computed over 1000 tasks using pre-extracted features. They are only indicative. Note that the inference time for fine-tuning methods highly depends on the number of fine-tuning steps.

All methods hyperparameters are defined in this JSON file. They were selected on miniImageNet validation set. The procedure can be reproduced with make hyperparameter-search. We decided to use miniImageNet's hyperparameters for all benchmarks in order to highlight the adaptability of the different methods. Note that all methods use L2 normalization of features, except for FEAT as it harms its performance.

There are no results for Mathing and Relation Networks as the trained weights for their additional modules are unavailable.

miniImageNet & tieredImageNet

All methods use the same backbone: a custom ResNet12 using the trained parameters provided by the authors from FEAT (download: miniImageNet, tieredImageNet).

Best inductive and best transductive results for each column are shown in bold.

Method Ind / Trans miniImagenet
1-shot
miniImagenet
5-shot
tieredImagenet
1-shot
tieredImagenet
5-shot
Time
ProtoNet Inductive 63.6 80.4 60.2 77.4 6s
SimpleShot Inductive 63.6 80.5 60.2 77.4 6s
MatchingNet Inductive - - - - -
RelationNet Inductive - - - - -
Finetune Inductive 63.3 80.5 59.8 77.5 1mn33s
FEAT Inductive 64.7 80.1 61.3 76.2 3s
BD-CSPN Transductive 69.8 82.2 66.3 79.1 7s
LaplacianShot Transductive 69.8 82.3 66.2 79.2 9s
PT-MAP Transductive 76.1 84.2 71.7 80.7 39mn40s
TIM Transductive 74.3 84.2 70.7 80.7 3mn05s
Transductive Finetuning Transductive 63.0 80.6 59.1 77.5 30s

To reproduce:

  1. Download the miniImageNet and tieredImageNet weights for ResNet12 and save them under data/models/feat_resnet12_mini_imagenet.pth (resp. tiered).
  2. Extract all embeddings from the test sets of all datasets with make extract-all-features-with-resnet12.
  3. Run the evaluation scripts with make benchmark-mini-imagenet (resp. tiered).

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

easyfsl-1.5.0.tar.gz (53.8 kB view details)

Uploaded Source

Built Distribution

easyfsl-1.5.0-py3-none-any.whl (72.8 kB view details)

Uploaded Python 3

File details

Details for the file easyfsl-1.5.0.tar.gz.

File metadata

  • Download URL: easyfsl-1.5.0.tar.gz
  • Upload date:
  • Size: 53.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.11.4

File hashes

Hashes for easyfsl-1.5.0.tar.gz
Algorithm Hash digest
SHA256 1f414660bef0aecdd06ca81ef94158b1d20bcb243c1fed09f820ed81b061ea30
MD5 04dab95796b2474e70a01ffefcf356bc
BLAKE2b-256 3da078a7bcd7c83d1575627ec0db3d2f6c3a4f66e778f2b2d56e606e3af9296e

See more details on using hashes here.

File details

Details for the file easyfsl-1.5.0-py3-none-any.whl.

File metadata

  • Download URL: easyfsl-1.5.0-py3-none-any.whl
  • Upload date:
  • Size: 72.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.11.4

File hashes

Hashes for easyfsl-1.5.0-py3-none-any.whl
Algorithm Hash digest
SHA256 40fb7747381d6afac5ca3db3193f158003d060507533188d655b98c5aff4e142
MD5 32e71018ba75a2bcd868c3e1eac2ff12
BLAKE2b-256 e147fa188980a02084661080fc07ac75150c45537308e769803fcf18653165fa

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page