PhysioHelper is a personal collection of utility functions designed to save me from rewriting the same calculations across multiple research projects. These functions automate the derivation of common physiological parameters in critical care and respiratory medicine studies.
This package is a tool for my own workflow—nothing fancy, just practical functions that make data analysis more efficient and reproducible.
"Write once, use everywhere" — and avoid copy-paste errors along the way.
Special thanks to Dr. Patrick D. Collins, MD for the initial adaptation of these functions and for the foundational script development that inspired this package.
Install the development version directly from GitHub:
# Install devtools if you haven't already
install.packages("devtools")
# Install PhysioHelper from GitHub
devtools::install_github("Kernel236/PhysioHelper")All functions work by taking a data frame, calculating a derived variable, and adding it as a new column. Every function includes robust error checking with clear messages.
NOTE: Column names are passed as strings (with quotes).
Calculate Predicted Body Weight (PBW) using the Devine formula.
Formula:
- Males: PBW = 50 + 0.91 × (heightcm - 152.4)
- Females: PBW = 45.5 + 0.91 × (heightcm - 152.4)
patients <- data.frame(id = 1:3, "c"("M", "F", "M"), "c"(1.75, 1.62, 1.80))
patients <- add_pbw_devine(patients, "sex", "height_m")Reference: Devine BJ. Drug Intell Clin Pharm. 1974;8:650-655.
Normalize tidal volume to predicted body weight.
Target: 6-8 mL/kg for lung-protective ventilation
vent_data <- add_vt_per_pbw(vent_data, "vt_ml", "pbw_kg")add_minute_ventilation(data, tidal_volume_ml, respiratory_rate, new_col = "minute_ventilation_L_min")
Calculate minute ventilation.
Formula: V̇E = VT × RR
Normal range: 5-8 L/min
vent_data <- add_minute_ventilation(vent_data, "vt_ml", "rr")add_static_compliance(data, tidal_volume_ml, plateau_pressure, peep, new_col = "static_compliance_ml_cmH2O")
Calculate static respiratory compliance.
Formula: Cstat = VT / (Pplat - PEEP)
Normal: 50-100 mL/cmH₂O
ARDS: < 40 mL/cmH₂O
vent_data <- add_static_compliance(vent_data, "vt", "pplat", "peep")Calculate driving pressure.
Formula: ΔP = Pplat - PEEP
Target in ARDS: < 15 cmH₂O
vent_data <- add_driving_pressure(vent_data, "pplat", "peep")Reference: Amato MBP et al. N Engl J Med. 2015;372(8):747-755.
Convert PaCO₂ from kPa to mmHg (1 kPa = 7.5006 mmHg).
Normal range: 35-45 mmHg (4.7-6.0 kPa)
abg_data <- add_paco2_mmhg(abg_data, paco2_kpa = paco2_kpa)Calculate alveolar ventilation.
Formula: V̇A = (0.863 × V̇CO2) / PaCO2
Where V̇CO2 is in mL/min and PaCO2 is in mmHg.
gas_data <- add_alveolar_ventilation(gas_data, vco2_ml_min = vco2, paco2_mmHg = paco2)add_dead_space_fraction(data, minute_ventilation_L_min, alveolar_ventilation_L_min, new_col = "dead_space_fraction")
Calculate physiological dead space.
Formula: VD/VT = 1 - (V̇A / V̇E)
Normal: 0.20-0.35 (20-35%)
ARDS: > 0.60 (60%)
vent_data <- add_dead_space_fraction(vent_data, "ve", "va")add_dead_space_volume(data, tidal_volume_ml, vco2_ml_min, paco2_mmHg, respiratory_rate, new_col = "dead_space_volume_ml")
Calculate volumetric dead space using CO₂ production.
Formula: VD = VT - (V̇CO2 / (PaCO2 × RR × 0.863))
Normal: ~150 mL (anatomical dead space)
vent_data <- add_dead_space_volume(vent_data, "vt", "vco2", "paco2", "rr")Calculate ventilatory efficiency.
Formula: V̇E/V̇CO2 = Minute Ventilation (L/min) / CO2 Production (L/min)
Normal: 25-35 (higher = worse efficiency)
vent_data <- add_ve_vco2_ratio(vent_data, minute_ventilation_L_min = ve, vco2_ml_min = vco2)add_arterial_oxygen_content(data, hemoglobin_g_dL, sao2_fraction, pao2_mmHg, new_col = "cao2_ml_per_dL")
Calculate arterial oxygen content.
Formula: CaO2 = (1.34 × Hb × SaO2) + (0.003 × PaO2)
Where:
- 1.34 = Hüfner constant (mL O2 per g Hb)
- 0.003 = dissolved O2 coefficient
Normal: 16-22 mL O2/dL
abg_data <- add_arterial_oxygen_content(abg_data, hemoglobin_g_dL = hb,
sao2_fraction = sao2, pao2_mmHg = pao2)add_venous_oxygen_content(data, hemoglobin_g_dL, scvo2_fraction, pvO2_mmHg, new_col = "cvo2_ml_per_dL")
Calculate mixed venous oxygen content.
Formula: CvO2 = (1.34 × Hb × ScvO2) + (0.003 × PvO2)
Normal: 12-15 mL O2/dL
cvl_data <- add_venous_oxygen_content(cvl_data, hemoglobin_g_dL = hb,
scvo2_fraction = scvo2, pvO2_mmHg = pvo2)Calculate ideal capillary oxygen content (assuming 100% saturation).
Formula: CcO2 = (1.34 × Hb × 1.00) + (0.003 × PaO2)
abg_data <- add_capillary_oxygen_content(abg_data, hemoglobin_g_dL = hb, pao2_mmHg = pao2)add_shunt_fraction(data, cao2_ml_per_dL, cvo2_ml_per_dL, cco2_ml_per_dL, new_col = "shunt_fraction")
Calculate pulmonary shunt using the Riley method.
Formula: Qs/Qt = (CcO2 - CaO2) / (CcO2 - CvO2)
Normal: < 10%
Pathological: > 15%
ARDS: > 30%
gas_data <- add_shunt_fraction(gas_data, cao2_ml_per_dL = cao2,
cvo2_ml_per_dL = cvo2, cco2_ml_per_dL = cco2)Reference: Riley RL, Cournand A. J Appl Physiol. 1949;1(12):825-847.
Calculate PaO₂/FiO₂ ratio for ARDS diagnosis.
Formula: P/F = PaO2 / FiO2
ARDS Severity (Berlin Criteria):
- Mild: 200-300 mmHg
- Moderate: 100-200 mmHg
- Severe: < 100 mmHg
Normal (room air): ~400-500 mmHg
abg_data <- add_pf_ratio(abg_data, pao2_mmHg = pao2, fio2_fraction = fio2)Reference: ARDS Definition Task Force. JAMA. 2012;307(23):2526-2533.
add_aa_gradient(data, fio2_fraction, pao2_mmHg, paco2_mmHg, barometric_pressure_mmHg = 760, new_col = "aa_gradient_mmHg")
Calculate alveolar-arterial oxygen gradient.
Alveolar Gas Equation:
PAO2 = (FiO2 × [Patm - 47]) - (PaCO2 / 0.8)
A-a Gradient:
A-a = PAO2 - PaO2
Normal: 5-10 mmHg (room air, young adults)
Age-adjusted: (Age/4) + 4 mmHg
abg_data <- add_aa_gradient(abg_data, "fio2", "pao2", "paco2")Helper functions to create mathematical expression labels for ggplot2:
Generate mathematical expressions for plot labels:
library(ggplot2)
# Use in ggplot
ggplot(data, aes(x = time, y = pf_ratio)) +
geom_line() +
ylab(physio_label("pf_ratio")) # Shows: PaO₂/FiO₂ (mmHg)
# Available parameters:
physio_label("shunt_fraction") # Qs/Qt
physio_label("cao2") # CaO₂ (mL/dL)
physio_label("compliance") # Cstat (mL/cmH₂O)
physio_label("dead_space") # VD/VT
physio_label("ve_vco2") # V̇E/V̇CO₂Get formula expressions for annotations:
# Add formula to plot
ggplot(data, aes(x = hb, y = cao2)) +
geom_point() +
annotate("text", x = 10, y = 15,
label = physio_formula("cao2"), parse = TRUE)
# Shows: CaO₂ = (1.34 × Hb × SaO₂) + (0.003 × PaO₂)library(PhysioHelper)
library(dplyr)
# Sample ICU patient data
patients <- data.frame(
id = 1:3,
sex = c("M", "F", "M"),
height_m = c(1.75, 1.62, 1.80),
# Ventilator data
vt_ml = c(450, 400, 500),
rr = c(14, 16, 12),
pplat = c(25, 28, 24),
peep = c(10, 10, 8),
fio2 = c(0.60, 0.50, 0.40),
# Metabolic data
vco2 = c(200, 180, 220),
# Blood gas data
paco2_kpa = c(5.3, 5.8, 5.0),
pao2 = c(80, 95, 120),
sao2 = c(0.94, 0.96, 0.98),
# Central line data
hb = c(12, 10, 14),
scvo2 = c(0.65, 0.60, 0.70),
pvo2 = c(38, 35, 42)
)
# Calculate ALL derived physiological parameters in one pipeline
results <- patients %>%
# Body weight
add_pbw_devine(sex = sex, "height_m") %>%
# Respiratory mechanics
add_vt_per_pbw(tidal_volume_ml = vt_ml, "pbw_kg") %>%
add_minute_ventilation(tidal_volume_ml = vt_ml, "rr") %>%
add_static_compliance(tidal_volume_ml = vt_ml,
plateau_pressure = pplat, "peep") %>%
add_driving_pressure(plateau_pressure = pplat, "peep") %>%
# Gas exchange
add_paco2_mmhg(paco2_kpa = paco2_kpa) %>%
add_alveolar_ventilation(vco2_ml_min = vco2, paco2_mmHg = paco2_mmHg) %>%
add_dead_space_fraction(minute_ventilation_L_min = minute_ventilation_L_min,
alveolar_ventilation_L_min = alveolar_ventilation_L_min) %>%
add_ve_vco2_ratio(minute_ventilation_L_min = minute_ventilation_L_min,
vco2_ml_min = vco2) %>%
# Oxygenation indices
add_pf_ratio(pao2_mmHg = pao2, fio2_fraction = fio2) %>%
add_aa_gradient(fio2_fraction = fio2, pao2_mmHg = pao2, paco2_mmHg = paco2_mmHg) %>%
# Oxygen transport
add_arterial_oxygen_content(hemoglobin_g_dL = hb, sao2_fraction = sao2, pao2_mmHg = pao2) %>%
add_venous_oxygen_content(hemoglobin_g_dL = hb, scvo2_fraction = scvo2, pvO2_mmHg = pvo2) %>%
add_capillary_oxygen_content(hemoglobin_g_dL = hb, pao2_mmHg = pao2) %>%
add_shunt_fraction(cao2_ml_per_dL = cao2_ml_per_dL,
cvo2_ml_per_dL = cvo2_ml_per_dL,
cco2_ml_per_dL = cco2_ml_per_dL)
# View comprehensive physiological profile
print(results)This gives you a complete physiological snapshot including:
- Lung-protective ventilation metrics (VT/PBW, ΔP, Cstat)
- Gas exchange efficiency (VD/VT, V̇E/V̇CO₂)
- Oxygenation severity (P/F ratio, A-a gradient)
- Intrapulmonary shunt (Qs/Qt)
MIT License - see LICENSE file for details.