{"id":15639098,"url":"https://github.com/fcakyon/balanced-loss","last_synced_at":"2025-10-06T01:54:09.864Z","repository":{"id":48090781,"uuid":"516290672","full_name":"fcakyon/balanced-loss","owner":"fcakyon","description":"Easy to use class balanced cross entropy and focal loss implementation for Pytorch","archived":false,"fork":false,"pushed_at":"2024-12-17T11:24:31.000Z","size":31,"stargazers_count":99,"open_issues_count":1,"forks_count":8,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-27T07:22:54.070Z","etag":null,"topics":["balanced-loss","binary-crossentropy","class-balanced-loss","computer-vision","cross-entropy","cvpr","deep-learning","focal-loss","image-classification","loss-functions","machine-learning","pip","pypi","python","pytorch"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/balanced-loss/","language":"Python","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fcakyon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"fcakyon"}},"created_at":"2022-07-21T08:38:10.000Z","updated_at":"2025-09-09T07:05:24.000Z","dependencies_parsed_at":"2025-02-28T13:14:15.646Z","dependency_job_id":"85324b42-59c5-4f63-8207-a34caae284fb","html_url":"https://github.com/fcakyon/balanced-loss","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/fcakyon/balanced-loss","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fcakyon%2Fbalanced-loss","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fcakyon%2Fbalanced-loss/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fcakyon%2Fbalanced-loss/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fcakyon%2Fbalanced-loss/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fcakyon","download_url":"https://codeload.github.com/fcakyon/balanced-loss/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fcakyon%2Fbalanced-loss/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278547817,"owners_count":26004773,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-05T02:00:06.059Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["balanced-loss","binary-crossentropy","class-balanced-loss","computer-vision","cross-entropy","cvpr","deep-learning","focal-loss","image-classification","loss-functions","machine-learning","pip","pypi","python","pytorch"],"created_at":"2024-10-03T11:24:44.009Z","updated_at":"2025-10-06T01:54:09.834Z","avatar_url":"https://github.com/fcakyon.png","language":"Python","readme":"\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://user-images.githubusercontent.com/34196005/180311379-1003da44-cdf9-46e8-af83-e65fbc3710cd.png\" width=\"350\"\u003e\n\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n    \u003ca href=\"https://badge.fury.io/py/balanced-loss\"\u003e\u003cimg src=\"https://badge.fury.io/py/balanced-loss.svg\" alt=\"pypi version\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://pepy.tech/project/balanced-loss\"\u003e\u003cimg src=\"https://pepy.tech/badge/balanced-loss\" alt=\"total downloads\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://twitter.com/fcakyon\"\u003e\u003cimg src=\"https://img.shields.io/badge/twitter-fcakyon_-blue?logo=twitter\u0026style=flat\" alt=\"fcakyon twitter\"\u003e\u003c/a\u003e\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n    Easy-to-use, class-balanced, cross-entropy and focal loss implementation for Pytorch.\n\u003c/p\u003e\n\n## Theory\n\nWhen training dataset labels are imbalanced, one thing to do is to balance the loss across sample classes.\n\n- First, the effective number of samples are calculated for all classes as:\n\n![alt-text](https://user-images.githubusercontent.com/34196005/180266195-aa2e8696-cdeb-48ed-a85f-7ffb353942a4.png)\n\n- Then the class balanced loss function is defined as:\n\n![alt-text](https://user-images.githubusercontent.com/34196005/180266198-e27d8cba-f5e1-49ca-9f82-d8656333e3c4.png)\n\n## Installation\n\n```bash\npip install balanced-loss\n```\n\n## Usage\n\n- Standard losses:\n\n```python\nimport torch\nfrom balanced_loss import Loss\n\n# outputs and labels\nlogits = torch.tensor([[0.78, 0.1, 0.05]]) # 1 batch, 3 class\nlabels = torch.tensor([0]) # 1 batch\n\n# focal loss\nfocal_loss = Loss(loss_type=\"focal_loss\")\nloss = focal_loss(logits, labels)\n```\n\n```python\n# cross-entropy loss\nce_loss = Loss(loss_type=\"cross_entropy\")\nloss = ce_loss(logits, labels)\n```\n\n```python\n# binary cross-entropy loss\nbce_loss = Loss(loss_type=\"binary_cross_entropy\")\nloss = bce_loss(logits, labels)\n```\n\n- Class-balanced losses:\n\n```python\nimport torch\nfrom balanced_loss import Loss\n\n# outputs and labels\nlogits = torch.tensor([[0.78, 0.1, 0.05]]) # 1 batch, 3 class\nlabels = torch.tensor([0]) # 1 batch\n\n# number of samples per class in the training dataset\nsamples_per_class = [30, 100, 25] # 30, 100, 25 samples for labels 0, 1 and 2, respectively\n\n# class-balanced focal loss\nfocal_loss = Loss(\n    loss_type=\"focal_loss\",\n    samples_per_class=samples_per_class,\n    class_balanced=True\n)\nloss = focal_loss(logits, labels)\n```\n\n```python\n# class-balanced cross-entropy loss\nce_loss = Loss(\n    loss_type=\"cross_entropy\",\n    samples_per_class=samples_per_class,\n    class_balanced=True\n)\nloss = ce_loss(logits, labels)\n```\n\n```python\n# class-balanced binary cross-entropy loss\nbce_loss = Loss(\n    loss_type=\"binary_cross_entropy\",\n    samples_per_class=samples_per_class,\n    class_balanced=True\n)\nloss = bce_loss(logits, labels)\n```\n\n- Customize parameters:\n\n```python\nimport torch\nfrom balanced_loss import Loss\n\n# outputs and labels\nlogits = torch.tensor([[0.78, 0.1, 0.05]]) # 1 batch, 3 class\nlabels = torch.tensor([0])\n\n# number of samples per class in the training dataset\nsamples_per_class = [30, 100, 25] # 30, 100, 25 samples for labels 0, 1 and 2, respectively\n\n# class-balanced focal loss\nfocal_loss = Loss(\n    loss_type=\"focal_loss\",\n    beta=0.999, # class-balanced loss beta\n    fl_gamma=2, # focal loss gamma\n    samples_per_class=samples_per_class,\n    class_balanced=True\n)\nloss = focal_loss(logits, labels)\n```\n\n## Improvements\n\nWhat is the difference between this repo and vandit15's?\n\n- This repo is a pypi installable package\n- This repo implements loss functions as `torch.nn.Module`\n- In addition to class balanced losses, this repo also supports the standard versions of the cross entropy/focal loss etc. over the same API\n- All typos and errors in vandit15's source are fixed\n- Continuously tested on PyTorch 1.13.1 and 2.5.1\n- Automatically selects loss module device based on logits\n\n## References\n\nhttps://arxiv.org/abs/1901.05555\n\nhttps://github.com/richardaecn/class-balanced-loss\n\nhttps://github.com/vandit15/Class-balanced-loss-pytorch\n","funding_links":["https://github.com/sponsors/fcakyon"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffcakyon%2Fbalanced-loss","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffcakyon%2Fbalanced-loss","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffcakyon%2Fbalanced-loss/lists"}