MAniR 3: scalable matrix viewer and quantitative comparisons

.github/workflows/docs-screenshots.yml

@@ -0,0 +1,106 @@
+name: Capture real MAniR documentation screenshots
+
+on:
+  push:
+    branches:
+      - upgrade/scalable-analysis
+    paths:
+      - scripts/capture-docs-screenshots.js
+      - .github/workflows/docs-screenshots.yml
+      - app.R
+      - ui.R
+      - server.R
+      - R/**
+      - www/**
+      - examples/**
+  workflow_dispatch:
+
+concurrency:
+  group: manir-real-screenshots-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+
+jobs:
+  capture-screens:
+    name: Real Shiny screenshot capture
+    if: github.ref == 'refs/heads/upgrade/scalable-analysis'
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: true
+
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          cache-version: 1
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Install browser driver
+        run: |
+          npm install --no-save --no-package-lock playwright@1.55.1
+          if command -v google-chrome >/dev/null 2>&1; then
+            echo "CHROME_BIN=$(command -v google-chrome)" >> "$GITHUB_ENV"
+          elif command -v chromium >/dev/null 2>&1; then
+            echo "CHROME_BIN=$(command -v chromium)" >> "$GITHUB_ENV"
+          else
+            npx playwright install --with-deps chromium
+          fi
+
+      - name: Start real MAniR Shiny app
+        run: |
+          nohup Rscript -e "shiny::runApp('.', host='127.0.0.1', port=3838, launch.browser=FALSE)" \
+            > "$RUNNER_TEMP/manir-shiny.log" 2>&1 &
+          echo $! > "$RUNNER_TEMP/manir-shiny.pid"
+          for attempt in $(seq 1 90); do
+            if curl --silent --fail --output /dev/null http://127.0.0.1:3838; then
+              echo "MAniR is running"; break
+            fi
+            sleep 2
+          done
+          curl --silent --fail http://127.0.0.1:3838 >/dev/null || {
+            cat "$RUNNER_TEMP/manir-shiny.log"
+            exit 1
+          }
+
+      - name: Capture actual example-data screens
+        run: node scripts/capture-docs-screenshots.js
+        env:
+          MANIR_SCREENSHOT_URL: http://127.0.0.1:3838
+
+      - name: Upload screenshots for review
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: actual-manir-screenshots
+          path: docs/images/*.png
+          if-no-files-found: warn
+
+      - name: Store actual screenshots on development branch
+        if: success()
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add docs/images/*.png
+          if git diff --cached --quiet; then
+            echo "Documentation screenshots unchanged"
+          else
+            git commit -m "docs: update real Shiny screenshots from synthetic example"
+            # The docs may have changed while this browser job was running.
+            git fetch origin upgrade/scalable-analysis
+            git rebase origin/upgrade/scalable-analysis
+            git push origin HEAD:upgrade/scalable-analysis
+          fi
+
+      - name: Show Shiny server logs on failure
+        if: failure()
+        run: cat "$RUNNER_TEMP/manir-shiny.log" || true

.github/workflows/r-tests.yml

@@ -0,0 +1,53 @@
+name: MAniR tests and benchmark smoke
+
+on:
+  push:
+    branches:
+      - main
+      - upgrade/**
+  pull_request:
+
+jobs:
+  r-tests:
+    name: R regression suite
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          cache-version: 1
+          extra-packages: |
+            any::data.table
+            any::fastcluster
+      - name: Test numerical correctness, files and plot export
+        run: Rscript tests/run_tests.R
+      - name: Parse and load the Shiny application
+        run: Rscript -e "stopifnot(inherits(getElement(source('app.R'), 'value'), 'shiny.appobj'))"
+      - name: Shiny upload smoke test
+        run: Rscript tests/test_shiny.R
+      - name: Benchmark smoke
+        run: Rscript benchmarks/benchmark.R --smoke
+      - name: Upload benchmark smoke results
+        uses: actions/upload-artifact@v4
+        with:
+          name: MAniR-benchmark-smoke
+          path: benchmarks/results/*-smoke.csv
+
+  windows-tests:
+    name: Windows regression suite
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: r-lib/actions/setup-r@v2
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          cache-version: 1
+      - name: Regression tests
+        run: Rscript tests/run_tests.R
+      - name: Parse and load application
+        run: Rscript -e "stopifnot(inherits(getElement(source('app.R'), 'value'), 'shiny.appobj'))"
+      - name: Shiny upload smoke test
+        run: Rscript tests/test_shiny.R

.gitignore

@@ -41,3 +41,6 @@ vignettes/*.pdf
 # Shinyapps.io information
 rsconnect/
 .lintr
+
+# Generated benchmark measurements
+benchmarks/results/

DESCRIPTION

@@ -0,0 +1,22 @@
+Package: MAniR
+Type: Project
+Title: Interactive Pairwise Matrix Comparison for MALDI-TOF and Genomic Analysis
+Version: 3.0.0
+Authors@R: person("BiKC", role = "aut")
+Description: Shiny application to compare similarity, correlation and distance
+    matrices using scalable visualization, isolate-level metadata and
+    pairwise analytical summaries. The application is run directly from app.R.
+License: GPL-3
+Encoding: UTF-8
+Depends:
+    R (>= 4.2.0)
+Imports:
+    shiny,
+    plotly,
+    htmltools,
+    htmlwidgets,
+    openxlsx,
+    RColorBrewer
+Suggests:
+    data.table,
+    fastcluster

R/example_data.R

@@ -0,0 +1,55 @@
+# Built-in teaching example. All values are synthetic, not measured isolates.
+manir_example_files <- function(root = ".") {
+  c(ANI = file.path(root, "examples", "ani.csv"),
+    MALDI = file.path(root, "examples", "maldi.csv"),
+    metadata = file.path(root, "examples", "metadata.csv"))
+}
+
+manir_load_example <- function(root = ".") {
+  paths <- manir_example_files(root)
+  missing <- paths[!file.exists(paths)]
+  if (length(missing)) {
+    stop("Built-in example files are missing: ",
+         paste(basename(missing), collapse = ", "))
+  }
+  ani <- read_matrix_input(paths[["ANI"]], kind = "similarity")
+  maldi <- read_matrix_input(paths[["MALDI"]], kind = "similarity")
+  matched <- match_matrices(ani, maldi)
+  metadata <- read_metadata_input(paths[["metadata"]])
+  if (!setequal(rownames(metadata), matched$ids)) {
+    stop("Built-in example metadata does not match the matrix identifiers.")
+  }
+  list(first = ani, second = maldi,
+       metadata = align_metadata(metadata, matched$ids))
+}
+
+manir_write_example_workbook <- function(destination, root = ".") {
+  example <- manir_load_example(root)
+  wb <- openxlsx::createWorkbook()
+  for (name in c("ANI", "MALDI")) {
+    m <- if (name == "ANI") example$first else example$second
+    openxlsx::addWorksheet(wb, name)
+    openxlsx::writeData(wb, name,
+      data.frame(sample_id = rownames(m), m, check.names = FALSE))
+    openxlsx::freezePane(wb, name, firstRow = TRUE, firstCol = TRUE)
+  }
+  openxlsx::addWorksheet(wb, "metadata")
+  openxlsx::writeData(wb, "metadata",
+    data.frame(sample_id = rownames(example$metadata),
+               example$metadata, check.names = FALSE))
+  openxlsx::freezePane(wb, "metadata", firstRow = TRUE, firstCol = TRUE)
+  openxlsx::addWorksheet(wb, "README")
+  openxlsx::writeData(wb, "README", data.frame(
+    Notes = c(
+      "MAniR built-in example. All data are SYNTHETIC and intended for demonstration only.",
+      "ANI: fictional percentage-like genomic similarity, diagonal = 100.",
+      "MALDI: fictional spectral similarity on a 0-to-1 scale, diagonal = 1.",
+      "The two matrices use different scales. Do not enable comparable-units metrics.",
+      "Metadata includes three fictional groups, specimen source and measurement batch.",
+      "Two pairs deliberately have discordant MALDI/ANI relationships for exploration.",
+      "Select ANI as matrix 1, MALDI as matrix 2, and metadata as the annotation sheet."
+    ), check.names = FALSE))
+  openxlsx::setColWidths(wb, "README", cols = 1, widths = 100)
+  openxlsx::saveWorkbook(wb, destination, overwrite = TRUE)
+  invisible(destination)
+}