Pulmonary Function Test Interpretation per ERS/ATS 2022

Computes predicted values and lower/upper limits of normal for pulmonary function tests according to American Thoracic Society ('ATS') and European Respiratory Society ('ERS') reference standards. Supports spirometry (Global Lung Function Initiative 'GLI' 2012, Quanjer et al. (2012) ; and the race-neutral 'GLI' 2022 / 'GLI Global' equations, Bowerman et al. (2023) ), static lung volumes ('GLI' 2021, Hall et al. (2021) ), and the carbon monoxide transfer factor / diffusion capacity ('GLI' 2017, Stanojevic et al. (2017) , including the 2020 author correction ). Also assigns interpretive pattern labels (Normal, Non-specific, Obstructed, Restricted, Mixed) from spirometry and lung-volume measurements following the 'ERS'/'ATS' 2022 interpretation algorithm, Stanojevic et al. (2022) .

pft

Compute ATS / ERS-compliant reference values, lower/upper limits of normal, and interpretive pattern classifications for pulmonary function tests in R.

Status

Research and education use only. This package is not a regulated medical device. The reference equations it implements come from published clinical standards, but the package itself has not been validated for diagnostic decision-making. All outputs require interpretation by a qualified clinician.

Installation

# install.packages("remotes")
remotes::install_github("overdodactyl/pft")

What it does

pft implements the Stanojevic 2022 ERS/ATS interpretive standard for pulmonary function tests. Reference values come from the GLI family of equations (GLI 2012 and GLI Global 2022 spirometry, GLI 2021 static lung volumes, GLI 2017 TLCO with the 2020 author correction). On top of those, the package computes z-scores and percent predicted, ATS pattern classification, severity grading, bronchodilator response, PRISm, conditional change scores and longitudinal slopes, GLI 2012 vs GLI Global 2022 reclassification, the Hughes & Pride diffusion category, lung age, and ggplot2-based single-patient and cohort figures.

Reference value functions

Each reference function emits <measure>_pred, <measure>_lln, <measure>_uln. If a <measure>_measured column is also present, <measure>_zscore and <measure>_pctpred are appended automatically.

Spirometry outputs additionally carry a four-digit GLI-year suffix (e.g. fev1_pred_2012, fev1_pred_2022) so a single result frame can hold the GLI 2012 and GLI Global 2022 columns side-by-side, and so the suffix isn't ambiguous when the default year changes in a future release. Lung-volume (Hall 2021) and diffusion (GLI 2017) outputs stay unsuffixed because only one standard currently ships for each — the same suffixing convention will be adopted there if competing standards emerge.

Interpretation functions

All functions take a data frame and return a data frame, so they compose with dplyr pipelines.

Quick start

library(pft)
library(dplyr)

# Demographics for two patients
patients <- data.frame(
  sex    = c("M", "F"),
  age    = c(45,  60),
  height = c(178, 165),
  race   = c("Caucasian", "AfrAm")
)

# Compute spirometry, lung volume, and diffusion reference values
patients |>
  pft_spirometry(year = 2022) |>
  pft_volumes() |>
  pft_diffusion(SI.units = TRUE)

# Add measured values to also get z-scores and percent predicted
patients$fev1_measured <- c(3.2, 2.1)
patients$fvc_measured  <- c(4.5, 2.8)
pft_spirometry(patients, year = 2022)
# -> adds fev1_pred_2022, fev1_lln_2022, fev1_uln_2022,
#         fev1_zscore_2022, fev1_pctpred_2022, and equivalents for fvc.

To classify a patient's pattern, attach their measured values plus LLNs and pipe through pft_classify():

patient <- data.frame(
  fev1 = 2.5,  fev1_lln = 3.0,
  fvc  = 3.8,  fvc_lln  = 3.5,
  fev1fvc = 0.66, fev1fvc_lln = 0.70,
  tlc = 6.2,   tlc_lln = 5.0
)
pft_classify(patient)
#>   fev1 fev1_lln  fvc fvc_lln fev1fvc fev1fvc_lln tlc tlc_lln ats_classification ats_pattern_combination
#> 1  2.5      3.0  3.8     3.5    0.66        0.70 6.2     5.0         Obstructed                    ANAN

End-to-end pipeline

For the canonical "interpret → visualise" workflow on a cohort:

cohort <- data.frame(
  sex    = c("M", "F"),
  age    = c(45,  60),
  height = c(178, 165),
  race   = c("Caucasian", "AfrAm"),
  fev1_measured = c(3.2, 1.8),
  fvc_measured  = c(4.5, 2.4),
  tlc_measured  = c(7.0, 4.8)
)

result <- pft_interpret(cohort)   # spirometry + volumes + classify + severity
pft_plot(result[1, ])             # per-patient z-score figure

Common workflows

Cohort analysis with broom-style tidiers

result <- pft_interpret(cohort)
result |> pft_long()              # one row per (patient, measure)

Reference equations

Reference data is built reproducibly from official ERS / ATS source documents. The data-raw/build_*.R scripts read the published lookup-table workbooks (or, where unavailable, the equation tables printed in the article PDFs) and regenerate the package's internal data. The source documents are copyrighted and not included in this repository; obtain them from the publishers if you want to regenerate the data.

The validation tests anchor predicted, LLN, and ULN outputs against ground truth from the official GLI web calculator at gli-calculator.ersnet.org.

Citations

Reference equations:

• Quanjer PH, Stanojevic S, Cole TJ, et al. Multi-ethnic reference values for spirometry for the 3-95-yr age range: the global lung function 2012 equations. Eur Respir J. 2012;40(6):1324-1343. doi:10.1183/09031936.00080312
• Bowerman C, Bhakta NR, Brazzale D, et al. A race-neutral approach to the interpretation of lung function measurements. Am J Respir Crit Care Med. 2023;207(6):768-774. doi:10.1164/rccm.202205-0963OC
• Hall GL, Filipow N, Ruppel G, et al. Official ERS technical standard: Global Lung Function Initiative reference values for static lung volumes in individuals of European ancestry. Eur Respir J. 2021;57(3):2000289. doi:10.1183/13993003.00289-2020
• Stanojevic S, Graham BL, Cooper BG, et al. Official ERS technical standards: Global Lung Function Initiative reference values for the carbon monoxide transfer factor for Caucasians. Eur Respir J. 2017;50(3):1700010. doi:10.1183/13993003.00010-2017 (Author correction: doi:10.1183/13993003.50010-2017)

Pattern interpretation:

• Stanojevic S, Kaminsky DA, Miller MR, et al. ERS/ATS technical standard on interpretive strategies for routine lung function tests. Eur Respir J. 2022;60(1):2101499. doi:10.1183/13993003.01499-2021
• Pellegrino R, Viegi G, Brusasco V, et al. Interpretative strategies for lung function tests. Eur Respir J. 2005;26(5):948-968. doi:10.1183/09031936.05.00035205

Use citation("pft") to retrieve the package and dependent reference list as a bibentry for your own publications.

License

MIT. See LICENSE.

The numerical reference values reproduced inside this package are facts derived from published statistical models and are not themselves copyrightable. The source publications are © their respective publishers; copies are not redistributed with this package.

Contributing

Bugs, feature requests, and clinical-validation feedback welcome via the issue tracker. For changes that affect classification logic or reference equation implementations, please include a citation to the relevant standards document in the PR description.