Getting started with the SBT 2026 assessment

Clone, install, update, and render the accepted ESC31 workflow

ImportantBefore you begin

Ask a quantifish administrator to give your GitHub account access to the private quantifish/sbt2026, quantifish/sbt, and quantifish/sbtdata repositories. These instructions restore the frozen software environment and use accepted fit objects; they do not refit a model or start MCMC.

1. Install the prerequisites

Install Git, R 4.6.1, Quarto 1.10.18, and the normal R package compilation tools for your operating system. Installing GitHub CLI is strongly recommended.

Authenticate Git and confirm access to all three repositories:

gh auth login --web --git-protocol https
gh auth setup-git
gh repo view quantifish/sbt2026
gh repo view quantifish/sbt
gh repo view quantifish/sbtdata

Store a GitHub credential for R package installation. Use a fine-grained token with read access to all three repositories, or a classic token with repo scope. Never save the token in a script or QMD file.

install.packages(c("gitcreds", "renv"))
gitcreds::gitcreds_set()

2. Clone and install

Choose a working directory, then clone only the assessment repository. The locked environment installs the exact sbt and sbtdata versions; ordinary assessment users do not need separate source checkouts.

mkdir -p ~/Projects/CCSBT
cd ~/Projects/CCSBT
git clone https://github.com/quantifish/sbt2026.git
cd sbt2026
Rscript scripts/restore-renv.R

The restore helper installs the packages recorded in renv.lock, including the pinned GitHub packages and the external header needed by compResidual. It then checks that the resulting project library exactly matches the lockfile.

3. Check the installation

From the sbt2026 repository root, run the lightweight clean-clone check:

Rscript scripts/check-clean-clone.R

You can also verify the central packages in R:

stopifnot(
  requireNamespace("sbt", quietly = TRUE),
  requireNamespace("sbtdata", quietly = TRUE)
)

sbtdata::sbt_data_releases()
sbtdata::sbt_data_manifest("2026")$release
quarto::quarto_version()

4. Render the accepted base assessment

Run Quarto from the repository root:

quarto render ESC31/2_base.qmd

Open ESC31/2_base.html in a browser. The tracked ESC31/runs/esc31_base.rds contains the accepted MLE and posterior. A normal render reads that checkpoint; do not set any ESC31_RUN_* environment variable unless you have deliberately agreed to replace an accepted assessment result.

The published pages can be read at quantifish.co.nz/sbt2026. Some full sensitivity, MLE-grid, MSY, and projection reruns also require large accepted artefacts held separately from Git; see runs/README.md before attempting those workflows.

Pulling later updates

First confirm that you have no uncommitted work, then update main, restore any lockfile changes, and repeat the lightweight check:

git status --short
git switch main
git pull --ff-only
Rscript scripts/restore-renv.R
Rscript scripts/check-clean-clone.R

If git status --short prints anything, commit the work on a branch before pulling. Do not discard or overwrite local files merely to update the clone.

Contributing through a pull request

Do not push directly to main. Start from an up-to-date branch, commit only the intended files, and open a pull request:

git switch main
git pull --ff-only
git switch -c initials/brief-description

# Make and check the change, then:
git add <files-you-changed>
git commit -m "Brief description of the change"
git push -u origin HEAD
gh pr create --web
NoteCommon problems
  • GitHub reports 401 or 404: confirm repository access in a browser, then repeat gh auth login and gitcreds::gitcreds_set().
  • A package will not compile: install the R development toolchain for your operating system, then rerun Rscript scripts/restore-renv.R.
  • Files cannot be found: run commands from the sbt2026 repository root.
  • The library differs from the lockfile: run renv::status() for details, then rerun the restore helper rather than installing arbitrary newer package versions.