---
title: "Glossary"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Glossary}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(echo = TRUE, comment = "#>")
```

A reference for the clinical and statistical terms used throughout
`pft`. Every definition is keyed to the canonical source where the
term is formally defined.

# Measure abbreviations

**FEV1** — Forced Expiratory Volume in 1 second. The volume of air
expired during the first second of a forced expiratory maneuver,
in litres.

**FVC** — Forced Vital Capacity. The total volume of air expired
during a forced exhalation from full inspiration, in litres.

**FEV1/FVC** — Ratio of FEV1 to FVC. Dimensionless; typical adult
values are 0.70 – 0.85.

**FEF25-75** — Forced Expiratory Flow between 25% and 75% of FVC.
Litres per second.

**FEF75** — Forced Expiratory Flow at 75% of expired FVC.

**FRC** — Functional Residual Capacity. The volume in the lungs at
the end of normal tidal expiration.

**TLC** — Total Lung Capacity. The maximum volume of air in the lungs
after full inspiration.

**RV** — Residual Volume. The volume remaining in the lungs after
maximum exhalation.

**RV/TLC** — The ratio of residual volume to total lung capacity.

**ERV** — Expiratory Reserve Volume.

**IC** — Inspiratory Capacity.

**VC** — Vital Capacity (slow VC, distinct from FVC).

**TLCO** / **DLCO** — Transfer factor / diffusing capacity for carbon
monoxide. "TLCO" is the SI-units name; "DLCO" is the traditional-units
name; they describe the same physiological measure.

**KCO** — Carbon-monoxide transfer coefficient, equal to TLCO/VA (or
DLCO/VA). Expressed in SI or traditional units accordingly.

**VA** — Alveolar volume, used in the single-breath DLCO maneuver.

# Statistical terms

**M (median / predicted value)** — The age-, sex-, and demographic-
adjusted central value for a measure. In the GLI LMS framework, the
expected value for a healthy individual matching the inputs.

**S (coefficient of variation)** — A scale parameter from the LMS
framework that captures the spread of healthy values at each age/sex
combination.

**L (skewness / Box-Cox transform)** — A shape parameter from the LMS
framework that adjusts for non-normality of the underlying
distribution.

**LMS method** — A statistical framework
(Cole TJ. *Stat Med.* 1988;7(3):305-12) that models reference
distributions via three age-varying parameters L, M, S. Used by the
GLI equations for FEV1, FVC, FEV1/FVC, TLCO, lung volumes, and others.

**LLN (lower limit of normal)** — The 5th percentile of the
reference distribution: the value below which a healthy individual
falls only 5% of the time. Equivalent to a z-score of **−1.645**.

**ULN (upper limit of normal)** — The 95th percentile, equivalent to
z-score **+1.645**.

**z-score** — A measure of how far an observed value is from the
predicted median, expressed in standard deviation units. In the LMS
framework:
$$z = \frac{(measured / M)^L - 1}{L \cdot S}.$$
Implemented by the `<measure>_zscore` outputs of `pft_spirometry()`,
`pft_volumes()`, and `pft_diffusion()`.

**Percent predicted** — `(measured / M) × 100`. A traditional
expression of departure from predicted; superseded by z-scores in the
Stanojevic 2022 standard but still widely used in clinical practice.

# Patterns and clinical entities

**Normal** — All measured values at or above their LLN.

**Obstructed** — FEV1/FVC below LLN with TLC at or above LLN (or
unknown).

**Restricted** — TLC below LLN with FEV1/FVC at or above LLN.

**Mixed** — Both FEV1/FVC and TLC below their LLNs.

**Non-specific pattern** — Low FVC with normal FEV1/FVC and normal
TLC. By definition not restrictive (TLC is normal) and not obstructive
(FEV1/FVC is normal). The label is descriptive only; Stanojevic 2022
Table 5 enumerates clinical contexts.

**PRISm** — Preserved Ratio Impaired Spirometry. Low FEV1 with
FEV1/FVC at or above LLN. A spirometry-only screening label (no TLC
required).

**Dysanapsis** — A normal-variant pattern with normal FEV1, high
FVC, and low FEV1/FVC. Listed in Stanojevic 2022 Table 5 but not
emitted as a separate label by `pft_classify()` (folded into
"Obstructed" when FEV1/FVC is below LLN).

# Tests and gradings

**BDR (bronchodilator response)** — Per Stanojevic 2022: a change of
**more than 10% of the predicted value** in FEV1 or FVC between pre-
and post-bronchodilator measurements. Implemented by `pft_bdr()`.
Replaces the 2005 standard (≥12% AND ≥200 mL from baseline).

**Severity grading** — Per Stanojevic 2022, a uniform three-level
system applied to any z-score:

| Grade     | z-score                |
|-----------|------------------------|
| Normal    | z ≥ −1.645              |
| Mild      | −2.5 ≤ z < −1.645       |
| Moderate  | −4 ≤ z < −2.5           |
| Severe    | z < −4                  |

Implemented by `pft_severity()`.

**GOLD COPD severity** — Per the Global Initiative for Chronic
Obstructive Lung Disease, in patients with confirmed airflow
obstruction:

| Grade   | FEV1 % predicted |
|---------|-------------------|
| GOLD 1  | ≥ 80%             |
| GOLD 2  | 50 – < 80%        |
| GOLD 3  | 30 – < 50%        |
| GOLD 4  | < 30%             |

Implemented by `pft_gold()`.

**CCS (conditional change score)** — A z-score-style index of whether
the change between two measurements computed as
`(z2 − r * z1) / sqrt(1 − r^2)` exceeds the within-subject variability expected by
regression-to-the-mean alone. `|CCS| > 1.96` is the Stanojevic 2022
two-sided 95% normal-limits threshold (Box 2). Implemented by
`pft_change()`.

**Spirometry quality grade (A–F)** — Per Graham et al. ATS/ERS 2019,
a grade based on the number of acceptable maneuvers from a session
and the difference between the two best values:

| Grade | Acceptable | Best-two diff (adult)     | Best-two diff (child ≤ 6)  |
|-------|------------|---------------------------|-----------------------------|
| A     | ≥ 3        | ≤ 0.150 L                 | ≤ 0.100 L                   |
| B     | 2          | ≤ 0.150 L                 | ≤ 0.100 L                   |
| C     | ≥ 2        | ≤ 0.200 L                 | ≤ 0.150 L                   |
| D     | ≥ 2        | ≤ 0.250 L                 | ≤ 0.200 L                   |
| E     | ≥ 2        | > 0.250 L, or 1 maneuver  | > 0.200 L, or 1 maneuver    |
| F     | 0          | n/a                       | n/a                         |

The child thresholds (column "Best-two diff (child ≤ 6)") are
additionally floored at 10% of the highest measured value per
Graham 2019 Table 10's footnote.

Implemented by `pft_quality()`.

# Notation: the 4-character pattern combination

`pft_classify()` emits an `ats_pattern_combination` column with a
four-character string. Each character is **A** (below LLN) or **N**
(at or above LLN), in the fixed order:

1. FEV1
2. FVC
3. FEV1/FVC
4. TLC

So `"NNAN"` means *normal FEV1, normal FVC, abnormally low FEV1/FVC,
normal TLC*. This is by definition pure airway obstruction.

# Race / ancestry categories (GLI 2012 only)

GLI 2012 distinguishes five ancestral groups for spirometry:

* **Caucasian** — European-ancestry populations.
* **AfrAm** — African American.
* **NEAsia** — North-East Asian (Han Chinese, Japanese, Korean).
* **SEAsia** — South-East Asian.
* **Other/mixed** — A multi-ethnic composite category constructed by
  the GLI Task Force from populations not captured by the four above.

GLI Global 2022 is race-neutral; the `race` column is ignored when
calling `pft_spirometry(year = 2022)`.

# Common validation errors

If your cohort is unexpectedly all-NA or you see a warning about
unrecognised inputs, check the following before anything else:

**Sex must be canonical `"M"` / `"F"`.** Common dataset values like
`"male"`, `"Male"`, `"MALE"`, `"m"`, `"f"`, `"Female"`, `"woman"`,
`"boy"`, `"girl"` are auto-normalised with a warning. Anything else
(e.g. `"Unknown"`, `"X"`, `"NB"`) is set to `NA`. Prior to this
behaviour any value other than `"M"` was silently treated as female;
make sure your data isn't relying on that.

**Race must be one of the five GLI 2012 categories.** Common
variants like `"caucasian"` (lowercase), `" Caucasian"` (whitespace),
`"white"`, `"black"`, `"African American"`, `"european"` are
auto-normalised with a warning. Anything else (`"Asian"` ambiguous
between NEAsia/SEAsia is mapped to `NEAsia`; other strings like
`"Hispanic"`, `"Latino"`, `"Native American"` are not in the GLI 2012
framework) is set to `NA`.

**`year = 2012` without a `race` column errors** rather than
silently producing all-NA output. Either supply a `race` column or
call `pft_spirometry(data, year = 2022)` for the race-neutral
equations.