Improve reproducibility and CI validation

Author: Ekin-Kahraman

.github/workflows/ci.yml

@@ -26,7 +26,7 @@ jobs:
       - name: Restore renv packages
         uses: r-lib/actions/setup-renv@v2
 
-      - name: Install missing dependencies
+      - name: Restore pinned dependencies
         run: Rscript 000_install_dependencies.R
 
       - name: Verify renv.lock unchanged
@@ -42,3 +42,46 @@ jobs:
 
       - name: Tests
         run: Rscript -e 'testthat::test_dir("tests/testthat")'
+
+  pipeline-rebuild:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libglpk40
+
+      - name: Setup R
+        uses: r-lib/actions/setup-r@v2
+        with:
+          r-version: "4.5.2"
+          use-public-rspm: true
+
+      - name: Restore renv packages
+        uses: r-lib/actions/setup-renv@v2
+
+      - name: Install pinned dependencies
+        run: Rscript 000_install_dependencies.R
+
+      - name: Remove committed analysis outputs before rebuild
+        run: rm -f results/figures/*.png results/tables/*.csv
+
+      - name: Rebuild analysis outputs
+        run: Rscript run_all.R
+
+      - name: Validate rebuilt outputs
+        run: Rscript -e 'testthat::test_dir("tests/testthat")'
+
+      - name: Verify regenerated tables match tracked results
+        run: git diff --exit-code -- results/tables
+
+      - name: Verify key figures match tracked results
+        run: >
+          git diff --exit-code --
+          results/figures/qc_library_size.png
+          results/figures/pca_plot.png
+          results/figures/volcano_plot.png

000_install_dependencies.R

@@ -1,85 +1,36 @@
 #!/usr/bin/env Rscript
-# Restore all required packages for the analysis pipeline using renv.
+# Restore the pinned project library from renv.lock.
 
 is_macos <- identical(Sys.info()[["sysname"]], "Darwin")
-deps_fields <- c("Depends", "Imports", "LinkingTo")
 
-# Use a single, stable CRAN repo for both renv + non-renv installs.
 options(repos = c(CRAN = "https://cloud.r-project.org"))
-Sys.setenv(RENV_CONFIG_PPM_ENABLED = "FALSE")
-
-# Not every R distribution on macOS supports CRAN macOS binaries. Detect whether
-# a "binary" repo path exists; if not, fall back to source installs.
-binary_repo <- utils::contrib.url(getOption("repos"), type = "binary")
-source_repo <- utils::contrib.url(getOption("repos"), type = "source")
-has_cran_binaries <- is_macos && !identical(binary_repo, source_repo) && grepl("/bin/", binary_repo)
-install_type <- if (has_cran_binaries) "binary" else "source"
-options(pkgType = install_type)
+options(renv.consent = TRUE)
 
 if (!file.exists("renv.lock")) {
   stop("File not found: renv.lock\nThis project uses renv for reproducible dependencies.")
 }
 
-options(renv.consent = TRUE)
+if (is_macos) {
+  binary_repo <- utils::contrib.url(getOption("repos"), type = "binary")
+  source_repo <- utils::contrib.url(getOption("repos"), type = "source")
+  has_cran_binaries <- !identical(binary_repo, source_repo) && grepl("/bin/", binary_repo)
+  options(pkgType = if (has_cran_binaries) "binary" else "source")
+}
 
 if (!requireNamespace("renv", quietly = TRUE)) {
   message("Installing renv...")
-  install.packages("renv", dependencies = deps_fields)
-}
-
-if (requireNamespace("BiocManager", quietly = TRUE)) {
-  options(repos = BiocManager::repositories())
+  install.packages("renv")
 }
 
 message("Restoring packages from renv.lock...")
 renv::restore(prompt = FALSE)
 
-if (is_macos && !requireNamespace("ggiraph", quietly = TRUE)) {
-  message("\nPre-installing ggiraph (CRAN ", install_type, ")...")
-  tryCatch(
-    install.packages("ggiraph", type = install_type, dependencies = deps_fields),
-    error = function(e) {
-      message("ggiraph install failed: ", conditionMessage(e))
-      message("If compilation is required, ensure Xcode CLT are installed:")
-      message("  xcode-select --install")
-    }
-  )
-}
-
-deps <- renv::dependencies()
-pkgs <- sort(unique(deps$Package))
-pkgs <- setdiff(pkgs, "renv")
-
-missing <- pkgs[!vapply(pkgs, requireNamespace, quietly = TRUE, FUN.VALUE = logical(1))]
-if (length(missing) > 0) {
-  message("Installing missing packages: ", paste(missing, collapse = ", "))
-  for (pkg in missing) {
-    message("\n==> Installing: ", pkg)
-    tryCatch(
-      renv::install(
-        pkg,
-        prompt = FALSE,
-        type = install_type,
-        dependencies = deps_fields
-      ),
-      error = function(e) {
-        message("\nFailed installing ", pkg, ": ", conditionMessage(e))
-        if (is_macos) {
-          message("\nmacOS troubleshooting:")
-          message("  - Ensure Xcode Command Line Tools are installed: xcode-select --install")
-          message("  - Then retry: Rscript 000_install_dependencies.R")
-        }
-        stop(e)
-      }
-    )
+status_output <- capture.output(status <- renv::status(), type = "output")
+if (!isTRUE(status$synchronized)) {
+  if (length(status_output) > 0) {
+    message(paste(status_output, collapse = "\n"))
   }
-}
-
-if (!identical(Sys.getenv("CI"), "true")) {
-  message("Updating renv.lock...")
-  renv::snapshot(prompt = FALSE)
-} else {
-  message("CI detected; skipping renv.lock snapshot.")
+  stop("renv restore completed, but the project library is still not synchronized.")
 }
 
 message("\nDone. Run: Rscript run_all.R")

README.md

@@ -97,15 +97,15 @@ Hierarchical clustering of top 50 DE genes shows consistent expression patterns
 
 ### Pathway Enrichment
 
-**529 GO Biological Process terms** and **28 KEGG pathways** significantly enriched (FDR < 0.05).
+**529 GO Biological Process terms** and **26 KEGG pathways** significantly enriched (FDR < 0.05).
 
 ![GO Enrichment](results/figures/go_dotplot.png)
 
 Top GO terms: cytoplasmic translation, response to virus, defense response to virus.
 
 ![KEGG Enrichment](results/figures/kegg_dotplot.png)
 
-Top KEGG pathway: **Coronavirus disease - COVID-19** (FDR = 1.5×10<sup>-40</sup>), followed by NOD-like receptor signalling.
+Top KEGG pathway: **Coronavirus disease - COVID-19** (FDR = 4.5×10<sup>-39</sup>), followed by NOD-like receptor signalling.
 
 ### ISG Signalling Cascade
 
@@ -130,6 +130,7 @@ Analysis runtime: ~0.5 min after data download (~2GB).
 
 ### Notes
 - To re-download the GEO dataset (otherwise the pipeline reuses existing `data/*.rds` outputs): `FORCE_DOWNLOAD=true Rscript scripts/00_get_data.R`
+- To continue without KEGG results when the KEGG service is unavailable: `ALLOW_KEGG_FAILURE=true Rscript scripts/06_enrichment.R`
 - Lint: `Rscript dev/lint.R`
 - Tests: `Rscript -e 'testthat::test_dir("tests/testthat")'`
 - Reproducibility details (expected outputs, network requirements): see `REPRODUCIBILITY.md`
@@ -150,6 +151,11 @@ Rscript dev/lint.R
 Rscript -e 'testthat::test_dir("tests/testthat")'
 ```
 
+Maintainers updating dependencies should refresh the lockfile explicitly:
+```sh
+Rscript dev/snapshot_lockfile.R
+```
+
 ## Citation Metadata
 - Zenodo DOI: `10.5281/zenodo.18432519`
 - For citation tooling, see `CITATION.cff`
@@ -166,7 +172,8 @@ bulk-rnaseq-differential-expression/
 ├── CITATION.cff
 ├── REPRODUCIBILITY.md
 ├── dev/
-│   └── lint.R                   # Lint scripts/ via lintr
+│   ├── lint.R                   # Lint scripts/ via lintr
+│   └── snapshot_lockfile.R      # Maintainer-only renv.lock refresh
 ├── renv/
 │   ├── activate.R
 │   └── settings.json
@@ -181,7 +188,8 @@ bulk-rnaseq-differential-expression/
 │   ├── 05_model_diagnostics.R
 │   ├── 06_enrichment.R
 │   ├── 07_reproducibility.R
-│   └── 08_pathway_diagram.R
+│   ├── 08_pathway_diagram.R
+│   └── config.R                 # Shared analysis thresholds and helpers
 ├── data/
 │   └── [RDS files]
 ├── results/
@@ -241,6 +249,8 @@ This project uses `renv` for reproducible dependencies. Install/restore everythi
 Rscript 000_install_dependencies.R
 ```
 
+This command restores the pinned project library only; it does not modify `renv.lock`.
+
 ### Manual installation (optional)
 If you prefer to install packages manually instead of using `renv`:
 

REPRODUCIBILITY.md

@@ -11,13 +11,19 @@ This repository is set up so a reviewer can reproduce the analysis with a small
 Run these commands from the repository root (i.e., a fresh clone):
 
 ```sh
-# Restore/install pinned dependencies (CRAN + Bioconductor)
+# Restore/install pinned dependencies from renv.lock
 Rscript 000_install_dependencies.R
 
 # Run the full pipeline (downloads data if needed, then regenerates results)
 Rscript run_all.R
 ```
 
+Maintainers who intentionally change dependencies should refresh the lockfile explicitly:
+
+```sh
+Rscript dev/snapshot_lockfile.R
+```
+
 ## Data Download Behaviour
 The data download step (`scripts/00_get_data.R`) is **idempotent**:
 - If `data/counts_raw.rds` and `data/metadata.rds` already exist, it will **skip** re-downloading.
@@ -33,6 +39,11 @@ Some steps require network access:
 - KEGG pathway annotation (via KEGG REST) in `scripts/06_enrichment.R`
 
 If you are running in a restricted environment, these steps may fail until network access is available.
+If KEGG is temporarily unavailable and you still want the pipeline to continue locally, run:
+
+```sh
+ALLOW_KEGG_FAILURE=true Rscript scripts/06_enrichment.R
+```
 
 ## Determinism
 The balanced subset selection uses a fixed seed (`set.seed(123)` in `scripts/01_qc.R`) so repeated runs should yield the same subset and downstream results, given the same package versions.
@@ -49,9 +60,11 @@ After a successful run, you should see (among others):
 # Check environment consistency against renv.lock
 Rscript -e 'renv::status()'
 
-# Run smoke tests (validates presence/shape of committed artifacts)
+# Run output validation tests
 Rscript -e 'testthat::test_dir("tests/testthat")'
 
 # Lint the analysis scripts
 Rscript dev/lint.R
 ```
+
+GitHub Actions also performs a clean rebuild of the tracked analysis outputs and checks that regenerated key outputs match the committed versions.

dev/snapshot_lockfile.R

@@ -0,0 +1,25 @@
+#!/usr/bin/env Rscript
+# Maintainer helper: refresh renv.lock after intentionally changing dependencies.
+
+if (!file.exists("renv.lock")) {
+  stop("File not found: renv.lock")
+}
+
+options(renv.consent = TRUE)
+
+if (!requireNamespace("renv", quietly = TRUE)) {
+  stop("Package 'renv' is required. Run: Rscript 000_install_dependencies.R")
+}
+
+message("Updating renv.lock from the current project library...")
+renv::snapshot(prompt = FALSE)
+
+status_output <- capture.output(status <- renv::status(), type = "output")
+if (!isTRUE(status$synchronized)) {
+  if (length(status_output) > 0) {
+    message(paste(status_output, collapse = "\n"))
+  }
+  stop("renv.lock was updated, but the project is still not synchronized.")
+}
+
+message("renv.lock updated successfully.")