🎋 Semi-Supervised Regression

Official repository for the paper
"RankUp: Boosting Semi-Supervised Regression with an Auxiliary Ranking Classifier",
by Pin-Yen Huang, Szu-Wei Fu, and Yu Tsao. Accepted at NeurIPS 2024.

Explore the following resources:
📄 arXiv Paper · 🗃️ Experiment Logs · ✨ Feature Visualizations

📋 Table of Contents

1. Introduction
2. Getting Started
3. Usage
4. Benchmark Results
5. License
6. Contact
7. Citing This Work
8. Acknowledgments

1. Introduction

Paper Link: https://arxiv.org/abs/2410.22124

This repository contains the official code and documentation for the paper "RankUp: Boosting Semi-Supervised Regression with an Auxiliary Ranking Classifier". Here, you’ll find implementations of the proposed methods (RankUp and RDA), alongside related works, experiment logs, feature visualizations, datasets, and hyperparameter settings used in our experiments. The code is adapted from the popular semi-supervised classification framework, USB. We are deeply grateful to the USB team for their excellent framework, which played a crucial role in the development of our research and made our work possible!

(back to top)

2. News and Updates

• [Jan 01, 2025] Simplified the code by removing classification algorithms.
• [Oct 23, 2024] Released the code for the RankUp paper.
• [Sep 25, 2024] The RankUp paper has been accepted into the NeurIPS 2024 Main Track!

(back to top)

3. Getting Started

This section guides you through setting up the repository locally. Follow these steps to get your environment ready.

💽 Clone Repository

Clone this repository with the following command:

git clone https://github.com/pm25/semi-supervised-regression.git

🪛 Prerequisites

This repository is built on PyTorch, along with torchvision, torchaudio, and transformers.

To install the required packages, first create a Conda environment:

conda create --name ssr python=3.8

Activate the environment:

conda activate ssr

Then, use pip to install the required packages:

python -m pip install -r requirements.txt

Once the installation is complete, you can start using this repository by running:

python train.py --gpu 0 --c config/classic_cv/rankup/rankup_utkface_lb250_s0.yaml

⚙️ Configuration Files

All configuration files are stored in the config folder.

The configuration file paths follow this naming format:

./config/{data_type}/{method}/{method}_{dataset}_lb{num_labeled}_s{seed}.yaml

For example, the configuration file for the RankUp method on the UTKFace dataset with 250 labeled samples and seed 0 is located at:

./config/classic_cv/rankup/rankup_utkface_lb250_s0.yaml

📊 Prepare Datasets

No manual dataset preparation is required. The datasets will be automatically downloaded and processed when you run the code. For more details on the dataset splits and processing, visit the pm25/Regression-Datasets.

(back to top)

4. Usage

This repository is designed to be user-friendly and extendable. Below are some examples to help you get started with training, evaluation, and feature visualization.

🏋️ Training

To train RankUp on the UTKFace dataset with 250 labels on GPU 0, use the following command. You can modify the configuration file to try other algorithms, datasets, or label settings:

python train.py --gpu 0 --c config/classic_cv/rankup/rankup_utkface_lb250_s0.yaml

🎯 Evaluation

After training, you can either view the evaluation results in the training logs or run the evaluation script:

python eval.py --gpu 0 --c config/classic_cv/rankup/rankup_utkface_lb250_s0.yaml

✨ Features Visualization

Once training is complete, you can extract hidden features of the evaluation data using:

python eval.py --gpu 0 --save_features \
    --c config/classic_cv/rankup/rankup_utkface_lb250_s0.yaml

To visualize these features, you can project them into 2D or 3D space using t-SNE or UMAP:

python visualization/plot.py --methods tsne umap --output_dim 2 \
    --load_path visualization/features/rankup_utkface_lb250_s0.npy

(back to top)

5. Benchmark Results

Please refer to Results for benchmark results and experiment logs on different tasks and labeled settings.

(back to top)

6. License

This project is licensed under the MIT License. See LICENSE for more details.

(back to top)

7. Contact

• Pin-Yen Huang ([email protected]), Arizona State University
• Szu-Wei Fu ([email protected]), NVIDIA
• Yu Tsao ([email protected]), Academia Sinica

(back to top)

8. Citing this Work

If you find this repository useful, please consider citing our paper or giving this repository a star. Your support is greatly appreciated!

@inproceedings{
  huang2024rankup,
  title={RankUp: Boosting Semi-Supervised Regression with an Auxiliary Ranking Classifier},
  author={Pin-Yen Huang and Szu-Wei Fu and Yu Tsao},
  booktitle={The Thirty-eighth Annual Conference on Neural Information Processing Systems (NeurIPS)},
  year={2024},
  url={https://openreview.net/forum?id=d2lPM1Aczs}
}

(back to top)

9. Acknowledgments

• USB
• TorchSSL
• README Template

(back to top)