diagcalc 3.2.3 → 5.0.0

package/README.md

@@ -10,7 +10,7 @@ Both interfaces use the same calculation engine.
 ## Repository
 
 - GitHub: `https://github.com/tiagojct/diagcalc`
-- Web app: `https://diagcalc.tiagojct.eu/`
+- Web app: `https://diagcalc.tiagojacinto.eu/`
 - npm package: `https://www.npmjs.com/package/diagcalc`
 
 ## Description
@@ -47,11 +47,28 @@ The web and terminal interfaces both follow that workflow.
 - sensitivity, specificity, PPV, NPV
 - LR+ and LR-
 - positive and negative post-test probability
-- 95% confidence intervals with the Wilson method
-- preset study scenarios
+- Wilson 95% intervals for proportions and log-normal intervals for likelihood ratios and DOR
+- illustrative teaching scenarios with explicit provenance
 - Fagan nomogram in the web app
 - TUI, text CLI, and JSON CLI output in the terminal app
 
+## Case Studies
+
+All current presets are illustrative teaching scenarios. Medical references provide background; their confusion-matrix counts have not been verified against retained source-table extractions. They must not be presented as published study estimates.
+
+- `screening` - low-prevalence population screening workflow
+- `caseControl` - balanced case-control teaching example
+- `clinic` - specialist clinic setting with intermediate prevalence
+- `ddimer` - D-dimer for pulmonary embolism rule-out
+- `troponin` - high-sensitivity troponin for acute myocardial infarction
+- `mammography` - screening mammography in a low-prevalence setting
+- `covid_antigen` - rapid antigen testing for COVID-19
+- `hiv_elisa` - fourth-generation HIV ELISA screening
+- `strep_throat` - rapid antigen testing for streptococcal pharyngitis
+- `xray_pneumonia` - chest X-ray for community-acquired pneumonia
+
+These cases are included to support teaching across different prevalence settings, screening vs. confirmation logic, and Bayesian interpretation of test results.
+
 ## Web App
 
 The web app is static. It does not need a build step.
@@ -82,7 +99,7 @@ http://localhost:8080
 
 ## Terminal App
 
-The terminal app requires Node.js 18 or newer.
+The terminal app requires Node.js 22 or newer.
 
 It is intended for keyboard-first use, quick calculations, reproducible terminal workflows, and scripting.
 
@@ -148,6 +165,38 @@ The CLI is useful when you want a one-shot calculation or when you want to integ
 - `r`: reset current case
 - `q`: quit
 
+## Validation and reproducibility
+
+Counts must be non-negative safe integers, including their total. Both disease cohorts must be present. Pre-test probability accepts complete dot/comma decimal strings from 0 through 100 inclusive. Impossible conditioning events remain undefined and display an em dash; infinite ratios display infinity. Chaining retains full precision and assumes tests are conditionally independent given disease status.
+
+The browser's history retains the inputs, continuity correction, engine version and origin for each calculation. Editing a preset marks it customised and invalidates previous results. Storage restrictions fall back to session memory; they do not prevent calculations. Older history entries are explicitly marked as recalculated legacy cases because their original correction settings were not recorded.
+
+### Version 5 JSON compatibility
+
+`--format json` now emits schema version 2. Every metric and CI endpoint encodes exceptional numbers explicitly:
+
+```json
+{"value": null, "status": "infinite", "ci": null}
+```
+
+Statuses are `finite`, `infinite`, `negative-infinite`, and `undefined`; finite values are unrounded. Consumers of the previous JSON format must migrate. Outputs include engine version, inputs, correction options and provenance. TUI text/Markdown exports append a reproducible JSON snapshot and refuse to overwrite existing paths.
+
+ROC rows must represent the same cohorts with monotonic operating points and consistently ordered cutoffs. Synthetic points and edited synthetic points remain labelled illustrative, including their AUC. Decision thresholds are unavailable for uninformative or inverted tests. Nomogram lines outside its labelled axis range are explicitly omitted; numeric probabilities remain available.
+
+## Development checks
+
+```bash
+npm ci
+npx playwright install chromium firefox webkit
+npm run check
+```
+
+`check` runs JavaScript type checking, engine/CLI/TUI/package tests and browser tests in Chromium, Firefox and WebKit. Browser tests prepare the actual static deployment bundle automatically. Python 3 and a pseudo-terminal are required for the real terminal test on Unix; that test is skipped on Windows. There are no runtime browser dependencies or compilation step.
+
+Pull requests run checks on Node 22 and 24 and all three browser engines. Main-branch deployment requires both verification jobs. `npm run prepare:site` copies only browser assets and `CNAME` into `public/`; package tests also extract and execute the actual npm archive outside the checkout.
+
+See [lib/README.md](lib/README.md) for API contracts and [docs/PROVENANCE.md](docs/PROVENANCE.md) for dataset evidence requirements.
+
 ## Deployment
 
 ### GitHub Pages
