<div align="center">
<img src="cbloss.svg" alt="PyPI" >
</div>
<div align="center">
<img src="https://img.shields.io/pypi/v/cbloss" alt="PyPI" >
<img src="https://github.com/wildoctopus/cbloss/actions/workflows/ci.yml/badge.svg" alt="Build Status">
</div>
# cbloss (Class Balanced Loss)
`cbloss` is a Python package that provides Pytorch implementation of - .
This package also includes Pytorch Implementation of  as `Focal Loss` is currently not avaialable in `torch.nn` module.
## Installation
You can install `cbloss` via pip:
```
pip install cbloss
```
## Usage
### Focal Loss
Focal Loss is a popular loss function for imbalanced classification problems. It's a modification of the standard Cross Entropy nad Binary Classification Loss, that is designed to address class imbalance issues. In essence, it gives more weight to hard to classify examples.
```
Formula:
For a binary classification problem:
FL(pt) = -alpha * (1 - pt)**gamma * log(pt) if y = 1
- (1 - alpha) * pt**gamma * log(1 - pt) otherwise
For a multi-class classification problem:
FL(pt) = -alpha * (1 - pt)**gamma * log(pt) if y = c
- (1 - alpha) * pt**gamma * log(1 - pt) otherwise
where:
pt = sigmoid(x) for binary classification, and softmax(x) for multi-class classification
alpha = balancing parameter, default to 1, the balance between positive and negative samples
gamma = focusing parameter, default to 2, the degree of focusing, 0 means no focusing.
Args:
num_classes (int) : number of classes
alpha (float): balancing parameter, default to 1.
gamma (float): focusing parameter, default to 2.
reduction (str): reduction method for the loss, either 'none', 'mean' or 'sum', default to 'mean'.
```
```python
from cbloss.loss import FocalLoss
loss_fn = FocalLoss(num_classes=3, gamma=2.0, alpha=0.25)
```
### ClassBalancedLoss
This loss function helps address the problem of class imbalance in the training data by assigning higher weights to underrepresented classes during training. The weights are determined based on the `number of samples per class and a beta value`, which controls the degree of balancing between the classes.
The loss function supports different types of base losses, including `CrossEntropyLoss`, `BCEWithLogitsLoss`, and `FocalLoss`.
```
The effective number of samples per class is calculated as:
effective_num = 1 - beta^(samples_per_cls)
The weights for each class are then calculated as:
weights = (1 - beta) / effective_num
weights = weights / sum(weights) * num_classes
The loss is calculated as:
loss = (weights * base_loss).mean()
where `base_loss` is the value returned by the base loss function.
Args:
samples_per_cls (list or numpy array): Number of samples per class in the training data.
beta (float): Degree of balancing between the classes.
num_classes (int): Number of classes in the classification problem.
loss_func (nn.Module): Base loss function to use for calculating the loss. Should be one of
the following: nn.CrossEntropyLoss, nn.BCEWithLogitsLoss, or FocalLoss..
```
```python
from cbloss.loss import ClassBalancedLoss
samples_per_cls = [300, 200, 100] # an example case
loss_func = nnCrossEntropyLoss(reduction = 'none')
loss_fn = ClassBalancedLoss(samples_per_cls, beta=0.99, num_classes=3, loss_func=loss_func)
```
The `loss_func` parameter should be set to one of these base losses (FocalLoss, nn.CrossEntropyLoss, nn.BCEWithLogitsLoss).
`*** Please Note "reduction = 'none'" should be set for all base Loss Function, while using ClassBalancedLoss.`
## v0.1.0
If you have v0.1.0 installed, please use cb_loss.loss to import FocalLoss and ClassBalancedLoss.
```python
from cb_loss.loss import ClassBalancedLoss, FocalLoss
samples_per_cls = [300, 200, 100] # an example case
loss_func = nnCrossEntropyLoss(reduction = 'none')
loss_fn = ClassBalancedLoss(samples_per_cls, beta=0.99, num_classes=3, loss_func=loss_func)
```
# Citations
```
@inproceedings{lin2017focal,
title={Focal Loss for Dense Object Detection},
author={Lin, Tsung-Yi and Goyal, Priya and Girshick, Ross and He, Kaiming and Dollar, Piotr},
booktitle={Proceedings of the IEEE international conference on computer vision},
pages={2980--2988},
year={2017}
}
@inproceedings{cui2019class,
title={Class-balanced loss based on effective number of samples},
author={Cui, Yifan and Jia, Meng and Lin, Tsung-Yi and Song, Yang and Belongie, Serge},
booktitle={Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition},
pages={9268--9277},
year={2019}
}
```
# Contribution and Support
Contributions, issues, and feature requests are welcome! Feel free to check out the  if you want to contribute.
If you find any bugs or have any questions, please open an issue on the repository or contact me through the email listed in our profiles.
If you find this project helpful, please give a ⭐️ on GitHub and share it with your friends and colleagues. This will help me grow and improve the project. Thank you for your support!
Raw data
{
"_id": null,
"home_page": "https://github.com/wildoctopus/cbloss",
"name": "cbloss",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "pytorch,loss,class-balanced,classification-loss,focal-loss,FocalLoss,cb_loss,cbloss",
"author": "Alok Pandey",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/2f/e1/348b60a355779126b1c4809035428415159862db2c67aebfb9b4b89e7082/cbloss-0.2.0.tar.gz",
"platform": null,
"description": "\n<div align=\"center\">\n <img src=\"cbloss.svg\" alt=\"PyPI\" >\n \n</div>\n\n<div align=\"center\">\n <img src=\"https://img.shields.io/pypi/v/cbloss\" alt=\"PyPI\" >\n <img src=\"https://github.com/wildoctopus/cbloss/actions/workflows/ci.yml/badge.svg\" alt=\"Build Status\">\n</div>\n\n# cbloss (Class Balanced Loss)\n`cbloss` is a Python package that provides Pytorch implementation of - .\n\nThis package also includes Pytorch Implementation of  as `Focal Loss` is currently not avaialable in `torch.nn` module.\n\n\n\n## Installation\n\nYou can install `cbloss` via pip:\n\n```\npip install cbloss\n```\n\n\n\n## Usage\n\n### Focal Loss\n\nFocal Loss is a popular loss function for imbalanced classification problems. It's a modification of the standard Cross Entropy nad Binary Classification Loss, that is designed to address class imbalance issues. In essence, it gives more weight to hard to classify examples.\n```\nFormula:\n For a binary classification problem:\n FL(pt) = -alpha * (1 - pt)**gamma * log(pt) if y = 1\n - (1 - alpha) * pt**gamma * log(1 - pt) otherwise\n\n For a multi-class classification problem:\n FL(pt) = -alpha * (1 - pt)**gamma * log(pt) if y = c\n - (1 - alpha) * pt**gamma * log(1 - pt) otherwise\n where:\n pt = sigmoid(x) for binary classification, and softmax(x) for multi-class classification\n alpha = balancing parameter, default to 1, the balance between positive and negative samples\n gamma = focusing parameter, default to 2, the degree of focusing, 0 means no focusing.\n \nArgs:\n num_classes (int) : number of classes\n alpha (float): balancing parameter, default to 1.\n gamma (float): focusing parameter, default to 2.\n reduction (str): reduction method for the loss, either 'none', 'mean' or 'sum', default to 'mean'.\n```\n```python\nfrom cbloss.loss import FocalLoss\n\nloss_fn = FocalLoss(num_classes=3, gamma=2.0, alpha=0.25)\n```\n\n### ClassBalancedLoss\n\nThis loss function helps address the problem of class imbalance in the training data by assigning higher weights to underrepresented classes during training. The weights are determined based on the `number of samples per class and a beta value`, which controls the degree of balancing between the classes.\n\nThe loss function supports different types of base losses, including `CrossEntropyLoss`, `BCEWithLogitsLoss`, and `FocalLoss`.\n```\n The effective number of samples per class is calculated as:\n\n effective_num = 1 - beta^(samples_per_cls)\n\n The weights for each class are then calculated as:\n\n weights = (1 - beta) / effective_num\n weights = weights / sum(weights) * num_classes\n\n The loss is calculated as:\n\n loss = (weights * base_loss).mean()\n\n where `base_loss` is the value returned by the base loss function.\n\n Args:\n samples_per_cls (list or numpy array): Number of samples per class in the training data.\n beta (float): Degree of balancing between the classes.\n num_classes (int): Number of classes in the classification problem.\n loss_func (nn.Module): Base loss function to use for calculating the loss. Should be one of\n the following: nn.CrossEntropyLoss, nn.BCEWithLogitsLoss, or FocalLoss..\n```\n```python\nfrom cbloss.loss import ClassBalancedLoss\n\nsamples_per_cls = [300, 200, 100] # an example case\nloss_func = nnCrossEntropyLoss(reduction = 'none')\n\nloss_fn = ClassBalancedLoss(samples_per_cls, beta=0.99, num_classes=3, loss_func=loss_func)\n\n```\nThe `loss_func` parameter should be set to one of these base losses (FocalLoss, nn.CrossEntropyLoss, nn.BCEWithLogitsLoss). \n\n`*** Please Note \"reduction = 'none'\" should be set for all base Loss Function, while using ClassBalancedLoss.` \n\n\n## v0.1.0\n\nIf you have v0.1.0 installed, please use cb_loss.loss to import FocalLoss and ClassBalancedLoss.\n\n```python\nfrom cb_loss.loss import ClassBalancedLoss, FocalLoss\n\nsamples_per_cls = [300, 200, 100] # an example case\nloss_func = nnCrossEntropyLoss(reduction = 'none')\n\nloss_fn = ClassBalancedLoss(samples_per_cls, beta=0.99, num_classes=3, loss_func=loss_func)\n\n```\n\n\n# Citations\n```\n @inproceedings{lin2017focal,\n title={Focal Loss for Dense Object Detection},\n author={Lin, Tsung-Yi and Goyal, Priya and Girshick, Ross and He, Kaiming and Dollar, Piotr},\n booktitle={Proceedings of the IEEE international conference on computer vision},\n pages={2980--2988},\n year={2017}\n }\n\n @inproceedings{cui2019class,\n title={Class-balanced loss based on effective number of samples},\n author={Cui, Yifan and Jia, Meng and Lin, Tsung-Yi and Song, Yang and Belongie, Serge},\n booktitle={Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition},\n pages={9268--9277},\n year={2019}\n }\n```\n\n\n# Contribution and Support\n\n\nContributions, issues, and feature requests are welcome! Feel free to check out the  if you want to contribute.\n\nIf you find any bugs or have any questions, please open an issue on the repository or contact me through the email listed in our profiles.\n\nIf you find this project helpful, please give a \u2b50\ufe0f on GitHub and share it with your friends and colleagues. This will help me grow and improve the project. Thank you for your support!\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "PyTorch implementations of two popular loss functions for imbalanced classification problems: Class Balanced Loss and Focal Loss.",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/wildoctopus/cbloss"
},
"split_keywords": [
"pytorch",
"loss",
"class-balanced",
"classification-loss",
"focal-loss",
"focalloss",
"cb_loss",
"cbloss"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "00fdf00f0207725b63d70bdda556e50ee57f7344ab8182be579ae4a3de8e50d3",
"md5": "66c27781d751e7eedef8bf068dd8d61c",
"sha256": "d63353acfa019a6cfa7f3f6ddec7b250b36277463191b640caa9ed63cfd114dc"
},
"downloads": -1,
"filename": "cbloss-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "66c27781d751e7eedef8bf068dd8d61c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 6908,
"upload_time": "2023-05-12T05:24:48",
"upload_time_iso_8601": "2023-05-12T05:24:48.316008Z",
"url": "https://files.pythonhosted.org/packages/00/fd/f00f0207725b63d70bdda556e50ee57f7344ab8182be579ae4a3de8e50d3/cbloss-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2fe1348b60a355779126b1c4809035428415159862db2c67aebfb9b4b89e7082",
"md5": "1199ca5a0047026689f21d463deaa765",
"sha256": "0bf2aa160a9e7104eb9bc1a0f1fca334a743cb4d85e269840375a0d58df31440"
},
"downloads": -1,
"filename": "cbloss-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "1199ca5a0047026689f21d463deaa765",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 6503,
"upload_time": "2023-05-12T05:24:50",
"upload_time_iso_8601": "2023-05-12T05:24:50.376659Z",
"url": "https://files.pythonhosted.org/packages/2f/e1/348b60a355779126b1c4809035428415159862db2c67aebfb9b4b89e7082/cbloss-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-12 05:24:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wildoctopus",
"github_project": "cbloss",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "cbloss"
}
JSON
