Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,63 @@
+---
+license: apache-2.0
+language:
+  - en
+  - nl
+  - da
+  - es
+  - fr
+tags:
+  - text2text-generation
+  - icd
+  - historical-demography
+  - digital-humanities
+pipeline_tag: text2text-generation
+base_model: google/flan-t5-base
+---
+
+# codLLM base (deployment checkpoint)
+
+Fine-tuned FLAN-T5-base that assigns **ICD-10h** codes to free-text causes of
+death from historical death registers (roughly 1850-1939), across Dutch, Danish,
+Spanish, French, English and Latin phrasings with archaic spellings.
+
+## Input format matters, a lot
+
+The model is highly sensitive to its input shape. Two formats were trained:
+
+| format | example |
+|---|---|
+| `cod` | `tabes meseraica` |
+| `cod_age_sex` | `cod: stuipen \| age: unknown \| sex: male` |
+
+Rules that are easy to get wrong:
+
+* **cod-only is a bare string** with no `cod: ` prefix.
+* **cod_age_sex always emits all three fields**, using the literal string
+  `unknown` when a value is missing or unmappable. Omitting a field produces a
+  shape the model never saw in training.
+
+Which format performs better is **source dependent**. On held-out sources scored
+by leave-one-source-out checkpoints, exact match ranged from 0.043 to 0.593 on
+the same records purely by changing the format. Measure on your own data rather
+than assuming a default.
+
+## Output
+
+Comma-separated ICD-10h codes; the task is multi-label. Pair the model with the
+included `ICD10h_Masterlist_2024.tsv` for code descriptions.
+
+## Uncertainty
+
+Mean token entropy over the generated sequence is a usable abstention signal.
+The reference operating point is `0.127`, chosen for roughly 80% coverage on an
+unseen-string slice. Entropy correlates with output length, so it is a better
+ranking signal than an absolute per-record probability.
+
+## Limitations
+
+* Sub-code granularity may follow a different archive's coding convention than
+  yours; the broader category is often right where the sub-code differs.
+* On cause strings never seen in training, accuracy drops substantially.
+* Confident wrong codes occur, particularly for convention mismatches, so a
+  low-entropy prediction is not a guarantee of correctness.