Package: easyfsl
Easy Few-Shot LearningReady-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 practiceYou want to learn few-shot learning and don't know where to start? Start with our tutorials.NotebookDescriptionColabFirst steps into few-shot image classificationBasically Few-Shot Learning 101, in less than 15min.Example of episodic trainingUse it as a starting point if you want to design a script for episodic training using EasyFSL.Example of classical trainingUse it as a starting point if you want to design a script for classical training using EasyFSL.Test with pre-extracted embeddingsMost 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.Code that you can use and understandState-Of-The-Art Few-Shot Learning methods:With 11 built-in methods, EasyFSL is the most comprehensive open-source Few-Shot Learning library!Prototypical NetworksSimpleShotMatching NetworksRelation NetworksFEATFine-TuneBD-CSPNLaplacianShotTransductive Information MaximizationPT-MAPTransductive Fine-TuningWe also provide aFewShotClassifierclass to quickstart your implementation
of any few-shot classification algorithm, as well ascommonly 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 tasksFewShotDataset: an abstract class to standardize the interface of any dataset you'd like to useEasySet: a ready-to-use FewShotDataset object to handle datasets of images with a class-wise directory splitWrapFewShotDataset: a wrapper to transform any dataset into a FewShotDataset objectFeaturesDataset: a dataset to handle pre-extracted featuresSupportSetFolder: a dataset to handle support sets stored in a directoryScripts to reproduce our benchmarks:scripts/predict_embeddings.pyto extract all embeddings from a dataset with a given pre-trained backbonescripts/benchmark_methods.pyto evaluate a method on a test dataset using pre-extracted embeddings.And also:some utilitiesthat I felt I often used in my research, so I'm sharing with you.Datasets to test your modelThere 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-BirdsWe provide amake download-cubrecipe to download and extract the dataset,
along with the standard(train / val / test) splitalong classes.
Once you've downloaded the dataset, you can instantiate the Dataset objects in your code
with this super complicated process:fromeasyfsl.datasetsimportCUBtrain_set=CUB(split="train",training=True)test_set=CUB(split="test",training=False)tieredImageNetTo use it, you need theILSVRC2015dataset. Once you have
downloaded and extracted the dataset, ensure that its localisation on disk is consistent with the class paths
specified in thespecification files. Then:fromeasyfsl.datasetsimportTieredImageNettrain_set=TieredImageNet(split="train",training=True)test_set=TieredImageNet(split="test",training=False)miniImageNetSame as tieredImageNet, we provide thespecification files,
but you need theILSVRC2015dataset.
Once you have it:fromeasyfsl.datasetsimportMiniImageNettrain_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
addingload_on_ram=Trueto the constructor.
It takes a few minutes but it can make your training significantly faster!Danish FungiI'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)wgethttp://ptak.felk.cvut.cz/plants/DanishFungiDataset/DF20-train_val.tar.gz# Or alternatively the images reduced to 300px (6.5Gb)wgethttp://ptak.felk.cvut.cz/plants/DanishFungiDataset/DF20-300px.tar.gz# And finally download the metadata (83Mb) to data/fungi/wgethttps://public-sicara.s3.eu-central-1.amazonaws.com/easy-fsl/DF20_metadata.csv-Odata/fungi/DF20_metadata.csvAnd then instantiate the dataset with the same process as always:fromeasyfsl.datasetsimportDanishFungidataset=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!QuickStartInstall the package:pip install easyfslor simply fork the repository.Download your data.Design your training and evaluation scripts. You can use our example notebooks forepisodic trainingorclassical training.ContributeThis project is very open to contributions! You can help in various ways:raise issuesresolve issues already openedtackle new features from the roadmapfix typos, improve code qualityBenchmarksWe 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 inthis JSON file.
They were selected on miniImageNet validation set.
The procedure can be reproduced withmake 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 & tieredImageNetAll methods use the same backbone:a custom ResNet12using the trained parameters
provided by the authors fromFEAT(download:miniImageNet,tieredImageNet).Best inductive and best transductive results for each column are shown in bold.MethodInd / TransminiImagenet1-shotminiImagenet5-shottieredImagenet1-shottieredImagenet5-shotTimeProtoNetInductive63.680.460.277.46sSimpleShotInductive63.680.560.277.46sMatchingNetInductive-----RelationNetInductive-----FinetuneInductive63.380.559.877.51mn33sFEATInductive64.780.161.376.23sBD-CSPNTransductive69.882.266.379.17sLaplacianShotTransductive69.882.366.279.29sPT-MAPTransductive76.184.271.780.739mn40sTIMTransductive74.384.270.780.73mn05sTransductive FinetuningTransductive63.080.659.177.530sTo reproduce:Download theminiImageNetandtieredImageNetweights for ResNet12
and save them underdata/models/feat_resnet12_mini_imagenet.pth(resp.tiered).Extract all embeddings from the test sets of all datasets withmake extract-all-features-with-resnet12.Run the evaluation scripts withmake benchmark-mini-imagenet(resp.tiered).