vignettes/shiny-walkthrough.Rmd
shiny-walkthrough.RmdThe stepssurvey package includes a Shiny web application
that provides a guided, point-and-click interface for analysing WHO
STEPS survey data. It calls the same functions available in the R API,
so results are identical whether you use the app or write scripts.
The app is designed for public health professionals who may not write R code but need to produce standardised STEPS outputs.
This opens a browser window with a six-tab workflow. Each tab corresponds to one stage of the pipeline: Data & Settings, Clean, Design, Indicators, Visualise, and Reports.
Work through the tabs from left to right. Each tab activates once the previous step has completed successfully.
This is where you load your STEPS data.
Click Browse and select your file. Supported formats
are CSV (.csv), Excel (.xlsx), Stata
(.dta), and SPSS (.sav). SPSS is the most
common format for STEPS data exported from Epi Info.
After upload, you will see:
If you do not have a STEPS data file, click Use demo data to load a realistic simulated dataset with 3,000 observations. This is useful for exploring the app and understanding the outputs before running your own data.
The auto-detection system recognises standard WHO STEPS variable codes from both instrument v3.1 and v3.2. However, some country datasets use non-standard names. If a variable is marked “not found”, use the dropdown menus under Column overrides to manually select the correct column from your data.
Key variables to check:
| Variable | What it is | Why it matters |
|---|---|---|
age |
Respondent age in years | Required for age group classification |
sex |
Respondent sex | Required for sex-stratified tables |
weight_step1 |
Sampling weight (Step 1) | Needed for correct weighted estimates |
psu |
Primary sampling unit / cluster | Needed for correct standard errors |
tobacco_current |
Current tobacco smoking | Core Step 1 indicator |
sbp1 |
First SBP reading | Core Step 2 indicator |
fasting_glucose |
Fasting blood glucose | Core Step 3 indicator |
Click the Clean button to process the raw data. The cleaning step:
After cleaning, you will see:
If cleaning fails, check the console output (or R Studio console) for messages about which variables were missing or had unexpected values.
This tab creates the complex survey design object that ensures all estimates account for the sampling weights, stratification, and clustering used in STEPS surveys.
The app automatically detects the survey design complexity:
You will see a summary confirming which design was created. Extreme weights are automatically trimmed to prevent individual observations from dominating the estimates.
Click Compute indicators to calculate all weighted prevalence estimates and means across six domains:
After computation, you will see:
This tab displays pre-built charts. All plots use the WHO STEPS
colour palette and theme_steps() styling.
If a particular chart is not available (because the underlying data was missing), a “not available” message is shown instead of an error.
This is the final step. Click Generate report to produce both reports.
The app runs a pipeline that:
A status message keeps you informed of progress. The full process typically takes 30–90 seconds depending on sample size.
| Report | Button | Contents |
|---|---|---|
| Summary Report | Download Summary Report | Executive summary, narrative by domain, embedded charts, recommendations, methodology |
| Detailed Data Book | Download Data Book | Complete WHO 3-panel tables (Men | Women | Both Sexes) by age group, organised by STEPS step |
The country report includes:
The data book follows the WHO STEPS standard layout with tables organised by survey step:
Every table uses the 3-panel format:
Age Group | Men | Women | Both Sexes
18-24 | 4.3% (2-6.5)| 0% (0-0) | 1.8% (0.8-2.8)
25-34 | ... | ... | ...
...
18-69 | ... | ... | ...If you see dim<-.haven_labelled() not supported, this
was a known issue with SPSS files that has been fixed. Make sure you are
running the latest version of the package
(devtools::load_all(".") or reinstall from GitHub).
This happens when the RStudio Viewer pane is too narrow. Open the app
in a full browser window instead: after run_app(), click
“Open in Browser” in the Viewer toolbar.
The Summary Report derives the insufficient PA indicator from
MET-minutes/week. If your dataset has raw GPAQ items (P1–P16) but no
pre-computed met_total, the package now computes
MET-minutes/week automatically using WHO MET multipliers (8 for
vigorous, 4 for moderate/transport activities). Ensure your GPAQ columns
are correctly mapped in Tab 1.
Tables are only produced when the required variables are present in the data. For example, CVD risk tables require both clinical measurements and a risk scoring algorithm. Missing tables show “No data available for this section.”
Yes. The R Markdown templates are located in inst/rmd/
within the package source:
country_report.Rmd – Summary Reportdata_book.Rmd – Detailed Data Bookfact_sheet.Rmd – Fact SheetCopy the template you want to modify, edit it, and pass the path via the config object.
| Feature | Shiny App | R Scripts |
|---|---|---|
| Audience | Non-coders, quick analysis | R users, reproducible workflows |
| Column mapping | Interactive dropdowns |
detect_steps_columns() + manual overrides |
| Customisation | Limited to built-in options | Full control over every step |
| Batch processing | One dataset at a time | Loop over multiple datasets |
| Reproducibility | Manual (same clicks each time) | Full script = full reproducibility |
| Output | Word reports via browser | Word, HTML, PDF, or custom formats |
For routine country-level STEPS analysis, the Shiny app is the
fastest path. For multi-country comparisons, methodological research, or
custom indicators, use the R API documented in
vignette("stepssurvey-guide").