diagcalc 3.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tiago Jacinto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# DIAGCALC
+
+DIAGCALC is a diagnostic test calculator with two interfaces:
+
+- a web app for teaching and interactive use
+- a terminal app with both TUI and plain CLI modes
+
+Both interfaces use the same calculation engine.
+
+## Repository
+
+- GitHub: `https://github.com/tiagojct/diagcalc`
+
+## Features
+
+- confusion matrix input: TP, FP, FN, TN
+- pre-test probability input
+- sensitivity, specificity, PPV, NPV
+- LR+ and LR-
+- positive and negative post-test probability
+- 95% confidence intervals with the Wilson method
+- preset study scenarios
+- Fagan nomogram in the web app
+- TUI, text CLI, and JSON CLI output in the terminal app
+
+## Web App
+
+The web app is static. It does not need a build step.
+
+### Run locally
+
+Open `index.html` directly in a browser, or serve the folder locally:
+
+```bash
+python3 -m http.server 8080
+```
+
+Then open:
+
+```text
+http://localhost:8080
+```
+
+### Use
+
+1. Load a preset scenario, or leave the selector empty.
+2. Enter TP, FP, FN, TN.
+3. Enter pre-test probability.
+4. Click `Calculate results`.
+5. Review the probability bars, result cards, and Fagan nomogram.
+
+## Terminal App
+
+The terminal app requires Node.js 18 or newer.
+
+### Install locally
+
+```bash
+npm install
+```
+
+### TUI mode
+
+```bash
+node bin/diagcalc.js --tui
+```
+
+If you want the short command:
+
+```bash
+npm link
+diag --tui
+```
+
+### CLI mode
+
+List datasets:
+
+```bash
+diag --list-datasets
+```
+
+Run a preset case:
+
+```bash
+diag --dataset hiv_elisa
+```
+
+Run an ad hoc case:
+
+```bash
+diag --tp 42 --fp 8 --fn 3 --tn 120 --pre 15
+```
+
+Get JSON output:
+
+```bash
+diag --dataset ddimer --format json
+```
+
+### TUI controls
+
+- `Tab` / `Ctrl-N`: next panel
+- `Shift-Tab` / `Ctrl-P`: previous panel
+- arrows: move selection
+- type digits directly in the input editor
+- `Backspace`: delete one character from the selected field
+- `Delete` or `Ctrl-U`: clear the selected field
+- `Enter`: open the selected field in prompt mode
+- `n`: start a blank ad hoc case
+- `x`: export current case to plain text
+- `m`: export current case to Markdown
+- `r`: reset current case
+- `q`: quit
+
+## Deployment
+
+### GitHub Pages
+
+This repository includes a GitHub Pages workflow at `.github/workflows/deploy-pages.yml`.
+
+To publish the web app:
+
+1. Push to the `main` branch.
+2. In GitHub, open `Settings -> Pages`.
+3. Set the source to `GitHub Actions`.
+4. The workflow will publish the static site automatically.
+
+### npm
+
+This package is ready for npm publishing.
+
+Publish steps:
+
+```bash
+npm login
+npm publish --access public
+```
+
+After publishing, users can install it with:
+
+```bash
+npm install -g diagcalc
+diag --tui
+```
+
+## Project Structure
+
+- `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
+- `lib/diagcalc-datasets.js` - shared preset datasets
+- `tui/index.js` - terminal UI
+- `bin/diagcalc.js` - CLI and TUI entrypoint
+- `.github/workflows/deploy-pages.yml` - GitHub Pages deployment workflow
+
+## License
+
+MIT

package/bin/diagcalc.js

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+
+const core = require("../lib/diagcalc-core");
+const datasetStore = require("../lib/diagcalc-datasets");
+
+function parseArgs(argv) {
+  const args = {
+    raw: [],
+  };
+
+  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) {
+      args[key] = true;
+      continue;
+    }
+
+    args[key] = next;
+    index += 1;
+  }
+
+  return args;
+}
+
+function printHelp() {
+  process.stdout.write([
+    "DIAGCALC terminal tools",
+    "",
+    "Usage:",
+    "  diag --tui",
+    "  diag --dataset hiv_elisa",
+    "  diag --tp 199 --fp 1 --fn 1 --tn 9799 --pre 2",
+    "  diag --dataset ddimer --pre 18",
+    "  diag --list-datasets",
+    "",
+    "Options:",
+    "  --tui             Launch the interactive terminal UI",
+    "  --dataset <key>   Load a predefined scenario",
+    "  --tp <n>          True positives",
+    "  --fp <n>          False positives",
+    "  --fn <n>          False negatives",
+    "  --tn <n>          True negatives",
+    "  --pre <n>         Pre-test probability (%)",
+    "  --format <type>   Output format: text or json",
+    "  --list-datasets   Show available dataset keys",
+    "  --help            Show this help message",
+    "",
+    "Tip:",
+    "  Run `npm link` in this repo to use `diag` globally.",
+    "",
+  ].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) {
+  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)])),
+  };
+
+  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+
+function printDatasets() {
+  const rows = datasetStore.listDatasets().map((dataset) => `${dataset.key.padEnd(16)} ${dataset.name}`);
+  process.stdout.write(`Available datasets\n\n${rows.join("\n")}\n`);
+}
+
+function buildInputFromArgs(args) {
+  const dataset = args.dataset ? datasetStore.getDataset(args.dataset) : null;
+  if (args.dataset && !dataset) {
+    return {
+      error: `Unknown dataset: ${args.dataset}`,
+    };
+  }
+
+  const merged = {
+    tp: dataset ? dataset.tp : NaN,
+    fp: dataset ? dataset.fp : NaN,
+    fn: dataset ? dataset.fn : NaN,
+    tn: dataset ? dataset.tn : NaN,
+    preTestProb: dataset ? dataset.preTestProb : NaN,
+  };
+
+  if (typeof args.tp === "string") {
+    merged.tp = core.safeParseInt(args.tp);
+  }
+  if (typeof args.fp === "string") {
+    merged.fp = core.safeParseInt(args.fp);
+  }
+  if (typeof args.fn === "string") {
+    merged.fn = core.safeParseInt(args.fn);
+  }
+  if (typeof args.tn === "string") {
+    merged.tn = core.safeParseInt(args.tn);
+  }
+  if (typeof args.pre === "string") {
+    const normalised = core.normaliseDecimal(args.pre);
+    merged.preTestProb = normalised === "" ? NaN : parseFloat(normalised);
+  }
+
+  return {
+    dataset: dataset ? { key: args.dataset, ...dataset } : null,
+    input: merged,
+  };
+}
+
+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)}`
+    : "";
+  return `${metric.label}: ${value}${ci}`;
+}
+
+function printReport(dataset, metrics) {
+  const entries = [
+    metrics.sensitivity,
+    metrics.specificity,
+    metrics.ppv,
+    metrics.npv,
+    metrics.lrPositive,
+    metrics.lrNegative,
+    metrics.preTestProbability,
+    metrics.postTestPositive,
+    metrics.postTestNegative,
+  ];
+
+  const lines = [];
+  lines.push("DIAGCALC");
+  if (dataset) {
+    lines.push(dataset.name);
+  }
+  lines.push("");
+  entries.forEach((metric) => {
+    lines.push(renderMetricLine(metric));
+  });
+  lines.push("");
+  lines.push(`Pre-test bar       [${core.buildProbabilityBar(metrics.preTestProbability.value, 24)}] ${core.formatPercentage(metrics.preTestProbability.value)}`);
+  lines.push(`Post-test (+) bar  [${core.buildProbabilityBar(metrics.postTestPositive.value, 24)}] ${core.formatPercentage(metrics.postTestPositive.value)}`);
+  lines.push(`Post-test (-) bar  [${core.buildProbabilityBar(metrics.postTestNegative.value, 24)}] ${core.formatPercentage(metrics.postTestNegative.value)}`);
+  lines.push("");
+  lines.push(`Interpretation LR+: ${metrics.lrPositive.note}`);
+  lines.push(`Interpretation LR-: ${metrics.lrNegative.note}`);
+  lines.push("");
+
+  process.stdout.write(`${lines.join("\n")}\n`);
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  if (args["list-datasets"]) {
+    printDatasets();
+    return;
+  }
+
+  if (args.tui || (process.argv.length === 2 && process.stdout.isTTY && process.stdin.isTTY)) {
+    const { runTui } = require("../tui/index");
+    runTui();
+    return;
+  }
+
+  if (process.argv.length === 2) {
+    printHelp();
+    return;
+  }
+
+  const built = buildInputFromArgs(args);
+  if (built.error) {
+    process.stderr.write(`${built.error}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const validation = core.validateInputs(built.input);
+  if (!validation.valid) {
+    process.stderr.write(`${validation.message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const metrics = core.calculateMetrics(built.input);
+  const format = typeof args.format === "string" ? args.format.toLowerCase() : "text";
+  if (format === "json") {
+    printJsonReport(built.dataset, built.input, metrics);
+    return;
+  }
+
+  if (format !== "text") {
+    process.stderr.write("Unsupported format. Use --format text or --format json.\n");
+    process.exitCode = 1;
+    return;
+  }
+
+  printReport(built.dataset, metrics);
+}
+
+main();

package/index.html

@@ -0,0 +1,266 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>DIAG-CALC</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600;700;800&display=swap" />
+    <link rel="stylesheet" href="styles.css" />
+  </head>
+  <body>
+    <header class="intro" role="banner">
+      <div class="container">
+        <div class="header-controls">
+          <button id="themeToggle" class="theme-toggle" aria-label="Toggle dark mode" type="button">
+            <span class="theme-icon">◐</span>
+          </button>
+        </div>
+        <p class="tag">Educational tool</p>
+        <h1>DIAGCALC</h1>
+        <p class="lead">
+          Interactive calculator for exploring diagnostic test performance measures
+          and applying Bayesian reasoning in clinical practice.
+        </p>
+        <div class="intro-highlights" role="list">
+          <article class="highlight" role="listitem">
+            <h2>Key measures</h2>
+            <p>Sensitivity, specificity, PPV, NPV, and likelihood ratios with 95%&nbsp;CI.</p>
+          </article>
+          <article class="highlight" role="listitem">
+            <h2>Post-test probability</h2>
+            <p>Convert pre-test probability into positive and negative post-test probability.</p>
+          </article>
+          <article class="highlight" role="listitem">
+            <h2>Guided interpretation</h2>
+            <p>Results explained to support self-directed learning.</p>
+          </article>
+        </div>
+      </div>
+    </header>
+    <main class="container" id="main" role="main">
+      <div class="workspace">
+        <section aria-labelledby="library-title" class="panel panel-library">
+          <div class="panel-heading">
+            <p class="panel-kicker">Library</p>
+            <h2 id="library-title">Load a study scenario</h2>
+          </div>
+          <div class="form-row">
+            <label class="full" for="datasetSelect">Scenario</label>
+            <select id="datasetSelect" class="full" aria-describedby="dataset-help">
+              <option value="">— Select —</option>
+              <optgroup label="Generic scenarios">
+                <option value="screening">Screening programme (low prevalence)</option>
+                <option value="caseControl">Case-control study</option>
+                <option value="clinic">Specialist clinic</option>
+              </optgroup>
+              <optgroup label="Medical literature cases">
+                <option value="ddimer">D-dimer for pulmonary embolism</option>
+                <option value="troponin">High-sensitivity troponin for AMI</option>
+                <option value="mammography">Screening mammography</option>
+                <option value="covid_antigen">Rapid COVID-19 antigen test</option>
+                <option value="hiv_elisa">HIV ELISA</option>
+                <option value="strep_throat">Rapid Streptococcus test</option>
+                <option value="xray_pneumonia">Chest X-ray for pneumonia</option>
+              </optgroup>
+            </select>
+            <p id="dataset-help" class="help-text">
+              Values are filled in automatically and can be adjusted afterwards.
+            </p>
+            <div id="dataset-reference" class="dataset-reference" style="display: none;"></div>
+          </div>
+        </section>
+
+        <section aria-labelledby="form-title" class="panel panel-inputs">
+          <div class="panel-heading">
+            <p class="panel-kicker">Editor</p>
+            <h2 id="form-title">Build the confusion matrix</h2>
+            <p>
+              Use non-negative integers and a pre-test probability under 100%.
+            </p>
+          </div>
+          <form id="inputForm" novalidate>
+            <fieldset class="confusion-matrix">
+              <legend>Confusion matrix</legend>
+              <div class="grid-container" role="group" aria-label="Diagnostic test results">
+                <span class="empty" aria-hidden="true"></span>
+                <span class="grid-header grid-header-pos">Disease +</span>
+                <span class="grid-header grid-header-neg">Disease -</span>
+                <label class="grid-label grid-label-pos" for="tp">Test +</label>
+                <div class="grid-item">
+                  <input type="number" id="tp" inputmode="numeric" min="0" step="1"
+                    placeholder="True positives"
+                    aria-label="True positives (TP): disease present, test positive"
+                    required />
+                </div>
+                <div class="grid-item">
+                  <input type="number" id="fp" inputmode="numeric" min="0" step="1"
+                    placeholder="False positives"
+                    aria-label="False positives (FP): disease absent, test positive"
+                    required />
+                </div>
+                <label class="grid-label grid-label-neg" for="fn">Test -</label>
+                <div class="grid-item">
+                  <input type="number" id="fn" inputmode="numeric" min="0" step="1"
+                    placeholder="False negatives"
+                    aria-label="False negatives (FN): disease present, test negative"
+                    required />
+                </div>
+                <div class="grid-item">
+                  <input type="number" id="tn" inputmode="numeric" min="0" step="1"
+                    placeholder="True negatives"
+                    aria-label="True negatives (TN): disease absent, test negative"
+                    required />
+                </div>
+              </div>
+            </fieldset>
+            <div class="form-row">
+              <label for="preTestProb">Pre-test probability (%)</label>
+              <input
+                class="preTestProb"
+                type="number"
+                id="preTestProb"
+                inputmode="decimal"
+                min="0"
+                max="100"
+                step="0.1"
+                placeholder="e.g. 12.5"
+                required
+              />
+              <p class="help-text">
+                Suggestion: estimate the disease prevalence in the study population or the clinical probability before the test.
+              </p>
+            </div>
+            <div class="form-actions" role="group">
+              <button type="submit">Calculate results</button>
+              <button type="reset" id="resetButton" class="secondary">Clear fields</button>
+            </div>
+            <p id="feedback" class="feedback" role="alert" aria-live="polite"></p>
+          </form>
+        </section>
+
+        <section aria-labelledby="results-title" class="panel panel-results results-section">
+          <div class="panel-heading panel-heading-inline">
+            <div>
+              <p class="panel-kicker">Output</p>
+              <h2 id="results-title">Results</h2>
+              <p class="help-text">
+                Values are shown with 95% confidence intervals calculated using the Wilson method.
+              </p>
+            </div>
+            <div class="results-actions" role="group">
+              <button type="button" id="printButton" class="secondary">Print report</button>
+            </div>
+          </div>
+          <div id="probabilityChart" class="probability-chart" aria-label="Comparison of pre- and post-test probabilities"></div>
+          <div id="faganNomogram" class="fagan-nomogram" style="display: none;">
+            <h3>Fagan Nomogram</h3>
+            <p class="help-text">Graphical representation of the relationship between pre-test probability, likelihood ratio, and post-test probability.</p>
+            <canvas id="faganCanvas" width="600" height="400" aria-label="Fagan nomogram"></canvas>
+          </div>
+          <div id="results" class="results-grid" aria-live="polite"></div>
+        </section>
+      </div>
+
+      <div class="resource-grid">
+      <section aria-labelledby="interpretation-title" class="interpretation panel panel-docs">
+        <h2 id="interpretation-title">Interpretation guide</h2>
+        <details>
+          <summary>Sensitivity and specificity</summary>
+          <p>
+            Quantify the test's ability to correctly identify people with and without the condition. Useful for understanding the intrinsic performance of the test. Learn more at <a href="https://en.wikipedia.org/wiki/Sensitivity_and_specificity" target="_blank" rel="noopener noreferrer">Wikipedia</a>.
+          </p>
+        </details>
+        <details>
+          <summary>Predictive values</summary>
+          <p>
+            Depend on prevalence (pre-test probability). Use them to estimate the probability that a person has or does not have the disease after a positive or negative result. See <a href="https://en.wikipedia.org/wiki/Positive_and_negative_predictive_values" target="_blank" rel="noopener noreferrer">Wikipedia</a> for further reading.
+          </p>
+        </details>
+        <details>
+          <summary>Likelihood ratios</summary>
+          <p>
+            Relate the probability of a result in diseased vs. non-diseased individuals and can be applied directly in Bayes' formula to update the probability of disease. Further reference at <a href="https://en.wikipedia.org/wiki/Likelihood_ratio" target="_blank" rel="noopener noreferrer">Wikipedia</a>.
+          </p>
+        </details>
+        <details>
+          <summary>Post-test probabilities</summary>
+          <p>
+            Result from applying the LR to pre-test odds. They are crucial for clinical decisions such as initiating treatment or ordering additional tests. See also <a href="https://en.wikipedia.org/wiki/Posterior_probability" target="_blank" rel="noopener noreferrer">Wikipedia</a>.
+          </p>
+        </details>
+      </section>
+
+      <section aria-labelledby="references-title" class="references panel panel-docs">
+        <h2 id="references-title">Resources and references</h2>
+        <details>
+          <summary>Supporting literature</summary>
+          <ul class="reference-list">
+            <li>
+              <strong>Akobeng AK.</strong> Understanding diagnostic tests 1-3: sensitivity, specificity, and predictive values. 
+              <em>Acta Paediatr.</em> 2007;96(3):338-341. 
+              <a href="https://doi.org/10.1111/j.1651-2227.2006.00180.x" target="_blank" rel="noopener noreferrer">DOI: 10.1111/j.1651-2227.2006.00180.x</a>
+            </li>
+            <li>
+              <strong>McGee S.</strong> Simplifying likelihood ratios. 
+              <em>J Gen Intern Med.</em> 2002;17(8):646-649. 
+              <a href="https://doi.org/10.1046/j.1525-1497.2002.10750.x" target="_blank" rel="noopener noreferrer">DOI: 10.1046/j.1525-1497.2002.10750.x</a>
+            </li>
+            <li>
+              <strong>Fagan TJ.</strong> Nomogram for Bayes theorem. 
+              <em>N Engl J Med.</em> 1975;293(5):257. 
+              <a href="https://doi.org/10.1056/NEJM197507312930513" target="_blank" rel="noopener noreferrer">DOI: 10.1056/NEJM197507312930513</a>
+            </li>
+          </ul>
+        </details>
+        <details>
+          <summary>Online resources</summary>
+          <ul class="reference-list">
+            <li>
+              <strong>The Centre for Evidence-Based Medicine (CEBM):</strong> 
+              <a href="https://www.cebm.ox.ac.uk/resources/ebm-tools" target="_blank" rel="noopener noreferrer">EBM Tools and Resources</a>
+            </li>
+            <li>
+              <strong>StatPearls:</strong> 
+              <a href="https://www.ncbi.nlm.nih.gov/books/NBK557491/" target="_blank" rel="noopener noreferrer">Sensitivity and Specificity</a>
+            </li>
+            <li>
+              <strong>Deeks JJ, Altman DG.</strong> Diagnostic tests 4: likelihood ratios. 
+              <em>BMJ.</em> 2004;329(7458):168-169. 
+              <a href="https://www.bmj.com/content/329/7458/168" target="_blank" rel="noopener noreferrer">Open access</a>
+            </li>
+          </ul>
+        </details>
+        <details>
+          <summary>Complementary calculators</summary>
+          <ul class="reference-list">
+            <li>
+              <strong>MDCalc:</strong> 
+              <a href="https://www.mdcalc.com/" target="_blank" rel="noopener noreferrer">Medical calculators</a>
+            </li>
+            <li>
+              <strong>ClinCalc:</strong> 
+              <a href="https://clincalc.com/Stats/SampleSize.aspx" target="_blank" rel="noopener noreferrer">Diagnostic Test Calculator</a>
+            </li>
+          </ul>
+        </details>
+      </section>
+      </div>
+    </main>
+    <footer>
+      <p>
+        DIAGCALC is a diagnostic test performance calculator created for educational purposes and training of healthcare students.
+      </p>
+      <p>
+        Any analyses, results and conclusions may not be used, interpreted or generalised beyond this specific context.
+      </p>
+      <p>
+        &copy; 2025 — MIT Licence — Developed by <a href="https://tiagojct.eu">Tiago Jacinto</a>. <a href="mailto:tiagojacinto@med.up.pt">Contact</a>
+      </p>
+    </footer>
+    <script src="lib/diagcalc-datasets.js"></script>
+    <script src="lib/diagcalc-core.js"></script>
+    <script src="script.js"></script>
+  </body>
+</html>