Home

DETECT RPC APS BL Project Wiki

Welcome to the APS Baseline Dashboard project! This wiki documents everything you need to get the code running locally, understand the data pipeline, and deploy the Quarto-based dashboard to GitHub Pages.

---

📑 Table of Contents

1. Project Overview
2. Repository Structure
3. Prerequisites
4. Quick Start
5. Obtaining a REDCap API Token
6. Detailed Usage
7. Local Development Workflow
8. Resetting the R Environment
9. Deployment to GitHub Pages
10. Troubleshooting & FAQ
11. Contributing

---

Project Overview

The APS Baseline Dashboard visualises REDCap survey submissions for the APS (Active Project Surveillance) initiative. Data are retrieved from REDCap, stored locally in a lightweight DuckDB database, and surfaced in an interactive Quarto Dashboard (aps-dashboard.qmd).

Key components:

• data_operations.r – Pulls data from REDCap and writes it to a DuckDB file.
• aps-dashboard.qmd – Quarto file that queries the DuckDB and builds the dashboard UI.
• renv.lock – Exact package snapshot for reproducibility.

---

Repository Structure

├── data_operations.r          # Data-ingestion script
├── aps-dashboard.qmd          # Quarto dashboard source
├── renv.lock                  # Package lockfile (renv)
├── assets/
│   └── data/                  # DuckDB database lives here after first run
└── README.md / .github/       # (recommended) project meta & workflows

Tip: Keep all generated objects (DuckDB, Quarto _site/ or docs/ output) out of version control via .gitignore.

---

Prerequisites

Tool	Minimum Version	Install Command
R	4.5.0	https://cran.r-project.org
renv	1.0.0	install.packages("renv")
Quarto CLI	1.4.550	https://quarto.org/docs/get-started/
Git	2.40	https://git-scm.com

All other R packages (e.g., duckdb, REDCapR) are installed automatically by renv::restore().

---

Quick Start (in Terminal)

# 1. Clone the repository
git clone https://github.com/your-org/aps-dashboard.git
cd aps-dashboard

# 2. Restore all R packages
R -q -e "renv::restore()"

# 3. Store your REDCap API token (one-off, project-local)
echo "REDCAP_API_TOKEN=<your-token>" >> .Renviron

# To update the dashboard, rerun steps 4 and 5 only.
# 4. Ingest data (creates assets/data/APS-DATA.duckdb)
Rscript data_operations.r

# 5. Render & preview the dashboard
quarto preview aps-dashboard.qmd

🔐 Security: .Renviron should be listed in .gitignore so your token never reaches version control.

---

Obtaining a REDCap API Token

To query data you need a user-specific API token issued by the REDCap project you have access to.

1. Log in to REDCap at https://redcap.uth.tmc.edu/.
2. Open the APS Baseline project (or whichever project you need).
3. In the left sidebar, expand Applications → API.
4. If you don’t see a token, click Request API token and wait for approval.
5. Once approved, copy the 32-character string shown as Your API token.
6. Add it to a project-local .Renviron file:

   echo 'REDCAP_API_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' >> .Renviron

7. Open a new terminal (or restart RStudio) so the environment variable is loaded.

Scope: Tokens are project-specific—generate one for each REDCap project you work with.

---

Detailed Usage

Restoring the R Environment

renv.lock pins exact package versions. From your project root run:

renv::restore()

This installs all required packages into an isolated project library.

Fetching Data from REDCap

data_operations.r authenticates via your REDCAP_API_TOKEN and retrieves records:

redcap_read(
  redcap_uri  = "https://redcap.uth.tmc.edu/api/",
  token       = Sys.getenv("REDCAP_API_TOKEN"),
  continue_on_error = FALSE
)

Persisting Data with DuckDB

The script writes the fetched dataframe to assets/data/APS-DATA.duckdb:

dbWriteTable(con, "APS-BL", data$data, overwrite = TRUE)

Rendering the Quarto Dashboard

aps-dashboard.qmd uses the dashboard format. Render once:

quarto render aps-dashboard.qmd

The default output directory is _site/ (configurable via quarto.yml).

---

Local Development Workflow

1. Pull latest code – git pull origin main
2. Update data – Rscript data_operations.r
3. Iterate on visuals – Edit aps-dashboard.qmd → Quarto auto-reload
4. Commit changes – git commit -am "Add new KPI"
5. Push – git push origin main

---

Resetting the R Environment

If renv::restore() fails or you need a clean slate:

1. Rename or delete renv.lock.
2. Re-initialise renv:

   renv::init(bare = TRUE)      # creates a new lockfile
   renv::restore(lockfile = NULL)  # bypasses lockfile during restore

3. Install any extra packages, then run renv::snapshot(force = TRUE).
4. Commit the new renv.lock once everything renders correctly.

---

Deployment to GitHub Pages

The dashboard is built and served directly from the main branch.

Manual (no CI)

1. Configure Quarto to output to / (default).

2. Render the site:

   quarto render aps-dashboard.qmd

3. Commit and push the generated files:

   git add .
   git commit -m "Render site"
   git push origin main

4. In Repository → Settings → Pages, set Source to main branch and / since you render to root.

---

Troubleshooting & FAQ

Issue	Fix
_reproducible snapshot ... failed_	Delete .renv/ and run renv::restore()
Dashboard shows 0 submissions	Confirm .Renviron contains your token and that your REDCap user has export rights
Quarto command not found	Install Quarto CLI and ensure it’s on your PATH
Pages 404 after deploy	Wait a few minutes; Pages CDN caches. Confirm site in /docs on main

---

Contributing

1. Fork → Create feature branch (feat/new-chart) → Commit → Open PR.
2. Run lintr and ensure Quarto renders without errors.
3. Describe visual or data changes clearly in the PR summary.

---