@@ -187,8 +236,13 @@ Package page:
 
 - `index.html` - web app markup
 - `styles.css` - web app styles
-- `script.js` - web app logic and Fagan nomogram rendering
-- `lib/diagcalc-core.js` - shared calculations and validation
+- `script.js` - web state and event handling
+- `web/` - result rendering and scheduled DPR-aware charts
+- `lib/diagcalc-core.js` - shared numeric calculations and validation
+- `lib/diagcalc-presentation.js` - English/Portuguese metric labels and interpretation
+- `lib/diagcalc-case.js` - versioned snapshots and safe exceptional-number encoding
+- `lib/diagcalc-storage.js` - resilient browser preferences and session fallback
+- `lib/diagcalc-geometry.js` - independently testable nomogram geometry
 - `lib/diagcalc-datasets.js` - shared preset datasets
 - `tui/index.js` - terminal UI
 - `bin/diagcalc.js` - CLI and TUI entrypoint

package/bin/diagcalc.js

@@ -2,32 +2,32 @@
 
 const core = require("../lib/diagcalc-core");
 const datasetStore = require("../lib/diagcalc-datasets");
+const pkg = require("../package.json");
 
-function parseArgs(argv) {
-  const args = {
-    raw: [],
-  };
+const caseStore = require("../lib/diagcalc-case");
 
+function parseArgs(argv) {
+  const flags = new Set(["help", "tui", "chain", "list-datasets"]);
+  const values = new Set(["dataset", "tp", "fp", "fn", "tn", "pre", "tp2", "fp2", "fn2", "tn2", "chain-from", "format", "continuity"]);
+  const args = {};
   for (let index = 0; index < argv.length; index += 1) {
     const token = argv[index];
-    if (!token.startsWith("--")) {
-      args.raw.push(token);
-      continue;
-    }
-
-    const key = token.slice(2);
-    const next = argv[index + 1];
-    const isFlag = !next || next.startsWith("--");
-
-    if (isFlag) {
+    if (!token.startsWith("--")) return { error: `Unexpected argument: ${token}` };
+    const [key, ...parts] = token.slice(2).split("=");
+    if (!flags.has(key) && !values.has(key)) return { error: `Unknown option: --${key}` };
+    if (Object.prototype.hasOwnProperty.call(args, key)) return { error: `Duplicate option: --${key}` };
+    if (flags.has(key)) {
+      if (parts.length) return { error: `--${key} does not take a value.` };
       args[key] = true;
       continue;
     }
-
-    args[key] = next;
-    index += 1;
+    const value = parts.length ? parts.join("=") : argv[++index];
+    if (value === undefined || value === "" || value.startsWith("--")) return { error: `Missing value for --${key}.` };
+    args[key] = value;
+  }
+  if (!args.chain && ["tp2", "fp2", "fn2", "tn2", "chain-from"].some((key) => key in args)) {
+    return { error: "Second-test options require --chain." };
   }
-
   return args;
 }
 
@@ -40,6 +40,7 @@ function printHelp() {
     "  diag --dataset hiv_elisa",
     "  diag --tp 199 --fp 1 --fn 1 --tn 9799 --pre 2",
     "  diag --dataset ddimer --pre 18",
+    "  diag --dataset ddimer --chain --tp2 90 --fp2 10 --fn2 10 --tn2 90",
     "  diag --list-datasets",
     "",
     "Options:",
@@ -50,7 +51,11 @@ function printHelp() {
     "  --fn <n>          False negatives",
     "  --tn <n>          True negatives",
     "  --pre <n>         Pre-test probability (%)",
+    "  --chain           Compute a second test using test 1's post-test as pre-test",
+    "  --tp2 --fp2 --fn2 --tn2  Second test's confusion matrix (with --chain)",
+    "  --chain-from <r>  positive (default) | negative — which test 1 result to follow",
     "  --format <type>   Output format: text or json",
+    "  --continuity <m>  Continuity correction for LR/DOR CIs: auto (default), always, never",
     "  --list-datasets   Show available dataset keys",
     "  --help            Show this help message",
     "",
@@ -60,24 +65,32 @@ function printHelp() {
   ].join("\n"));
 }
 
-function serialiseMetric(metric) {
-  return {
-    label: metric.label,
-    value: metric.value,
-    formatted: core.formatValue(metric.value, metric.formatter),
-    ci: metric.ci || null,
-    note: metric.note || null,
-  };
-}
-
-function printJsonReport(dataset, input, metrics) {
+function printJsonReport(dataset, input, metrics, chained, warnings, continuity) {
+  const modified = Boolean(dataset && ["tp", "fp", "fn", "tn", "preTestProb"].some((key) => input[key] !== dataset[key]));
+  const snapshot = caseStore.createSnapshot(input, { continuityCorrection: continuity }, {
+    label: dataset ? `${modified ? "Customised: " : ""}${dataset.name}` : "Ad hoc case",
+    datasetKey: dataset ? dataset.key : null,
+    modified,
+    provenance: dataset ? dataset.provenance : null,
+  });
   const payload = {
-    case: dataset ? dataset.name : "Ad hoc case",
-    datasetKey: dataset ? dataset.key || null : null,
-    input,
-    metrics: Object.fromEntries(Object.entries(metrics).map(([key, metric]) => [key, serialiseMetric(metric)])),
+    ...snapshot,
+    engine: { name: "diagcalc", version: pkg.version, generatedAt: snapshot.savedAt, ciMethods: caseStore.methodMetadata(snapshot.options) },
+    case: snapshot.label,
+    warnings,
+    metrics: Object.fromEntries(Object.entries(metrics).map(([key, metric]) => [key, {
+      ...snapshot.metrics[key], label: metric.label,
+      formatted: core.formatValue(metric.value, metric.formatter), note: metric.note,
+    }])),
   };
-
+  if (chained) {
+    payload.chained = {
+      ...caseStore.createSnapshot(chained.input, { continuityCorrection: continuity }, { label: "Chained second test" }),
+      from: chained.from,
+      assumption: "Test results are conditionally independent given disease status.",
+      warnings: core.buildBiasWarnings(chained.input),
+    };
+  }
   process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
 }
 
@@ -115,8 +128,7 @@ function buildInputFromArgs(args) {
     merged.tn = core.safeParseInt(args.tn);
   }
   if (typeof args.pre === "string") {
-    const normalised = core.normaliseDecimal(args.pre);
-    merged.preTestProb = normalised === "" ? NaN : parseFloat(normalised);
+    merged.preTestProb = core.parseProbability(args.pre);
   }
 
   return {
@@ -128,17 +140,19 @@ function buildInputFromArgs(args) {
 function renderMetricLine(metric) {
   const value = core.formatValue(metric.value, metric.formatter);
   const ci = metric.ci
-    ? ` | 95% CI ${core.formatPercentage(metric.ci.lower)} to ${core.formatPercentage(metric.ci.upper)}`
+    ? ` | 95% CI ${core.formatValue(metric.ci.lower, metric.formatter)} to ${core.formatValue(metric.ci.upper, metric.formatter)}`
     : "";
   return `${metric.label}: ${value}${ci}`;
 }
 
-function printReport(dataset, metrics) {
+function printReport(dataset, metrics, warnings) {
   const entries = [
     metrics.sensitivity,
     metrics.specificity,
     metrics.ppv,
     metrics.npv,
+    metrics.dor,
+    metrics.numberNeededToScreen,
     metrics.lrPositive,
     metrics.lrNegative,
     metrics.preTestProbability,
@@ -152,6 +166,13 @@ function printReport(dataset, metrics) {
     lines.push(dataset.name);
   }
   lines.push("");
+  if (Array.isArray(warnings) && warnings.length > 0) {
+    lines.push("Heads up:");
+    for (const w of warnings) {
+      lines.push(`  - ${w}`);
+    }
+    lines.push("");
+  }
   entries.forEach((metric) => {
     lines.push(renderMetricLine(metric));
   });
@@ -169,6 +190,11 @@ function printReport(dataset, metrics) {
 
 function main() {
   const args = parseArgs(process.argv.slice(2));
+  if (args.error) {
+    process.stderr.write(`${args.error}\n`);
+    process.exitCode = 1;
+    return;
+  }
 
   if (args.help) {
     printHelp();
@@ -205,10 +231,34 @@ function main() {
     return;
   }
 
-  const metrics = core.calculateMetrics(built.input);
+  const continuity = typeof args.continuity === "string" ? args.continuity.toLowerCase() : "auto";
+  if (!["auto", "always", "never"].includes(continuity)) {
+    process.stderr.write(`Invalid --continuity value. Use auto, always, or never.\n`);
+    process.exitCode = 1;
+    return;
+  }
+  const metrics = core.calculateMetrics(built.input, { continuityCorrection: continuity });
+  if (args.format !== undefined && typeof args.format !== "string") {
+    process.stderr.write("Missing value for --format. Use --format text or --format json.\n");
+    process.exitCode = 1;
+    return;
+  }
   const format = typeof args.format === "string" ? args.format.toLowerCase() : "text";
+
+  let chained = null;
+  if (args.chain) {
+    chained = buildChainedTest(args, metrics, continuity);
+    if (chained.error) {
+      process.stderr.write(`${chained.error}\n`);
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  const warnings = [...core.buildBiasWarnings(built.input), ...datasetStore.buildDatasetWarnings(built.dataset)];
+
   if (format === "json") {
-    printJsonReport(built.dataset, built.input, metrics);
+    printJsonReport(built.dataset, built.input, metrics, chained, warnings, continuity);
     return;
   }
 
@@ -218,7 +268,63 @@ function main() {
     return;
   }
 
-  printReport(built.dataset, metrics);
+  const modified = built.dataset && ["tp", "fp", "fn", "tn", "preTestProb"].some((key) => built.input[key] !== built.dataset[key]);
+  printReport(built.dataset ? { ...built.dataset, name: `${modified ? "Customised: " : ""}${built.dataset.name}` } : null, metrics, warnings);
+  process.stdout.write(`Engine ${pkg.version}; continuity correction: ${continuity}.\n`);
+  if (chained) {
+    printChainedReport(chained);
+  }
+}
+
+function buildChainedTest(args, firstMetrics, continuity) {
+  const from = typeof args["chain-from"] === "string" ? args["chain-from"].toLowerCase() : "positive";
+  if (from !== "positive" && from !== "negative") {
+    return { error: "Invalid --chain-from. Use 'positive' or 'negative'." };
+  }
+  const sourceProb = from === "negative" ? firstMetrics.postTestNegative.value : firstMetrics.postTestPositive.value;
+  if (!Number.isFinite(sourceProb)) {
+    return { error: "Test 1's post-test probability is not finite; cannot chain." };
+  }
+  const preTestProb = core.chainedPreTestProbability(sourceProb);
+
+  const input = {
+    tp: typeof args.tp2 === "string" ? core.safeParseInt(args.tp2) : NaN,
+    fp: typeof args.fp2 === "string" ? core.safeParseInt(args.fp2) : NaN,
+    fn: typeof args.fn2 === "string" ? core.safeParseInt(args.fn2) : NaN,
+    tn: typeof args.tn2 === "string" ? core.safeParseInt(args.tn2) : NaN,
+    preTestProb,
+  };
+  const validation = core.validateInputs(input);
+  if (!validation.valid) {
+    return { error: `Test 2 validation failed: ${validation.message}` };
+  }
+  return {
+    from,
+    input,
+    metrics: core.calculateMetrics(input, { continuityCorrection: continuity }),
+  };
+}
+
+function printChainedReport(chained) {
+  process.stdout.write(`\n— Chained second test (following test 1's ${chained.from} result) —\n`);
+  process.stdout.write("Assumption: results are conditionally independent given disease status.\n");
+  process.stdout.write(`Test 2 pre-test probability: ${core.formatPercentage(chained.input.preTestProb / 100)}\n\n`);
+  const entries = [
+    chained.metrics.sensitivity,
+    chained.metrics.specificity,
+    chained.metrics.ppv,
+    chained.metrics.npv,
+    chained.metrics.dor,
+    chained.metrics.numberNeededToScreen,
+    chained.metrics.lrPositive,
+    chained.metrics.lrNegative,
+    chained.metrics.postTestPositive,
+    chained.metrics.postTestNegative,
+  ];
+  entries.forEach((metric) => {
+    process.stdout.write(`${renderMetricLine(metric)}\n`);
+  });
+  process.stdout.write("\n");
 }
 
 main();

package/docs/PROVENANCE.md

@@ -0,0 +1,17 @@
+# Dataset provenance
+
+All existing presets are classified `illustrative`. The repository does not retain a source table or extraction record establishing that the TP/FP/FN/TN values came from the cited medical papers. Keeping a DOI or a reference review date does not establish numerical provenance. The reference dates are therefore named `referenceLastReviewed`.
+
+Each frozen preset has a `provenance` record: `kind`, `sourceLocation`, `extraction`, `threshold`, `referenceStandard`, `outcome`, `population`, `reviewStatus`, and `note`. Null fields mean evidence has not been retained. Browser warnings, terminal warnings and JSON snapshots carry this distinction; customised cases retain their original source identity and mark their counts modified.
+
+To add a verified empirical case, retain an extraction file in this directory recording:
+
+1. The exact paper version/DOI and table, page or supplementary location.
+2. Population, exclusions, sample size, disease outcome and reference standard.
+3. Test assay, units, cutoff and positive direction.
+4. The four counts, their derivation and reconciliation against the source totals. Separate thresholds/cohorts must never be merged into a single ROC series.
+5. Reviewer, review date and an independent check of all four cells.
+
+Link that extraction from `provenance.extraction`, fill the remaining fields, add a regression fixture and update warnings only when the numerical claim is substantiated. No such independent extraction review was performed for the version 5 changes.
+
+Simulated ROC points carry `simulated` provenance; editing them changes it to `edited-simulated`, preserving the qualification on AUC. A reference citation cannot convert a simulated point into an observed threshold.