Upload README.md with huggingface_hub

README.md

@@ -107,6 +107,21 @@ Each level (`leaf` = 137 labels, `upper` = 38 container groups, `anatomy` = 10 s
 max-over-children roll-up of the leaf predictions (`model.aggregate_hierarchy(...)`). Coarser
 levels are easier to match, so upper/anatomy F1 are typically higher than leaf.
 
+### Per-label best F1 (threshold tuning)
+
+The default decision threshold is a single global value, but the F1-optimal threshold differs per
+label. To get the **best achievable F1 per label** (and the threshold that achieves it) against a
+ground-truth label set:
+
+```python
+# gt: a DataFrame with the 137 label columns (ternary; positive == 1), or a binary array
+res = model.per_label_best_f1(reports, gt, tokenizer=tok, level="leaf", min_pos=30)
+res["macro_best_f1_min_pos"]                 # macro best-F1 over labels with >= min_pos positives
+res["per_label"]["Pleural effusion"]         # {'best_f1':.., 'best_threshold':.., 'n_pos':..}
+```
+
+Per-label threshold tuning lifts macro-F1 by ~4–6 points over the fixed-0.5 threshold (see below).
+
 ## Inputs & conventions
 
 - Input is the **findings** text (the model was trained on CT-RATE findings + their refined
@@ -143,6 +158,17 @@ rows are the hierarchy roll-up.
 | upper (≥30 positives) | 19 | 0.837 | — |
 | anatomy | 10 | 0.869 | — |
 
+**Per-label best F1** (threshold swept per label to maximize F1; macro over leaf labels with ≥30
+positives, via `model.per_label_best_f1`):
+
+| Eval set | macro best-F1 (≥30) | macro-F1 @0.5 (≥30) | macro best-F1 (all evaluated) |
+|---|--:|--:|--:|
+| CT-RATE public | **0.907** | 0.866 | 0.844 |
+| Private | **0.820** | 0.761 | 0.795 |
+
+F1-optimal thresholds vary widely by label (~0.04–0.75), so per-label tuning recovers ~4–6 macro-F1
+points over a single global threshold.
+
 Leaf macro-AUC barely moves public→private (**0.989 → 0.972**), i.e. label ranking transfers to
 the unseen set; the F1 gap is mostly threshold / labeling-convention, not a domain failure.
 Separately, a radiologist spot-checked **966** reports of the public test labels (857 fully