Appendix A — Running the book
Everything is in book/ of mdsumner/r-variants. A render runs each script in book/scripts under both builds of R and writes the tables. Nothing is cached between renders.
| Path | What it is |
|---|---|
scripts/NN-name.R |
one example each; runnable alone with Rscript |
scripts/_bench.R |
the measuring helper the scripts share |
R/book.R |
runs a script under each build and makes the tables |
results/*.csv |
the rows from the last successful run of each script |
results/*.log |
each script’s output per build (not committed) |
docker/Dockerfile |
the book image |
run.sh |
the render command |
pawsey/render.slurm |
the same, as a Slurm job for Setonix |
A.1 The image
ghcr.io/mdsumner/r-variants:book starts from the published array-subset image, which has patched R-devel in /opt/R/variant. It adds stock R-devel in /opt/R/baseline, built from the same R-devel commit the patched image records, so the two builds differ by the patch and nothing else. The same altarr (exp/r-hook) and zaro are installed into each, and Quarto. The book workflow in the repository builds the image, renders the book in it as a test, and publishes it when asked (Actions, book, Run workflow, publish).
The same workflow can publish the book it rendered to GitHub Pages: tick pages when running it. That needs Pages set to “GitHub Actions” as its source, once, in the repository’s settings.
To move the book to a newer R-devel, rebuild and publish the array-subset variant first, then the book image. The preface prints what each build is.
A.2 On Pawsey (Setonix)
Compute nodes on Setonix can reach the internet, which is why the book runs there: the live chapters read from Copernicus, NCI and GitHub during the job.
Once:
cd $MYSCRATCH
git clone https://github.com/mdsumner/r-variantsEach run, from the top of the clone:
git pull
sbatch --account=$PAWSEY_PROJECT book/pawsey/render.slurmThe job pulls the image to $MYSCRATCH/altarr-book/book.sif the first time, renders, and leaves the book in book/_book/ and the result rows in book/results/. Its log is altarr-book-<jobid>.log where you submitted. To keep a run, commit the result rows:
git add book/results/*.csv && git commit -m "Book results, Setonix, $(date +%F)"Settings, all optional, passed with sbatch --export=ALL,NAME=value:
| Variable | Default | Meaning |
|---|---|---|
BOOK_MODE |
live |
offline skips the scripts that need the network |
BOOK_PULL |
unset | 1 pulls the image again (after it is rebuilt) |
BOOK_MAX_CON |
8 |
connection cap for the Copernicus and EOPF chapters |
BOOK_THREDDS_CON |
4 |
connection cap for reads from NCI THREDDS |
BOOK_TRIES, BOOK_RETRY_WAIT |
3, 60 |
attempts at a read that fails, and seconds between them |
BOOK_PAUSE |
60 |
seconds between the two builds on a live script |
BOOK_LATENCY |
0.05 |
seconds per fetch call in the simulated stores |
BOOK_SIF |
$MYSCRATCH/altarr-book/book.sif |
where the image is kept |
BOOK_SINGULARITY_MODULE |
pawseyenv/2025.08 singularity/4.1.0-slurm |
modules to load, in order; module spider singularity shows what a release needs |
To render one chapter, pass it after the mode:
sbatch --account=$PAWSEY_PROJECT book/pawsey/render.slurm live 04-virtual.qmdA.3 Anywhere with Docker
On a laptop, a Nimbus instance or any machine with Docker, from the top of a clone:
docker run --rm -v "$PWD:/work" -w /work/book \
ghcr.io/mdsumner/r-variants:book bash run.sh # live
docker run --rm -v "$PWD:/work" -w /work/book \
ghcr.io/mdsumner/r-variants:book bash run.sh offline # no networkA.4 One script, by hand
Inside the image, from book/:
/opt/R/baseline/bin/Rscript scripts/04-virtual.R # stock R-devel
/opt/R/variant/bin/Rscript scripts/04-virtual.R # patchedOutside the image the scripts run with any R that has altarr and zaro; point BOOK_R_STOCK and BOOK_R_PATCHED at two Rscript binaries to render the book against other builds.
A.5 Adding an example
- Write
scripts/NN-name.R: source_bench.R, open a lazy array, wrap each read inbench("label", x, expr), end withfinish(). - In a chapter, show it with a
file:chunk and run it withbook_run("NN-name.R", live = TRUE)thenbook_table(res). - Keep files ASCII.