Analysis pipeline (R) for a survey of respiratory muscle training in wind instrumentalists: descriptives, latent class analysis, and power analysis

This repository contains the R analysis pipeline for the Wind Instrumentalist Breathing and Muscle (WIBM) survey, an international cross-sectional survey of 1,441 wind instrumentalists examining respiratory muscle training (RMT) behaviours, beliefs and values, breathlessness, and receptivity to evidence. The code is organised as a sequence of numbered scripts that share a common set of APA-7 formatting helpers (00_APA_helpers.R) and write Word tables and high-resolution figures to a shared output folder. Script 01 imports the raw survey export, applies the exclusion criteria, and recodes the responses into a single cleaned dataset (data_clean.rds), which every later script reads as its input. Scripts 02–06 then produce the descriptive analyses for each domain in turn: demographics (02), RMT behaviours (03), beliefs and values (04), breathlessness (05), and receptivity to evidence (06). Script 07 is the analytical core, fitting a four-class latent class analysis (LCA) of RMT behaviour — with classes labelled No RMT, Instrument-only, Instrument + Body, and All-Rounder — and then using the BCH (Bolck–Croon–Hagenaars) approach to relate class membership to outcomes across all domains, with pairwise class comparisons corrected for multiple testing via the Benjamini–Hochberg false discovery rate (FDR). Script 08 carries out the corresponding power analysis for these class comparisons, and a standalone script computes inter-rater reliability (Cohen's kappa) for the qualitative content analysis. Because the survey data cannot be shared under the study's ethics approval, the dataset itself is not included; the scripts, together with the tables and figures they generate, are provided so that the analysis can be read, checked, and verified.

# Respiratory Muscle Training in Wind Instrumentalists — Survey Analysis

R analysis pipeline for the Wind Instrumentalist Breathing & Muscle (WIBM) survey,
an international survey of wind instrumentalists (*N* = 1,441) covering respiratory
muscle training (RMT) behaviours, beliefs, breathlessness, and receptivity to
evidence. This code reproduces the descriptive results, the latent class analysis
(LCA) with BCH auxiliary analyses, and the power analysis reported in the thesis
*Respiratory Muscle Performance and Training in Wind Instrumentalists*.

All analysis is in R. Tables are written to Word (APA 7th edition) and figures are
exported at 600 dpi (PNG + TIFF) using a colourblind-safe palette.

---

## Repository structure

```
wibm-survey-analysis/
├── README.md                  This file
├── LICENSE                    MIT licence
├── CITATION.cff               How to cite the code
├── run_all.R                  Runs the pipeline (01–08) in order
├── setup.R                    Installs required packages / fonts
├── wibm-survey-analysis.Rproj RStudio project (sets the project root)
├── R/                         Analysis scripts
│   ├── 00_APA_helpers.R           Shared APA-7 table/figure helpers
│   ├── 00_Clear_Folders.R         Utility: wipe output folders before a re-run
│   ├── 01_Data_Preparation.R      Import, exclusions, recoding → data_clean.rds
│   ├── 02_Demographics.R          Demographic description
│   ├── 03_Behaviours.R            RMT behaviours (prevalence, frequency, teaching)
│   ├── 04_Beliefs.R               Beliefs, values, and influences
│   ├── 05_Breathlessness.R        Breathlessness / dyspnoea
│   ├── 06_Receptivity.R           Receptivity to evidence (RCT vs non-RCT arm)
│   ├── 07_LCA.R                   Latent class analysis + BCH auxiliary analyses
│   ├── 08_Power_Analysis.R        Power analysis for the BCH comparisons
│   └── Kappa_Calculation_for_CA.R Inter-rater reliability (content analysis)
├── data/                      Survey data — NOT included (see data/README.md)
└── output/                    Tables and figures from the analysis (included; see output/README.md)
```

---

## The scripts

The numeric prefixes give the run order. `01` must run first; it writes
`data/data_clean.rds`, which every later script reads.

| Script | Purpose |
| --- | --- |
| `00_APA_helpers.R` | Functions sourced by `01`–`06`: APA-7 table title/note blocks, the figure theme and 600-dpi save routine, colourblind-safe palettes, and the Likert stacked-bar helper. Not run on its own. |
| `00_Clear_Folders.R` | Deletes the contents of `output/tables` and `output/figures` so a full re-run starts clean. Run manually; never sourced by another script. |
| `01_Data_Preparation.R` | Reads the raw survey export, applies the exclusion criteria, renames and recodes variables, and writes `data_clean.rds`/`.csv`/`.xlsx` plus the exclusions table. |
| `02_Demographics.R` | Sample description: counts, percentages, demographic figures, and the APA summary table. |
| `03_Behaviours.R` | RMT behaviours: method prevalence, practice frequency by method, external devices, reasons for non-use, and teaching practices. |
| `04_Beliefs.R` | Beliefs, values, and influences: Likert summaries, body-region importance, and correlations. |
| `05_Breathlessness.R` | Breathlessness / dyspnoea prevalence and patterns. |
| `06_Receptivity.R` | Receptivity to evidence, including the randomised RCT vs non-RCT evidence-framing comparison. |
| `07_LCA.R` | Latent class analysis (four classes) via `tidySEM`/`OpenMx`, BCH auxiliary analyses across all domains, FDR-corrected pairwise comparisons, and the forest/dot/heatmap figures and Word tables. Self-contained and the longest to run. |
| `08_Power_Analysis.R` | A priori, sensitivity, and simulation-based power analysis for the BCH auxiliary analyses (one-way ANOVA framing, *k* = 4 groups). Self-contained. |
| `Kappa_Calculation_for_CA.R` | Cohen's kappa for the qualitative content-analysis coding. Standalone. |

---

## Requirements

- **R** 4.2 or newer (record your exact version with `sessionInfo()`).
- **Packages** — install with `source("setup.R")`, or use `renv` (below). Core
  packages: `here`, `readxl`, `writexl`, `dplyr`, `tidyr`, `purrr`, `stringr`,
  `forcats`, `ggplot2`, `ggtext`, `patchwork`, `scales`, `flextable`, `officer`,
  `ragg`, `devEMF`, `extrafont`, `tidySEM`, `OpenMx`, `pwr`, `moments`, `irr`,
  `conflicted`, `zip`.
  - `OpenMx` is the engine behind `tidySEM`'s mixture models and BCH step; install
    it explicitly if `tidySEM` does not pull it in.
- **Font** — figures use **EB Garamond**. Install the font on your system, then
  register it once with `extrafont::font_import()` and
  `extrafont::loadfonts()`. `ragg` is used as the save device so the font renders
  correctly. Font handling in the scripts is set up for Windows
  (`loadfonts(device = "win")`); on macOS/Linux change the device accordingly.

---

## Getting started

1. Clone the repository and open `wibm-survey-analysis.Rproj` in RStudio. Opening
   the project sets the working directory to the repo root, which is how
   `here::here()` finds files — there is no need to call `setwd()`.
2. Install dependencies: `source("setup.R")` (or `renv::restore()` once a lockfile
   exists — see below).
3. Place the data files in `data/` (see **Data availability**).
4. Run the pipeline: `source("run_all.R")`, or run the scripts in `R/` one at a
   time in numeric order. Outputs are written to `output/`.

`run_all.R` runs `01`–`08` in order, each in its own environment.
`00_Clear_Folders.R` and `Kappa_Calculation_for_CA.R` are run separately when
needed.

---

## Data availability

The WIBM survey microdata is **not** included in this repository. The responses
were collected under a human-research ethics approval and consent terms that do
not permit public release of participant-level data.

To run the pipeline you need two files in `data/`:

- `R_Import_Transformed_15.02.25.xlsx` (sheet `To import`) — the raw export read
  by `01_Data_Preparation.R`.
- `data_clean.rds` — produced by `01`; required by `02`–`08`. (Running `01`
  creates this for you.)

The dataset cannot be shared. Participants consented on the basis that their
responses would be accessible only to the study investigators and stored for a
limited period, and the consent did not provide for public release or repository
deposit. Because the responses are anonymous, participants cannot be re-contacted
to consent to sharing. The code is published for transparency — so the analysis
can be read and checked — even though it cannot be re-run without the data. If a
runnable example is needed, a synthetic dataset (artificial rows, no real
responses) can be generated; that is not participant data. See `data/README.md`.

`data/` is git-ignored (except `data/README.md`) so participant data is never
committed by accident.

---

## Outputs

The tables and figures the scripts produce are included in `output/` so the
results can be inspected without running anything. They are aggregate and
non-identifiable. Figures are kept as PNG (which preview on GitHub); the
print-resolution TIFF copies are excluded by default to keep the repository
small. See `output/README.md` for the layout, the script-to-folder mapping, and
how to populate the folder.

---

## Reproducibility

- **Paths** are relative to the project root via `here::here()`, so the code runs
  on any machine once the `.Rproj` is opened — no absolute paths.
- **Package versions** — initialise `renv` to pin exact versions:
  ```r
  install.packages("renv")
  renv::init()       # creates renv.lock
  renv::snapshot()   # records exact versions
  ```
  A collaborator then reproduces your library with `renv::restore()`. Commit
  `renv.lock`. At minimum, paste your `sessionInfo()` and R version here.
- **Randomness** — the LCA and simulation steps set seeds where relevant.