Upload README.md with huggingface_hub

README.md

@@ -1,21 +1,70 @@
-# pockethb-base (EXPERIMENTAL — not a measurement tool)
+---
+license: mit
+tags:
+- regression
+- medical-imaging
+- fingernail
+- hemoglobin
+---
 
-base hemoglobin regressor from [pocketHb](https://github.com/jayanthvee/pocketHb). resnet18 finetuned on the [nature sci data 2024](https://www.nature.com/articles/s41597-024-03895-9) fingernail+hb dataset (n=250 subjects). subject-disjoint 70/15/15 split, seed 42.
+# pockethb-base
 
-## test metrics (patient-level, n=37 subjects)
+base hemoglobin regressor from the [pocketHb](https://github.com/jayanthvee/pocketHb) project. **not a measurement tool. read this whole card before using.**
 
-- MAE: 1.582 g/dL
-- RMSE: ~2.32 g/dL
-- **R² ≈ +0.01**
+## what this is
 
-**the R² being essentially zero is the headline finding.** this model is not meaningfully estimating hemoglobin. it has primarily learned to regress predictions toward the population mean (~12.55 g/dL). the MAE improvement over the dumb predict-the-mean baseline (1.77 g/dL) is marginal and mostly attributable to train/test mean drift, not learned image features.
+a global, population-level Hb regressor on fingernail photos. methodology follows Rudokaite et al., BNAIC 2025 (Tilburg/Sanquin smartphone-Hb paper):
 
-this is consistent with what every small-n open-source replication of the [Mannino et al. PNAS 2025 paper](https://doi.org/10.1073/pnas.2424677122) hits: the paper used 9,061 subjects with paired CBC labels (and 1.4M+ real-world uses). this dataset has 250 subjects with one photo each. there is not enough data here to recover the photo→Hb signal well at the population level.
+- frozen convnext_tiny.fb_in22k_ft_in1k via 	imm (no fine-tuning)
+- Shades-of-Gray (p=6) illumination correction → 224x224 resize → ImageNet normalize
+- per-patient aggregation: mean + std of crop embeddings (1536-d patient vector)
+- standardize → PLS + SVR(RBF) → isotonic calibration → weighted blend
+- trained on Nature Sci Data 2024 fingernail+Hb dataset (n=250 subjects, single CBC each)
+
+trained on **nail crops only**. the public Nature 2024 release ships 600x800 images, but 606 of 750 skin bboxes were labelled in a taller source frame and now sit below the bottom edge of the released images. only 83 patients would survive a nail+skin fusion — we ran nail-only on the full 250 instead.
+
+## metrics (5-fold stratified CV, n=250)
+
+- **MAE: 2.09 g/dL**
+- **RMSE: 2.74 g/dL**
+- **R²: -0.05**
+
+R² ≈ 0 means this global model is essentially predicting near the dataset mean. it barely beats the predict-mean floor (MAE ~2.14 g/dL) on this dataset. **this is the documented ceiling of population-level Hb modeling at sub-1000-subject scale**, not a bug:
+
+- The Rudokaite/BNAIC paper itself, with the same methodology on n=159, got MAE 0.6 mmol/L — that sounds clinical until you notice their predict-mean floor was ~0.63 mmol/L. similar R² ≈ 0 story, smaller absolute number because their donor population had Hb std 0.79 mmol/L vs our 2.67 g/dL.
+- Mannino et al. (PNAS 2025) only got clinical-near accuracy with n=9,061 subjects PLUS per-user personalization. their global model alone is not clinically useful either; they patented and locked the personalization layer (US 12268498).
 
 ## intended use
 
-**only as an input to a per-user personalization layer.** the open-source contribution of [pocketHb](https://github.com/jayanthvee/pocketHb) is the personalization layer that calibrates this noisy base model to a users known baseline hemoglobin value (from a real CBC). without that calibration, this base regressor should not be used.
+**only as an input to a per-user calibration / personalization layer.** the open-source contribution of [pocketHb](https://github.com/jayanthvee/pocketHb) is exactly that personalization layer. without it, this base regressor is research artifact only.
 
 ## not a medical device
 
-research replication only. **do not use to estimate anyones actual hemoglobin.** not FDA cleared, not validated clinically, not a doctor. if you need a hemoglobin reading, get a blood test.
+research replication only. **must not be used to estimate anyone\'s actual hemoglobin in any clinical, diagnostic, or treatment context.** not FDA cleared. not validated clinically. not a doctor. if you need a hemoglobin reading, get a blood test.
+
+## how to use
+
+`python
+import pickle
+from huggingface_hub import hf_hub_download
+
+# download bundle
+bundle_path = hf_hub_download(repo_id='bubbaonbubba/pockethb-base', filename='pockethb_base.pkl')
+with open(bundle_path, 'rb') as f:
+    bundle = pickle.load(f)
+
+# bundle contains: backbone_name, image_size, imagenet_mean/std,
+# shades_of_gray_p, modalities, aggregation, blender, n_train_patients, seed
+`
+
+see the [pocketHb repo](https://github.com/jayanthvee/pocketHb) for the full inference pipeline including image preprocessing and embedding extraction.
+
+## citation context
+
+- Mannino et al., PNAS 2025. doi:10.1073/pnas.2424677122
+- Rudokaite et al., BNAIC 2025 (Tilburg/Sanquin)
+- Nature Sci Data 2024 dataset: doi:10.1038/s41597-024-03895-9
+
+## license
+
+MIT.