Interactive Modelling with the SAE Shiny Application

Note. This vignette describes the interactive Shiny application bundled with hbsaems. Because Shiny apps are stateful and interactive, the screenshots and example workflows below are descriptive – they show what the user sees when running the app locally. Stan fits triggered from within the GUI are not run at vignette-build time.

When to use the Shiny app

The bundled Shiny application, launched by run_sae_app(), is intended for two audiences:

Non-programmers: subject-matter experts, BPS staff, NGO analysts, or students who want to fit and inspect an SAE model without writing R code.
Programmers prototyping a model: a quick way to explore the effect of priors, link functions, or spatial structure on a small dataset before committing to a scripted workflow.

The app is not meant to replace scripted modelling for production work – the audit trail of an .R script is essential there.

Launching the app

library(hbsaems)
run_sae_app()

This launches the app in your default browser. By default it runs on a random local port; pass port = 4242 to fix the port.

The app calls check_shiny_deps() at startup; if the required Shiny packages are missing it prints an actionable install message:

The Shiny application requires the following packages:
  - shiny (>= 1.7.0)
  - shinydashboard
  - DT
  - bslib

Install them with:
  install.packages(c("shiny", "shinydashboard", "DT", "bslib"))

Layout overview

The application is organised into six sidebar sections:

+------------------------+-----------------------------------------------+
|  Sidebar               |  Main panel (sub-tabs)                        |
+========================+===============================================+
|  Data Upload           |  CSV / RDS / use built-in datasets            |
|  Spatial Setup         |  Source / Map / Matrix / Diagnostic / Ref     |
|  Model Specification   |  Family, formula, priors, RE / spatial RE     |
|  MCMC Settings         |  Chains, iter, warmup, cores, control         |
|  Fit & Diagnostics     |  Run, summary, traceplot, posterior, LOO       |
|  Predictions           |  Predict for unsampled areas, export CSV       |
+------------------------+-----------------------------------------------+

A language selector at the top of the sidebar toggles the UI between English and Bahasa Indonesia (tr()-driven; see vignette("complete-workflow") for the i18n architecture).

Section 1: Data Upload

Three options:

Upload a CSV / RDS file – standard file-picker; the app previews the first 10 rows and lets you mark columns as response, auxiliary, group, or trial/n.
Use a bundled dataset – dropdown selector with data_fhnorm, data_lnln, data_betalogitnorm, data_binlogitnorm.
Paste from clipboard – for quick experiments with copied spreadsheet data.

Every uploaded dataset is validated by check_data(), which reports:

Total rows and columns
Missing-value counts per column
Response distribution check (e.g. “98% in (0, 1)” for proportions)

Section 2: Spatial Setup

A dedicated section since spatial modelling is the trickiest part of SAE for newcomers. Five sub-tabs:

Source: choose between (a) a shapefile / GeoJSON upload,
1. a precomputed adjacency matrix CSV, or (c) one of the bundled example matrices.
Map: leaflet-based preview of the polygons coloured by the response variable.
Matrix: heatmap of the weight matrix, with row-normalisation and standardisation options.
Diagnostic: runs check_spatial_weight() and reports symmetry, isolates, mean neighbours, and a verdict.
Reference: short text on CAR, SAR, BYM2, and the recommended parameterisations.

Section 3: Model Specification

Step-by-step:

Likelihood family: dropdown (gaussian, lognormal, Beta, binomial, loglogistic, shifted_loglogistic, …). Custom families registered via register_hbsae_brms_custom() appear in the same list.
Response variable: dropdown of numeric columns; the app greys out incompatible options (e.g. negative values for a lognormal).
Auxiliary variables: multi-select.
Group (random intercept): dropdown of integer/character columns.
Spatial random effect: toggle on/off; if on, choose CAR or SAR.
Pinned parameters: toggle on/off for $\phi$ from n+deff (Beta) or $\sigma$ from sampling_variance (lnln).
Priors: a table of priors with reasonable defaults that the user can edit. Distribution preview (PDF/CDF plots) is shown for the currently-selected class.

The “Build formula” button assembles the bf(...) call and shows the equivalent R code in a code block, which can be copied for scripted use:

# Equivalent R code (copy this for a scripted workflow):
hbm_lnln(
  response     = "y_obs",
  auxiliary    = c("x1", "x2", "x3"),
  area_var   = "regency",
  sampling_variance = "psi_i",
  data         = my_data,
  chains = 4, iter = 4000, warmup = 2000, cores = 4, seed = 1
)

Section 4: MCMC Settings

Sliders for chains (1-8), iter (1000-10000), warmup (fraction of iter), cores (capped at parallel::detectCores()), and seed. Advanced control options (adapt_delta, max_treedepth) are exposed under an “Advanced” disclosure.

Section 5: Fit & Diagnostics

Once “Fit Model” is clicked, the app:

Disables the Fit button and shows a progress bar with the live Stan output (compilation + each chain’s iteration count).
After the fit completes, populates four diagnostic sub-tabs:
- Summary: the standard summary() output rendered as an HTML table.
- Traceplot: bayesplot::mcmc_trace() for selected parameters.
- Posterior: density plots / mcmc_areas for selected parameters; “Compare with prior” toggle.
- LOO: loo() output and Pareto- $k$ diagnostic plot.

Saving the fit creates an .rds file with the hbmfit object.

Section 6: Predictions

Two modes:

In-sample: posterior mean and 95% CI for every area in the original dataset, joined with the area ID, exported as CSV.
Out-of-sample: upload (or paste) auxiliary values for new areas; the app calls sae_predict(..., allow_new_levels = TRUE) and produces a downloadable predictions table plus, if a polygon layer is loaded, a choropleth map.

Reproducibility

Every action in the app is logged to a hidden R log that can be exported as a runnable .R script. This gives users the best of both worlds: interactive exploration plus a scripted record that reproduces the entire session.

Limitations

Single-user. The app is designed to be run locally (run_sae_app() on your laptop); it is not a multi-user web service. For a deployable web service, use Shiny Server or Posit Connect with the bundled app source at system.file("shiny", "sae_app", package = "hbsaems").
Dataset size. In-memory only; not designed for datasets larger than a few thousand areas.
Custom families. Custom brms families must be registered before launching the app (register_hbsae_brms_custom()); they cannot be defined from inside the app.
Stan compilation time is unaffected by the GUI; the first fit in a session still incurs the one-time compile cost.