Awesome
<p align="center"> <img src="https://github.com/yzhuoning/LibAUC/blob/main/imgs/libauc.png" width="70%" align="center"/> </p> <p align="center"> Logo by <a href="https://yzhuoning.com">Zhuoning Yuan</a> </p>LibAUC: A Deep Learning Library for X-Risk Optimization
Website | Updates | Installation | Tutorial | Research | Github
We continuously update our library by making improvements and adding new features. If you use or like our library, please star:star: this repo. Thank you!
:calendar: Updates
- 2023/5: We are currently working on another major update, which will include new features, documentation & codebase improvements. We expect the new version to be released later this month!
- 2022/7: LibAUC 1.2.0 is released! In this version, we've included more losses and optimizers as well as made some performance improvements. Please check release note for more details! Thanks!
:mag: What is X-Risk?
X-risk refers to a family of compositional measures/losses, in which each data point is compared with a set of data points explicitly or implicitly for defining a risk function. It covers a family of widely used measures/losses including but not limited to the following four interconnected categories:
- Areas under the curves, including areas under ROC curves (AUROC), areas under Precision-Recall curves (AUPRC), one-way and two-wary partial areas under ROC curves.
- Ranking measures/objectives, including p-norm push for bipartite ranking, listwise losses for learning to rank (e.g., listNet), mean average precision (mAP), normalized discounted cumulative gain (NDCG), etc.
- Performance at the top, including top push, top-K variants of mAP and NDCG, Recall at top K positions (Rec@K), Precision at a certain Recall level (Prec@Rec), etc.
- Contrastive objectives, including supervised contrastive objectives (e.g., NCA), and global self-supervised contrastive objectives improving upon SimCLR and CLIP.
:star: Key Features
- Easy Installation - Easy to install and insert LibAUC code into existing training pipeline with Deep Learning frameworks like PyTorch.
- Broad Applications - Users can learn different neural network structures (e.g., MLP, CNN, GNN, transformer, etc) that support their data types.
- Efficient Algorithms - Stochastic algorithms with provable theoretical convergence that support learning with millions of data points without larger batch size.
- Hands-on Tutorials - Hands-on tutorials are provided for optimizing a variety of measures and objectives belonging to the family of X-risks.
:gear: Installation
$ pip install libauc==1.2.0
The latest version 1.2.0
is available now! You can check release note for more details. Source code is available for download here.
:clipboard: Usage
Example training pipline for optimizing X-risk (e.g., AUROC)
>>> #import our loss and optimizer
>>> from libauc.losses import AUCMLoss
>>> from libauc.optimizers import PESG
...
>>> #define loss & optimizer
>>> Loss = AUCMLoss()
>>> optimizer = PESG()
...
>>> #training
>>> model.train()
>>> for data, targets in trainloader:
>>> data, targets = data.cuda(), targets.cuda()
logits = model(data)
preds = torch.sigmoid(logits)
loss = Loss(preds, targets)
optimizer.zero_grad()
loss.backward()
optimizer.step()
...
>>> #update internal parameters
>>> optimizer.update_regularizer()
:notebook_with_decorative_cover: Tutorials
X-Risk
- AUROC: Optimizing AUROC loss on imbalanced dataset
- AUPRC: Optimizing AUPRC loss on imbalanced dataset
- Partial AUROC: Optimizing Partial AUC loss on imbalanced dataset
- Compositional AUROC: Optimizing Compositional AUROC loss on imbalanced dataset
- NDCG: Optimizing NDCG loss on MovieLens 20M
- SogCLR: Optimizing Contrastive Loss using small batch size on ImageNet-1K
Applications
- A Tutorial of Imbalanced Data Sampler (Updates Coming Soon)
- Constructing benchmark imbalanced datasets for CIFAR10, CIFAR100, CATvsDOG, STL10
- Using LibAUC with PyTorch learning rate scheduler
- Optimizing AUROC loss on Chest X-Ray dataset (CheXpert)
- Optimizing AUROC loss on Skin Cancer dataset (Melanoma)
- Optimizing AUROC loss on Molecular Graph dataset (OGB-Molhiv)
- Optimizing multi-label AUROC loss on Chest X-Ray dataset (CheXpert)
- Optimizing AUROC loss on Tabular dataset (Credit Fraud)
- Optimizing AUROC loss for Federated Learning
:page_with_curl: Citation
If you find LibAUC useful in your work, please cite the papers in BibTex and acknowledge our library:
@inproceedings{yuan2023libauc,
title={LibAUC: A Deep Learning Library for X-risk Optimization},
author={Zhuoning Yuan and Dixian Zhu and Zi-Hao Qiu and Gang Li and Xuanhui Wang and Tianbao Yang},
booktitle={29th SIGKDD Conference on Knowledge Discovery and Data Mining},
year={2023}
}
@article{yang2022algorithmic,
title={Algorithmic Foundation of Deep X-Risk Optimization},
author={Yang, Tianbao},
journal={arXiv preprint arXiv:2206.00439},
year={2022}
}
:email: Contact
For any technical questions, please open a new issue in the Github. If you have any other questions, please contact us @ Zhuoning Yuan [yzhuoning@gmail.com] and Tianbao Yang [tianbao-yang@tamu.edu].