Skip to content

Latest commit

 

History

History
254 lines (201 loc) · 7.67 KB

README.md

File metadata and controls

254 lines (201 loc) · 7.67 KB

Blood Gas Cases

A physiologically-accurate blood gas value generator for medical education. Generate realistic ABG (Arterial Blood Gas) values driven by patient conditions with full clinical interpretation.

🌐 Live Demo

Try it now: https://wmioch.github.io/BloodGasCases/

The web interface runs entirely in your browser - no server required!

✨ Features

  • Physiologically Accurate: Uses Henderson-Hasselbalch equation, compensation rules, alveolar gas equation, and established clinical formulas
  • FiO₂-Responsive Oxygenation: PO₂ realistically changes with FiO₂ based on underlying pathology (A-a gradient, shunt fraction)
  • Multi-Condition Support: Generate complex scenarios with multiple simultaneous conditions (e.g., DKA + opioid overdose)
  • Comprehensive Output: Core ABG, oxygenation, electrolytes, anion gap analysis, and clinical interpretation
  • Step-by-Step Analysis: Shows the working out process for educational purposes
  • Realistic Variability: Adds physiological noise for realistic, non-textbook values
  • Educational: Includes teaching points and clinical implications
  • Cross-Platform: Python library + TypeScript/JavaScript library + Web frontend

🚀 Quick Start

Web Interface (Easiest)

  1. Visit https://wmioch.github.io/BloodGasCases/
  2. Or open bloodgas_generator/frontend/index.html locally in your browser

Python

cd bloodgas_generator/python
pip install -e .
from bloodgas import generate_blood_gas, ClinicalCondition, Severity

# Single condition
result = generate_blood_gas(
    conditions=[ClinicalCondition.DKA],
    condition_severities={ClinicalCondition.DKA: Severity.SEVERE}
)

print(result.summary())
print(result.interpretation.to_text())

# Multiple conditions (e.g., T1DM in DKA who took opioids)
result = generate_blood_gas(
    conditions=[ClinicalCondition.DKA, ClinicalCondition.OPIOID_OVERDOSE],
    condition_severities={
        ClinicalCondition.DKA: Severity.MODERATE,
        ClinicalCondition.OPIOID_OVERDOSE: Severity.SEVERE
    }
)
# Result: Mixed metabolic + respiratory acidosis

TypeScript/JavaScript

cd bloodgas_generator/typescript
npm install
npm run build
import { generateBloodGas, ClinicalCondition, Severity } from 'bloodgas-generator';

const result = generateBloodGas({
  conditions: [ClinicalCondition.DKA, ClinicalCondition.OPIOID_OVERDOSE],
  severities: {
    [ClinicalCondition.DKA]: Severity.MODERATE,
    [ClinicalCondition.OPIOID_OVERDOSE]: Severity.SEVERE,
  },
  patientFactors: { age: 22 },
  fio2: 0.21,
});

console.log(result);

📋 Supported Clinical Conditions

Respiratory

Condition Primary Disorder Key Features
COPD Exacerbation Respiratory Acidosis ↑ A-a gradient, chronic compensation
Asthma Attack Respiratory Alkalosis ↑ A-a gradient, V/Q mismatch
Pulmonary Embolism Respiratory Alkalosis ↑ A-a gradient, dead space
ARDS Respiratory Acidosis High shunt fraction, refractory hypoxemia
Pneumonia Respiratory Alkalosis V/Q mismatch, consolidation
Opioid Overdose Respiratory Acidosis Normal A-a gradient
Hyperventilation Respiratory Alkalosis Normal A-a gradient
Neuromuscular Weakness Respiratory Acidosis Normal A-a gradient (pump failure)

Metabolic Acidosis - High Anion Gap (MUDPILES)

Condition Typical AG Key Features
DKA 20-35 ↑ glucose, ketones, Kussmaul breathing
HHS 12-20 Extreme hyperglycemia, mild acidosis
Lactic Acidosis (Sepsis) 18-30 ↑ lactate, may have lung injury
Lactic Acidosis (Shock) 22-35 Very high lactate, poor prognosis
Renal Failure 14-22 Hyperkalemia common
Toxic Ingestions 25-40 Methanol, ethylene glycol, salicylates
Alcoholic Ketoacidosis 18-28 Low/normal glucose

