Skip to contents

Classify a diffusion result into a clinical pattern category

Source: R/diffusion_interpret.R
pft_diffusion_interpret.Rd

Takes per-patient dlco_zscore, va_zscore, and kco_zscore columns (the outputs of pft_diffusion() when _measured columns are supplied) and assigns a clinical interpretive category per the Hughes & Pride 2012 framework adopted by the ERS/ATS Stanojevic 2017 task force.

Usage

pft_diffusion_interpret(
  data,
  SI.units = FALSE,
  dlco = NULL,
  va = NULL,
  kco = NULL
)

Arguments

data

A data frame containing the three z-score input columns.

SI.units

Logical, default FALSE. Selects the default column names for dlco and kco. Traditional units (FALSE): dlco_zscore and kco_tr_zscore. SI units (TRUE): tlco_zscore and kco_si_zscore. va defaults to va_zscore in both unit systems.

dlco, va, kco

Column references for the three z-score inputs. dlco and kco default to NULL, which means: pick the canonical column name based on SI.units. Pass a bare name, a string, or !!var to override (see "Column-name overrides").

Value

The original data frame with a single appended column: diffusion_category. Possible values:

"Normal"

All three z-scores above LLN.

"Parenchymal"

Low DLCO, low KCO, normal VA.

"Volume loss"

Low DLCO, low VA, normal or elevated KCO.

"Mixed"

Low DLCO, low VA, low KCO.

"Vascular (suggested)"

Low DLCO, normal VA, low or elevated KCO.

"Elevated KCO"

Normal DLCO with elevated KCO (z > +1.645).

"Other"

Combination not matching any of the above patterns (e.g., low VA in isolation).

NA

Required z-score columns missing.

The category labels describe the z-score pattern only; differential diagnosis is left to the clinician (see the Hughes & Pride 2012 source paper for clinical interpretation).

Details

The classifier consumes z-scores only and is unit-agnostic, but the default input column names differ between unit systems. Set SI.units = TRUE to pick up the SI-units column set (tlco_zscore, va_zscore, kco_si_zscore); otherwise the traditional-units column set (dlco_zscore, va_zscore, kco_tr_zscore) is used. Override individual column names via the dlco / va / kco arguments.

Typically called via pft_interpret() as part of the one-call workflow; exported for callers who want to apply the classifier to pre-computed z-score columns directly.

Column-name overrides

Each column-reference argument accepts three forms:

  • a bare column name – dlco = my_dlco

  • a string – dlco = "my_dlco"

  • an injected value – dlco = !!my_var where my_var <- "my_dlco"

dlco and kco default to NULL, which selects the canonical name based on SI.units (traditional or SI). Passing an explicit reference overrides this selection.

References

Hughes JM, Pride NB. Examination of the carbon monoxide diffusing capacity (DL(CO)) in relation to its KCO and VA components. Am J Respir Crit Care Med. 2012;186(2):132-139. doi:10.1164/rccm.201112-2160CI .

Stanojevic S, Graham BL, Cooper BG, et al. ERS/ATS technical standard: Global Lung Function Initiative reference values for the carbon monoxide transfer factor for Caucasians. Eur Respir J. 2017;50:1700010. doi:10.1183/13993003.00010-2017 . (Provides the z-score reference standard whose LLN at z = -1.645 is used here. The clinical interpretation framework is from Hughes & Pride 2012, adopted by the 2017 task force.)

See also

pft_diffusion() to compute the input z-scores; pft_interpret() for the one-call workflow that auto-runs this classifier when diffusion outputs are present.

Examples

# Three patients: normal, parenchymal (low DLCO/KCO, normal VA),
# and volume loss (low DLCO/VA, normal KCO).
d <- data.frame(
  dlco_zscore  = c(-0.5, -2.0, -2.0),
  va_zscore    = c(-0.5, -0.5, -2.0),
  kco_tr_zscore = c(-0.5, -2.0, -0.5)
)
pft_diffusion_interpret(d)
#>   dlco_zscore va_zscore kco_tr_zscore diffusion_category
#> 1        -0.5      -0.5          -0.5             Normal
#> 2        -2.0      -0.5          -2.0        Parenchymal
#> 3        -2.0      -2.0          -0.5        Volume loss

# SI units (TLCO / KCO_SI). Pass SI.units = TRUE.
d_si <- data.frame(
  tlco_zscore   = c(-0.5, -2.0),
  va_zscore     = c(-0.5, -0.5),
  kco_si_zscore = c(-0.5, -2.0)
)
pft_diffusion_interpret(d_si, SI.units = TRUE)
#>   tlco_zscore va_zscore kco_si_zscore diffusion_category
#> 1        -0.5      -0.5          -0.5             Normal
#> 2        -2.0      -0.5          -2.0        Parenchymal