feat(Detection): add pos_weight parameter in BCEWithLogitsLoss

[hulkds]

This is the new PR following this conversation: #8557
Related issues:

• pos_weight for dealing with imbalanced dataset #8578 (comment)
• Is it possible to change class weight? #2703

🛠️ PR Summary

_{Made with ❤️ by Ultralytics Actions}

🌟 Summary

Added pos_weight hyperparameter to address class imbalance in model training.

📊 Key Changes

• 🆕 Introduction of the pos_weight parameter in the training documentation.
• 🛠 Update to the default configuration (default.yaml) introducing pos_weight as a configurable list.
• 💡 Enhancement of the loss.py file to implement pos_weight in the BCEWithLogitsLoss.

🎯 Purpose & Impact

• 🎯 The pos_weight parameter aims to provide a mechanism to give more importance to positive examples during training, addressing scenarios with class imbalance.
• 👩‍💻 By incorporating pos_weight into the loss function, model training can achieve more balanced performance across classes, potentially improving accuracy for underrepresented classes.
• 🚀 For end-users, especially those working with imbalanced datasets, this update can lead to more robust models and fairer representation of minority classes in predictions.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 70.13%. Comparing base (e547771) to head (75616ae).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #8620      +/-   ##
==========================================
- Coverage   74.29%   70.13%   -4.16%     
==========================================
  Files         124      124              
  Lines       15699    15699              
==========================================
- Hits        11663    11010     -653     
- Misses       4036     4689     +653     

Flag	Coverage Δ
Benchmarks	35.31% <33.33%> (ø)
GPU	37.18% <100.00%> (-5.67%)	⬇️
Tests	66.27% <100.00%> (-3.79%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[Burhan-Q]

For the record, just noticed #7655 appears to be relegated/similar

[nattigt]

Hello Ultralytics team, is this feature released yet ? i am having this error 'SyntaxError: 'pos_weight' is not a valid YOLO argument. @Burhan-Q @hulkds

[Burhan-Q]

@nattigt this feature has not yet been reviewed or released. You will see it marked as "merged" when or if it is included with the main Ultralytics branch. If you wish to use this note, you should check out our clone this Pull Request (PR). I can't tell you a timeline when this may be reviewed or added, but I just have tried to provide feedback to assist the contributor that will make it easier for the Team to review this PR.

[manicmojo]

Can you expand on how best to use this?
Do I just make the file changes as linked on this PR?
Then, as I have 33 classes, heavily unbalanced (as there's multiple of some items on every image) as seen below:

• 0: 1079 occurrences
• 1: 372 occurrences
• 2: 434 occurrences
• 3: 100 occurrences
• 4: 811 occurrences
• 5: 905 occurrences
• 6: 21 occurrences
• 7: 768 occurrences
• 8: 836 occurrences
• 9: 1373 occurrences
• 10: 1566 occurrences
• 11: 37 occurrences
• 12: 707 occurrences
• 13: 298 occurrences
• 14: 731 occurrences
• 15: 18796 occurrences <-
• 16: 18696 occurrences <-
• 17: 3000 occurrences
• 18: 1577 occurrences
• 19: 2355 occurrences
• 20: 1194 occurrences
• 21: 0 occurrences
• 22: 5484 occurrences
• 23: 2749 occurrences
• 24: 3166 occurrences
• 25: 39298 occurrences <-
• 26: 2728 occurrences
• 27: 858 occurrences
• 28: 1570 occurrences
• 29: 3045 occurrences
• 30: 2457 occurrences
• 31: 229 occurrences
• 32: 849 occurrences
• Total: 118089 occurrences

Do I make a near exact representation to balance, and simply train my model like so?:
pos_weight = [ 108.44, 316.44, 271.09, 1179.89, 144.61, 129.49, 5622.29, 152.76, 140.25, 85.01, 74.41, 3190.59, 166.03, 395.27, 160.54, 5.28, 5.32, 38.36, 73.88, 49.14, 97.90, 0, 20.53, 41.96, 36.30, 2.00, 42.29, 136.63, 74.22, 37.78, 47.06, 514.67, 138.09 ]
I used 0 for class 21 to exclude completely.
Am I missing anything?

Thanks in advance, sorry if this is the wrong place.

[glenn-jocher]

@manicmojo hello there! 👋 No worries, you're definitely in the right place for asking questions. 😄

Yes, you've got the gist of how to use pos_weight for handling class imbalance in your dataset. By altering the pos_weight in your config as you've described, you're essentially telling the model to "pay more attention" to underrepresented classes during training, which is exactly what you want in a heavily imbalanced scenario like yours.

Your approach to calculate the pos_weight based on class occurrences and using a weight of 0 for class 21 to exclude it is indeed correct. When specifying pos_weight, ensure you align each weight with its corresponding class index, as you've shown.

Just a quick note, depending on the version of YOLOv8 you're using (since it's continuously being improved and updated), make sure to sync with the latest documentation or the specific Pull Request (PR) instructions for applying pos_weight.

Quick example to set pos_weight in your config file might look like this:

# Assuming this is part of your YOLOv8 model config file
pos_weight: [108.44, 316.44, ..., 138.09]

And then, you would proceed to train your model as usual. Remember, handling class imbalance is a bit of trial and error, so you might need to adjust your weights and observe the results.

I hope that helps! If you have more questions, feel free to ask. Happy training! 🚀

[austy81]

Looks good to me. I'd appreciate this to be released.

[CourchesneA]

Thanks for this contribution - would be great to have this merged into main

[Burhan-Q]

@austy81 and @CourchesneA could you both add a 👍 to the original PR comment? I think it would be a great way to show what PRs the community have the most interest in seeing added (hoping I can get this to be something official).