Awesome

Hubs and Hyperspheres

This repository contains the code for the paper "Hubs and Hyperspheres: Reducing Hubness and Improving Transductive Few-shot Learning with Hyperspherical Embeddings", CVPR 2023.

Abstract - Distance-based classification is frequently used in transductive few-shot learning (FSL). However, due to the high-dimensionality of image representations, FSL classifiers are prone to suffer from the hubness problem, where a few points (hubs) occur frequently in multiple nearest neighbour lists of other points. Hubness negatively impacts distance-based classification when hubs from one class appear often among the nearest neighbors of points from another class, degrading the classifier's performance. To address the hubness problem in FSL, we first prove that hubness can be eliminated by distributing representations uniformly on the hypersphere. We then propose two new approaches to embed representations on the hypersphere, which we prove optimize a tradeoff between uniformity and local similarity preservation -- reducing hubness while retaining class structure. Our experiments show that the proposed methods reduce hubness, and significantly improves transductive FSL accuracy for a wide range of classifiers.

Results aggregated over classifiers

1-shot

5-shot

Datasets

The datasets can be downloaded by following the instructions in the repo Realistic evaluation of transductive few-shot learning .

After downloading the datasets, use the files in data/split to separate the images into directories data/[mini|tiered|cub]/[train|val|test].

Feature extractors

Download the checkpoints from:

• ResNet-18: Realistic evaluation of transductive few-shot learning.
• WideRes28-10: S2M2 Charting the Right Manifold: Manifold Mixup for Few-shot Learning

And place them in the models directory.

Feature caching

When executing the evaluation script, setting --cache_dir /path/to/cached/features will save the computed features to the specified directory. By setting --use_cached True in subsequent runs, this will make repeated evaluations on the same dataset/feature extractors much faster.

Installing dependencies

Run

conda env create -f environment.yml

to create a conda environment with the base requirements.

Then, inside the newly created environment, install the other dependencies with pip:

pip install -r requirements.txt

Running with Docker

The docker directory contains a build script and a Dockerfile to build a docker image with all required dependencies.

Running evaluation

Evaluation is performed by running

python evaluate.py --checkpoint "<path/to/feature/extractor/checkpoint.ckpt>" --n_shots "<shots>" --dataset "[mini|tiered|cub]" --classifier "<classifier>" --embedding "<embedding>" "<optional arguments>" 

where "<classifier>" and "<embedding>" are one of the implemented classifiers and embedding methods, respectively (see below).

Alternatively, the arguments can be provided in a yaml file:

python evaluate.py -c path/to/config/file.yml "<optional arguments>"

See src/config/templates for examples of config files.

Implemented embedding methods

Implemented classifiers