Add BaseModel.set_pos_weight for imbalanced binary/multilabel outcomes

[solarsys]

Problem

For binary and multilabel labels, BaseModel.get_loss_function() returns plain F.binary_cross_entropy_with_logits, and there is no way to weight the positive class. Rare clinical outcomes (5–15% prevalence is typical) usually need that. A downstream EHR project had to patch around it.

Change

model = RNN(dataset=samples)
model.set_pos_weight("balanced", train_dataset)   # negatives / positives, per label
model.set_pos_weight(9.0)                         # or a fixed weight
model.set_pos_weight(None)                        # back to unweighted
model.pos_weight                                  # tensor or None

• get_loss_function() passes the weight as pos_weight, moved to the logits' device. The default is unchanged.
• Multilabel: "balanced" gives one weight per label; a label with no positives gets weight 1 and a warning.
• Multiclass and regression raise ValueError.

Design choices, open to your view

• A method, not a constructor argument (the spec proposed BaseModel(..., pos_weight=…)). Of the 29 models, none pass extra arguments through to BaseModel.__init__, so a constructor argument couldn't reach them without editing each one. Every model fetches the loss with self.get_loss_function() on each forward pass (31 call sites), so a weight set after construction applies to all of them.
• "balanced" needs the dataset passed explicitly. model.dataset is usually the full, unsplit sample set, and computing prevalence from it would let validation and test labels set the weight.
• Not covered: GAMENet, SafeDrug, MoleRec and MICRON compute their own losses. The docs say so.

Tests, docs, example

• New tests/core/test_pos_weight.py (8 tests):
  • the default is unweighted;
  • a fixed weight matches F.binary_cross_entropy_with_logits(pos_weight=…);
  • "balanced" uses the given training data, not the model's own;
  • "balanced" without a dataset raises;
  • clearing the weight works;
  • the forward-pass loss uses the weight;
  • multilabel gets per-label weights;
  • multiclass is rejected.
• Existing model.mode, RNN and MLP tests pass.
• docs/api/models.rst gets an "Imbalanced outcomes" section: pass the training split, which models ignore the weight, and that weighting shifts probabilities upward, so check calibration.
• New examples/imbalanced_outcome_pos_weight.py: a 10% outcome, trained with and without "balanced", scored side by side.
• Full core suite: Ran 1405 tests … OK (skipped=76). tools/check_pr_rules.py passes.

🤖 Generated with Claude Code

[jhnwu3]

lgtm.

This might be worth revisiting in a later timeline to see if there's a cleaner solution to this problem with the outdated pyhealth.trainer. But, I think this might be the easiest for now.