Package: sesemi
Image Classification with Self-Supervised RegularizationWhy SESEMI?SESEMI is an open source image classification library built on PyTorch and PyTorch Lightning. SESEMI enables various modern supervised classifiers to be robust semi-supervised learners based on the principles of self-supervised regularization.Highlights and FeaturesIntegration with the popularPyTorch Image Models(timm) library for access to contemporary, high-performance supervised architectures with optional pretrained ImageNet weights. See the list ofsupported backbonesDemonstrated utility on large realistic image datasets and is currently competitive on theFastAI Imagenette benchmarksEasy to use out-of-the-box requiring little hyper-parameter tuning across many tasks related to supervised learning, semi-supervised learning, and learning with noisy labels. In most use cases, one only needs to tune the learning rate, batch size, and backbone architectureSimply add unlabeled data for improved image classification without any tricksOur goal is to expand the utility of SESEMI for the ML/CV practitioner by incorporating the latest advances in self-supervised, semi-supervised, and few-shot learning to boost the accuracy performance of conventional supervised classifiers in the limited labeled data setting. If you find this work useful please star this repo to let us know. Contributions are also welcome!InstallationOur preferred installation method is Docker, however, you can use any virtual environment tool to install the necessary Python dependencies. Below are instructions for both these methods.PipTo use pip, configure a virtual environment of choice with at least Python 3.6 (e.g.miniconda). Then install the requirements as follows:$pipinstallgit+https://github.com/FlyreelAI/sesemi.gitWhile the above installs the latest version from the main branch, a version from PyPI can be installed instead as follows:$pipinstallsesemiDockerIf you would like to use docker, then ensure you have it installed by following the instructionshere. The Dockerfile at the root can be used to build an image with the
code in this repository. To build the image, run the followingbashcommand :$USER_ID=$(id-u)SESEMI_IMAGE=sesemi:latest
$DOCKER_BUILDKIT=1dockerbuild\--build-argUSER_ID=${USER_ID}\-t${SESEMI_IMAGE}https://github.com/FlyreelAI/sesemi.gitNote that your OS user ID is obtained through the bash commandid -u. This command will create an image namedsesemi:latest.Getting StartedYou can find more detailed documentation which is hostedhere, however, this section will guide you through the process of using SESEMI to train a model onFastAI's imagewoof2 dataset. If you don't have access to a GPU machine,
training will work but will take a very long time.Create a directory for the experiment and enter it.$mkdirsesemi-experiments
$cdsesemi-experiments
$mkdirdataruns.cacheDownload and extract the imagewoof2 dataset to the data directory.$curlhttps://s3.amazonaws.com/fast-ai-imageclas/imagewoof2.tgz|tar-xzv-C./dataRun training using SESEMI for 80 epochs. You should get 90-91% accuracy on the imagewoof2 dataset, which is competitive on theFastAI leaderboard, using a standard training protocol + unlabeled data, without fancy tricks.If you're not using docker this can be done as follows:$open_sesemi-cnimagewoof_rotationIf you use docker and havenvidia-dockerinstalled you can instead use:$USER_ID=$(id-u)SESEMI_IMAGE=sesemi:latestGPUS=all
$dockerrun\--gpus${GPUS}\-u${USER_ID}\--rm--ipc=host\--mounttype=bind,src=$(pwd),dst=/home/appuser/sesemi-experiments/\-w/home/appuser/sesemi-experiments\${SESEMI_IMAGE}\open_sesemi-cnimagewoof_rotationThe training logs with all relevant training statistics (accuracy, losses, learning rate, etc.) are written to the./runsdirectory. You can useTensorBoardto view and monitor them in your browser during training.$tensorboard--logdir./runsRun evaluation on the trained checkpoint.Without docker:$CHECKPOINT_PATH=$(echo./runs/imagewoof_rotation/*/lightning_logs/version_0/checkpoints/last.ckpt)$open_sesemi-cnimagewoof_rotation\run.mode=VALIDATE\run.pretrained_checkpoint_path=$CHECKPOINT_PATHWith docker:$USER_ID=$(id-u)SESEMI_IMAGE=sesemi:latestGPUS=all
$CHECKPOINT_PATH=$(echo./runs/imagewoof_rotation/*/lightning_logs/version_0/checkpoints/last.ckpt)$dockerrun\--gpus${GPUS}\-u${USER_ID}\--rm--ipc=host\--mounttype=bind,src=$(pwd),dst=/home/appuser/sesemi-experiments/\-w/home/appuser/sesemi-experiments\${SESEMI_IMAGE}\open_sesemi-cnimagewoof_rotation\run.mode=VALIDATE\run.pretrained_checkpoint_path=$CHECKPOINT_PATHCitationIf you find this work useful, consider citing the related paper:@inproceedings{TranSESEMI,
  title="{Exploring Self-Supervised Regularization for Supervised and Semi-Supervised Learning}",
  author={Phi Vu Tran},
  booktitle={NeurIPS Workshop on Learning with Rich Experience: Integration of Learning Paradigms},
  year={2019}
}