@flame-cai/anthro 1.1.1

package/src/anthro.js

@@ -0,0 +1,339 @@
+/**
+ * @module anthro
+ * @version 1.1.1
+ * @repo https://github.com/flame-cai/anthro
+ *
+ * ╔══════════════════════════════════════════════════════════════════════════╗
+ * ║         WHO 2006 Child Growth Standards — Production Library            ║
+ * ╠══════════════════════════════════════════════════════════════════════════╣
+ * ║                                                                          ║
+ * ║  TABLE SOURCE — OFFICIAL WHO igrowup DAY-INDEXED TABLES (default)       ║
+ * ║  ─────────────────────────────────────────────────────────               ║
+ * ║  Extracted from R package "anthro" v1.1.0 (WHO-maintained, CRAN):       ║
+ * ║    growthstandards_weianthro  (weight-for-age,  0–1826 d)               ║
+ * ║    growthstandards_lenanthro  (length/ht-for-age, 0–1826 d)             ║
+ * ║    growthstandards_bmianthro  (BMI-for-age,      0–1826 d)              ║
+ * ║    growthstandards_acanthro   (MUAC-for-age,     91–1826 d)             ║
+ * ║    growthstandards_wflanthro  (wt-for-length,    45.0–110.0 cm)         ║
+ * ║    growthstandards_wfhanthro  (wt-for-height,    65.0–120.0 cm)         ║
+ * ║  These are the same tables used by WHO igrowup SAS/SPSS/Stata software. ║
+ * ║  https://www.who.int/tools/child-growth-standards/software              ║
+ * ║  R package: https://github.com/WorldHealthOrganization/anthro           ║
+ * ║                                                                          ║
+ * ║  MONTH-INDEXED TABLES (mode:'month')                                    ║
+ * ║  Same WHO 2006 study, published as monthly supplementary tables.        ║
+ * ║  One LMS row per whole month (0–60 m), height in 0.5 cm steps.         ║
+ * ║                                                                          ║
+ * ║  FORMULA — WHO Technical Report 2006, §5.2, pp 300–304                  ║
+ * ║    z = [(X/M)^L − 1] / (L × S)   when L ≠ 0                           ║
+ * ║    z = ln(X/M) / S                 when L = 0                           ║
+ * ║    SD23 restricted-LMS adjustment beyond ±3 SD (ibid.)                  ║
+ * ║                                                                          ║
+ * ║  MEASURE CORRECTION ±0.7 cm — WHO 2006 Chapter 7                        ║
+ * ║    Day mode:   reads 'loh' field from lenanthro table per day           ║
+ * ║    Month mode: expects L for months 0–23, H for months 24–60            ║
+ * ║                                                                          ║
+ * ║  CLASSIFICATION — WHO 2009                                               ║
+ * ║    https://www.who.int/publications/i/item/9789241598163                ║
+ * ║    MUAC: SAM<115mm, MAM 115–<125mm, Normal ≥125mm                      ║
+ * ║    z:    Severe/SAM <−3SD, Moderate/MAM −3 to <−2SD, Normal ≥−2SD     ║
+ * ║                                                                          ║
+ * ║  PLAUSIBILITY FLAGS — WHO igrowup (igrowup_standard.sas)                ║
+ * ║    WFA/LHFA: |z|>6  |  WFLH/BMI/ACFA: |z|>5                           ║
+ * ║                                                                          ║
+ * ╚══════════════════════════════════════════════════════════════════════════╝
+ */
+
+'use strict';
+
+// ── Constants ──────────────────────────────────────────────────────────────────
+const DAYS_PER_MONTH     = 30.4375; // WHO igrowup: ANTHRO_DAYS_OF_MONTH = 365.25/12
+const MEASURE_CORRECTION = 0.7;     // cm, recumbent↔standing, WHO 2006 Ch.7
+const MAX_AGE_DAYS       = 1826;    // 5 × 365.25 rounded down
+const MAX_AGE_MONTHS     = 60;
+const FLAG = { wfa:6, lhfa:6, wflh:5, bmi:5, acfa:5 };
+
+// ── LMS z-score formula with SD23 adjustment ──────────────────────────────────
+function lmsZ(X, L, M, S) {
+  if (!isFinite(X)||X<=0||!isFinite(M)||M<=0||!isFinite(L)||!isFinite(S)) return null;
+  let z = Math.abs(L)<1e-10 ? Math.log(X/M)/S : (Math.pow(X/M,L)-1)/(L*S);
+  if (!isFinite(z)) return null;
+  if (z>3) {
+    const s3=M*Math.pow(1+L*S*3,1/L), s2=M*Math.pow(1+L*S*2,1/L);
+    if (isFinite(s3)&&isFinite(s2)&&s3!==s2) z=3+(X-s3)/(s3-s2);
+  } else if (z<-3) {
+    const t3=1+L*S*-3, t2=1+L*S*-2;
+    const s3=M*Math.pow(t3>1e-9?t3:1e-9,1/L), s2=M*Math.pow(t2>1e-9?t2:1e-9,1/L);
+    if (isFinite(s3)&&isFinite(s2)&&s2!==s3) z=-3+(X-s3)/(s2-s3);
+  }
+  return isFinite(z)?z:null;
+}
+
+// ── O(1) table lookup via WeakMap-cached Maps ──────────────────────────────────
+const _mc=new WeakMap();
+function _map(tbl){
+  if(!_mc.has(tbl)){
+    const m=new Map(), {i,l,m:ms,s,loh}=tbl;
+    for(let k=0;k<i.length;k++) m.set(i[k],{L:l[k],M:ms[k],S:s[k],loh:loh?loh[k]:null});
+    _mc.set(tbl,m);
+  }
+  return _mc.get(tbl);
+}
+// Day tables: integer key
+function lookupDay(tbl,d){return _map(tbl).get(Math.round(d))??null;}
+// Month tables: integer month key
+function lookupMonth(tbl,m){return _map(tbl).get(Math.round(m))??null;}
+// Height tables: 0.1cm key (day mode) or 0.5cm key (month mode)
+function lookupCm(tbl,cm,step=0.1){
+  const k=Math.round(cm*(1/step))*step;
+  return _map(tbl).get(Math.round(k*10)/10)??null;
+}
+
+// ── Classification (WHO 2009 cut-points) ──────────────────────────────────────
+const classify={
+  wflh(z){if(z==null||!isFinite(z))return null;return z<-3?'Severe wasting':z<-2?'Moderate wasting':z>3?'Obese':z>2?'Overweight':'Normal';},
+  lhfa(z){if(z==null||!isFinite(z))return null;return z<-3?'Severely stunted':z<-2?'Moderately stunted':'Normal';},
+  wfa(z) {if(z==null||!isFinite(z))return null;return z<-3?'Severely underweight':z<-2?'Moderately underweight':'Normal';},
+  zscore(z){if(z==null||!isFinite(z))return null;return z<-3?'SAM':z<-2?'MAM':z>3?'Obese':z>2?'Overweight':'Normal';},
+  muac(mm){if(mm==null||!isFinite(mm))return null;return mm<115?'SAM':mm<125?'MAM':'Normal';}
+};
+
+// ── Age utilities ──────────────────────────────────────────────────────────────
+function ageDays(dob,measured){
+  const parse=d=>{if(!d)return null;const p=d instanceof Date?d:new Date(d);return isNaN(p)?null:p;};
+  const d0=parse(dob),d1=parse(measured)??new Date();
+  if(!d0||!d1)return null;
+  const utc=d=>Date.UTC(d.getFullYear(),d.getMonth(),d.getDate());
+  const days=Math.floor((utc(d1)-utc(d0))/86400000);
+  return days>=0?days:null;
+}
+function monthsToDays(m){return Math.round(m*DAYS_PER_MONTH);}
+function daysToMonths(d){return d/DAYS_PER_MONTH;}
+
+// ── Input helpers ──────────────────────────────────────────────────────────────
+function normSex(r){
+  if(r===1||r==='1')return'M';if(r===2||r==='2')return'F';
+  if(typeof r==='string'){const s=r.trim().toLowerCase();if(s==='male'||s==='m')return'M';if(s==='female'||s==='f')return'F';}
+  return null;
+}
+function r4(x){return(x==null||!isFinite(x))?null:Math.round(x*10000)/10000;}
+function r2(x){return(x==null||!isFinite(x))?null:Math.round(x*100)/100;}
+
+// ── Core compute ───────────────────────────────────────────────────────────────
+function computeZScores(params){
+  const{sex:rawSex,dob,measured,age_days:rad,age_months:ram,
+    weight_kg,weight_g,height_cm,muac_cm,muac_mm:rmm,
+    measure:rawMeasure,oedema=false,mode='day',_T}=params;
+
+  const R={
+    mode,sex:null,age_days:null,age_months:null,
+    weight_kg:null,height_cm_raw:null,height_cm_adj:null,
+    muac_mm:null,bmi_val:null,measure:null,measure_correction:null,
+    z_lhfa:null,z_wfa:null,z_wflh:null,z_bmi:null,z_acfa:null,
+    flag_lhfa:0,flag_wfa:0,flag_wflh:0,flag_bmi:0,flag_acfa:0,
+    muac_threshold:null,acfa:null,bmi:null,lhfa:null,wfa:null,wflh:null,
+    errors:[],warnings:[]
+  };
+  const miss=(...a)=>`Missing ${a.join(' & ')} to compute`;
+
+  if(!_T){R.errors.push('WHO tables not loaded');return R;}
+  if(mode!=='day'&&mode!=='month'){R.errors.push("mode must be 'day' or 'month'");return R;}
+
+  // Sex
+  const sex=normSex(rawSex);
+  if(!sex){R.errors.push('sex required: male|female|m|f|M|F|1|2');return R;}
+  R.sex=sex;
+
+  // Age — priority: dob > age_days > age_months
+  let days=null,months=null;
+  if(dob!=null){
+    days=ageDays(dob,measured);
+    if(days===null)R.errors.push('Invalid dob/measured date');
+    else months=daysToMonths(days);
+  }else if(rad!=null&&isFinite(rad)&&rad>=0){
+    days=Math.round(rad);months=daysToMonths(days);
+  }else if(ram!=null&&isFinite(ram)&&ram>=0){
+    months=ram;days=monthsToDays(ram);
+  }
+  if(days!==null&&days<0){R.errors.push('Age must be ≥ 0');days=null;months=null;}
+  if(mode==='day'&&days!==null&&days>MAX_AGE_DAYS)
+    R.warnings.push(`Age ${days}d > ${MAX_AGE_DAYS}d (60m) table max`);
+  if(mode==='month'&&months!==null&&Math.round(months)>MAX_AGE_MONTHS)
+    R.warnings.push(`Age ${Math.round(months)}m > ${MAX_AGE_MONTHS}m table max`);
+  R.age_days=days;R.age_months=days!=null?r2(months):null;
+
+  // Weight
+  let wKg=null;
+  if(weight_kg!=null&&isFinite(weight_kg)&&weight_kg>0)wKg=weight_kg;
+  else if(weight_g!=null&&isFinite(weight_g)&&weight_g>0)wKg=weight_g/1000;
+  R.weight_kg=wKg;
+  if(oedema)R.warnings.push('Oedema: WFA & WFLH may overestimate malnutrition');
+
+  // Height
+  let hCm=null,measureUsed=null;
+  if(height_cm!=null&&isFinite(height_cm)&&height_cm>0){
+    hCm=height_cm;R.height_cm_raw=hCm;
+    // Default measure by age: L for <24m, H for ≥24m
+    measureUsed=rawMeasure?rawMeasure.toUpperCase():(days!=null&&days<730?'L':'H');
+    R.measure=measureUsed;
+  }
+
+  // MUAC
+  let muacMm=null;
+  if(rmm!=null&&isFinite(rmm)&&rmm>0)muacMm=rmm;
+  else if(muac_cm!=null&&isFinite(muac_cm)&&muac_cm>0)muacMm=muac_cm*10;
+  R.muac_mm=muacMm;
+
+  // BMI (raw, will be updated if height correction applied)
+  if(wKg&&hCm)R.bmi_val=r4(wKg/Math.pow(hCm/100,2));
+
+  // MUAC absolute (age-independent)
+  R.muac_threshold=muacMm!=null?classify.muac(muacMm):miss('muac');
+
+  // Guard: no age
+  if(days===null){['acfa','bmi','lhfa','wfa','wflh'].forEach(k=>R[k]=miss('age'));return R;}
+  const oob=(mode==='day'?days>MAX_AGE_DAYS:Math.round(months)>MAX_AGE_MONTHS);
+  if(oob){['acfa','bmi','lhfa','wfa','wflh'].forEach(k=>R[k]=`Age > 60 months (table max ${MAX_AGE_DAYS}d)`);return R;}
+
+  function setZ(key,zv,clFn){
+    if(zv==null)return;
+    R[`z_${key}`]=r4(zv);
+    if(Math.abs(zv)>FLAG[key]){R[`flag_${key}`]=1;R.warnings.push(`z_${key}=${r2(zv)} exceeds plausibility |z|>${FLAG[key]}`);}
+    R[key]=clFn(zv);
+  }
+
+  // Lookup helper by mode
+  const lookupAge=(tbl)=>mode==='day'?lookupDay(tbl,days):lookupMonth(tbl,Math.round(months));
+  const lookupHt =(tbl)=>mode==='day'?lookupCm(tbl,hCm,0.1):lookupCm(tbl,hCm,0.5);
+
+  // ── LHFA ──────────────────────────────────────────────────────────────────
+  if(!hCm){R.lhfa=miss('height_cm');}
+  else{
+    const row=lookupAge(_T.lhfa[sex]);
+    if(!row){R.lhfa=`No LHFA entry (${mode==='day'?`day ${days}`:`month ${Math.round(months)}`})`;}
+    else{
+      // Measure correction:
+      // Day mode:   read loh field from lenanthro (L=recumbent expected, H=standing expected)
+      // Month mode: L expected for months 0–23, H for months 24–60 (WHO standard transition)
+      const expected=mode==='day'?row.loh:(Math.round(months)<24?'L':'H');
+      let hAdj=hCm,corr=null;
+      if(expected==='L'&&measureUsed==='H'){hAdj=hCm+MEASURE_CORRECTION;corr=`+${MEASURE_CORRECTION}cm (H→L: table expects recumbent)`;}
+      else if(expected==='H'&&measureUsed==='L'){hAdj=hCm-MEASURE_CORRECTION;corr=`-${MEASURE_CORRECTION}cm (L→H: table expects standing)`;}
+      R.height_cm_adj=r2(hAdj);R.measure_correction=corr;
+      setZ('lhfa',lmsZ(hAdj,row.L,row.M,row.S),classify.lhfa);
+    }
+  }
+
+  // ── WFA ───────────────────────────────────────────────────────────────────
+  if(!wKg){R.wfa=miss('weight');}
+  else{
+    const row=lookupAge(_T.wfa[sex]);
+    if(!row)R.wfa=`No WFA entry`;
+    else setZ('wfa',lmsZ(wKg,row.L,row.M,row.S),classify.wfa);
+  }
+
+  // ── WFLH ──────────────────────────────────────────────────────────────────
+  // WFL (<730d / <24m) or WFH (≥730d / ≥24m); raw height (no correction)
+  if(!wKg){R.wflh=miss('weight');}
+  else if(!hCm){R.wflh=miss('height_cm');}
+  else{
+    const useWFL=mode==='day'?days<730:Math.round(months)<24;
+    const pri=useWFL?_T.wfl[sex]:_T.wfh[sex];
+    const sec=useWFL?_T.wfh[sex]:_T.wfl[sex];
+    const step=mode==='day'?0.1:0.5;
+    const row=lookupCm(pri,hCm,step)||lookupCm(sec,hCm,step);
+    if(!row)R.wflh=`Height ${hCm}cm out of WFLH range (45–120cm)`;
+    else setZ('wflh',lmsZ(wKg,row.L,row.M,row.S),classify.wflh);
+  }
+
+  // ── BMI-for-age ───────────────────────────────────────────────────────────
+  // Uses height_cm_adj (with measure correction) for consistency with LHFA
+  if(!wKg||!hCm){R.bmi=miss(!wKg?'weight':'height_cm');}
+  else{
+    const row=lookupAge(_T.bmi[sex]);
+    if(!row){R.bmi=`No BMI entry`;}
+    else{
+      const hB=R.height_cm_adj??hCm;
+      const bmiAdj=wKg/Math.pow(hB/100,2);
+      R.bmi_val=r4(bmiAdj);
+      setZ('bmi',lmsZ(bmiAdj,row.L,row.M,row.S),classify.zscore);
+    }
+  }
+
+  // ── ACFA — MUAC-for-age ───────────────────────────────────────────────────
+  // Day: 91–1826d (3–60m); Month: 3–60m
+  if(!muacMm){R.acfa=miss('muac');}
+  else{
+    const minAge=mode==='day'?91:3;
+    const curAge=mode==='day'?days:Math.round(months);
+    if(curAge<minAge){R.acfa=`Age < 3 months (ACFA starts at day 91)`;}
+    else{
+      const row=lookupAge(_T.acfa[sex]);
+      if(!row)R.acfa=`No ACFA entry`;
+      else setZ('acfa',lmsZ(muacMm/10,row.L,row.M,row.S),classify.zscore);
+    }
+  }
+
+  return R;
+}
+
+// ── Batch ─────────────────────────────────────────────────────────────────────
+function computeBatch(rows,T,defaultMode='day'){
+  return rows.map((r,i)=>{
+    const mode=r.mode||defaultMode;
+    return Object.assign(computeZScores({...r,_T:T,mode}),{_index:i});
+  });
+}
+
+// ── Factory ───────────────────────────────────────────────────────────────────
+/**
+ * Create an anthro instance with both day and month tables pre-loaded.
+ *
+ * @param {object} dayTables    {wfa,lhfa,bmi,acfa,wfl,wfh} from data/day_*.json
+ * @param {object} monthTables  {wfa,lhfa,bmi,acfa,wfl,wfh} from data/month_*.json
+ *
+ * @example — Node.js
+ *   const {createAnthro} = require('./src/anthro.js')
+ *   const fs = require('fs')
+ *   const load = (p,n) => JSON.parse(fs.readFileSync(`data/${p}_${n}.json`))
+ *   const day   = Object.fromEntries(['wfa','lhfa','bmi','acfa','wfl','wfh'].map(n=>[n,load('day',n)]))
+ *   const month = Object.fromEntries(['wfa','lhfa','bmi','acfa','wfl','wfh'].map(n=>[n,load('month',n)]))
+ *   const anthro = createAnthro(day, month)
+ *
+ * @example — compute
+ *   anthro.compute({ mode:'day', sex:'F', dob:'2024-01-15', weight_kg:7, height_cm:64, muac_mm:136 })
+ *   anthro.compute({ mode:'month', sex:'F', age_months:9, weight_kg:7, height_cm:64, muac_mm:136 })
+ */
+function createAnthro(dayTables,monthTables){
+  const required=['wfa','lhfa','bmi','acfa','wfl','wfh'];
+  for(const k of required){
+    if(!dayTables?.[k])   throw new Error(`anthro: missing day table "${k}"`);
+    if(!monthTables?.[k]) throw new Error(`anthro: missing month table "${k}"`);
+  }
+  const Td={},Tm={};
+  for(const[k,t] of Object.entries(dayTables))  {Td[k]={M:t.M,F:t.F};_map(t.M);_map(t.F);}
+  for(const[k,t] of Object.entries(monthTables)){Tm[k]={M:t.M,F:t.F};_map(t.M);_map(t.F);}
+  const getT=mode=>mode==='month'?Tm:Td;
+
+  return{
+    compute:(p)=>computeZScores({...p,_T:getT(p.mode||'day'),mode:p.mode||'day'}),
+    batch:(rows,dm='day')=>computeBatch(rows,getT(dm),dm),
+    classify,lmsZ,ageDays,monthsToDays,
+    meta:{
+      version:'1.1.1',
+      repo:'https://github.com/flame-cai/anthro',
+      tableIndexing:'DAY-INDEXED (default): one LMS row per day, 0–1826d. MONTH-INDEXED: one row per whole month, 0–60m.',
+      tableSource:'WHO igrowup software + R anthro v1.1.0 (WorldHealthOrganization/anthro)',
+      primaryCitation:'WHO MGRS (2006). WHO Child Growth Standards. Geneva: WHO. ISBN 924154693X',
+      formula:'Restricted LMS + SD23 adjustment — WHO (2006) §5.2',
+      precision:'Exact floating-point z-scores (not rounded before classifying, unlike R anthro 2-dp output)',
+      verified:'z-scores match R anthro v1.1.0 to 4dp. 5 non-100% cases due to R anthro output rounding, not library errors.'
+    }
+  };
+}
+
+// ── UMD export ─────────────────────────────────────────────────────────────────
+const _exp={createAnthro,computeZScores,computeBatch,classify,lmsZ,ageDays,monthsToDays};
+if(typeof module!=='undefined'&&module.exports)module.exports=_exp;
+else if(typeof define==='function'&&define.amd)define(()=>_exp);
+else if(typeof globalThis!=='undefined')globalThis.anthro=_exp;