Metabolic Acidosis - Normal Anion Gap

  • Diarrhea (GI HCO₃⁻ loss)
  • RTA Types 1, 2, 4
  • Saline Infusion (dilutional)

Metabolic Alkalosis

  • Vomiting / NG Suction (HCl loss)
  • Diuretic Use
  • Hypokalemia
  • Hyperaldosteronism

Normal Variants

  • Healthy Adult
  • Pregnancy (chronic respiratory alkalosis)
  • High Altitude

📊 Output Structure

{
  // Core ABG
  ph: 7.12,
  pco2: 52,      // mmHg
  po2: 58,       // mmHg - now responds to FiO2!
  hco3: 16,      // mEq/L
  baseExcess: -12,
  sao2: 86,      // %

  // Oxygenation
  fio2: 0.21,
  pao2Fio2Ratio: 276,
  aaGradient: 35,
  expectedAaGradient: 14,

  // Electrolytes
  sodium: 136,
  potassium: 5.8,
  chloride: 100,
  glucose: 420,

  // Calculated
  anionGap: 20,
  correctedAnionGap: 20,
  deltaGap: 8,
  lactate: 3.2,

  // Interpretation
  interpretation: {
    primaryDisorder: "Mixed Metabolic and Respiratory Acidosis",
    severity: "severe",
    teachingPoints: [...],
    // ...
  }
}

🔬 Physiological Models

Acid-Base

  • Henderson-Hasselbalch: pH = 6.1 + log([HCO₃⁻] / (0.03 × pCO₂))
  • Winter's formula: Expected pCO₂ = 1.5 × [HCO₃⁻] + 8 ± 2
  • Compensation rules for all primary disorders

Oxygenation (NEW: Pathology-Based)

  • Alveolar Gas Equation: PAO₂ = FiO₂(Patm - PH₂O) - PaCO₂/RQ
  • A-a Gradient: Based on underlying lung pathology
  • Shunt Fraction: Models refractory hypoxemia (ARDS, severe PE)
  • O₂-Hb Dissociation: Hill equation with Bohr effect
  • P/F Ratio: For ARDS classification

Anion Gap

  • Standard and albumin-corrected anion gap
  • Delta-delta analysis for mixed disorders

📁 Project Structure

BloodGasCases/
├── bloodgas_generator/
│   ├── frontend/              # Web interface
│   │   ├── index.html
│   │   ├── styles.css
│   │   ├── app.js
│   │   └── bloodgas.bundle.js
│   ├── python/                # Python library
│   │   ├── bloodgas/
│   │   │   ├── models/        # Data models
│   │   │   ├── physiology/    # Calculation engines
│   │   │   ├── scenarios/     # Clinical conditions
│   │   │   ├── generator.py   # Main generator
│   │   │   └── interpretation.py
│   │   └── pyproject.toml
│   ├── typescript/            # TypeScript library
│   │   ├── src/
│   │   │   ├── types.ts
│   │   │   ├── physiology.ts
│   │   │   ├── conditions.ts
│   │   │   └── generator.ts
│   │   └── package.json
│   └── shared/
│       └── schemas/           # JSON schemas
└── README.md

🛠️ Development

Prerequisites

  • Python 3.10+ (for Python library)
  • Node.js 18+ (for TypeScript library)

Building

Python:

cd bloodgas_generator/python
pip install -e ".[dev]"
pytest

TypeScript:

cd bloodgas_generator/typescript
npm install
npm run build
npm run build:bundle  # Creates browser bundle

Deploying the Web Interface

The frontend is a static site that can be deployed to GitHub Pages:

  1. Enable GitHub Pages in repository settings
  2. Set source to bloodgas_generator/frontend folder
  3. Or deploy using GitHub Actions

📝 License

MIT License - For educational purposes only. Not for clinical use.

🤝 Contributing

Contributions welcome! Please ensure physiological accuracy by citing sources for any new conditions or formulas.

⚠️ Disclaimer

This tool is intended for medical education only. The generated values are simulated and should never be used for clinical decision-making. Always interpret real patient ABGs in their full clinical context.