bayesTLS R Package

bayesTLS is an R package for fitting joint Bayesian four-parameter logistic (4PL) models to thermal death time (TDT) and thermal load sensitivity (TLS) data. It works with raw counts or continuous proportions, extracts classical quantities such as z, CTmax, Tcrit, and LT curves as posterior summaries, and provides tools for uncertainty propagation, group contrasts, heat-injury prediction, and bundled case-study data.

Please cite the companion paper when using bayesTLS:

Noble, D.W.A., Arnold, P.A., Nakagawa, S. & Pottier, P. (2026). A flexible modelling framework for estimating thermal tolerance and sensitivity. bioRxiv. https://doi.org/10.64898/2026.07.16.738378

This preprint is the primary citation for both the statistical framework and the bayesTLS package. You can also run citation("bayesTLS") in R for the formatted reference and a BibTeX entry.

The analytical workflow ships as an installable R package, available on CRAN. Install the released version with:

install.packages("bayesTLS")
library(bayesTLS)

To install the development version from GitHub instead:

# install.packages("remotes")  # if needed
remotes::install_github("daniel1noble/bayesTLS")

The package depends on brms (which needs a Stan backend; cmdstanr is recommended). All other imported dependencies (dplyr, ggplot2, MASS, patchwork, posterior, tibble) are CRAN packages and resolve automatically. The classical two-stage beta-binomial Stage 1 additionally uses the suggested glmmTMB package.

The coding workflow is decoupled — each step is a standalone function so users can stop, swap, or skip at any stage:

Full reference: ?fit_4pl, ?tls, ?predict_heat_injury, etc.

Four publicly available datasets are included with the bayesTLS package to make it easier to reproduce analyses and results in the paper and for testing purposes. These datasets are:

Each dataset can be loaded easily using data(aphid_tdt) (as an example of loading the aphid_tdt dataset). If you want other datasets loaded then simply replace aphid_tdt. If you want to learn more about a dataset you can explore it's helpful ?aphid_tdt.

This repository also contains the code needed to reproduce the companion paper, its supplement, and the simulation results. To do this, install the package from this repository, render the Quarto documents through the Makefile, and use the tests to verify the package functions used by the manuscript and supplement. All code chunks are provided in ms/ms.qmd and ms/supplement.qmd; use make supp to render the supplement and scripts/simulations/run_simulations.R to rerun the full two-stage-bias simulation suite. The large cached artifacts the renders read (simulation outputs and brms model fits) are not stored in the repository; make data downloads them from the project's public OSF deposit (see Fetching cached outputs below) so you need not re-fit or re-simulate. Run all scenarios with Rscript scripts/simulations/run_simulations.R, or a subset by passing scenario labels, e.g. Rscript scripts/simulations/run_simulations.R scen9_tmax_060. Each scenario and the per-simulation pipeline are visible in that one script; the reusable building blocks live in scripts/simulations/sim_functions.R.

Use this map to find the files and outputs involved in reproduction:

• Makefile — main entry point for rendering the manuscript and supplement.
• ms/ms.qmd — manuscript source file; renders to _output/ms.html, _output/ms.docx, and _output/ms.pdf.
• ms/supplement.qmd — supplement source file; renders to _output/supp.html, _output/supp.docx, and _output/supp.pdf.
• R/ — package source for the analysis functions used by the paper; see Key functions.
• data/ — bundled package datasets as .rda files.
• inst/extdata/ — source CSV files used to build the bundled datasets.
• data-raw/make_datasets.R — script that rebuilds the .rda datasets from the source CSV files.
• output/models/ — cached brms fits (.rds) created and reused during renders.
• scripts/simulations/ — the two-stage-bias simulation: run_simulations.R (scenarios + runner) and sim_functions.R (reusable building blocks).
• scripts/ — other support scripts (presentation figures, document cleanup).
• tests/testthat/ — fast unit tests plus optional brms integration tests.
• bib/ — bibliography and the Ecology Letters CSL file.
• notes/ — dated development notes for derivations, literature checks, and simulations.
• man/ — roxygen-generated package help files.
• _output/ — final rendered manuscript and supplement files; created by the render commands below.

1. Install the package from this repository so the renders use the same code you are reproducing:

   # install.packages("devtools")  # if needed
   devtools::install()

2. Fetch the cached artifacts the renders read (simulation outputs and brms model fits), which are not stored in the repository:

   make data        # results + model fits (~85 MB) -- enough to render the paper
   make data-full   # ALSO the 2.6 GB raw/draws tier (only to re-aggregate sims)

   make data is safe to re-run: a tier already present locally is skipped. No credentials are needed (the OSF deposit is public).

3. Render the manuscript, supplement, or both from the repository root:

   make all      # manuscript and supplement, all formats
   make ms       # manuscript only: _output/ms.{html,docx,pdf}
   make supp     # supplement only: _output/supp.{html,docx,pdf}

   You can also render one format at a time, for example make ms-pdf or make supp-html.

   The first supplement render may take several minutes because it fits or checks cached models. Subsequent renders reuse the .rds files in output/models/ and should be much faster.

4. Inspect the rendered files in _output/. Use make clean to remove only _output/, or make build-clean to also remove the out-of-tree Quarto build cache at ~/Library/Caches/tls-render/.

The simulation outputs and brms model fits the manuscript reads are large and are not committed to the repository. They live in the project's public OSF deposit (node c6dxy) as tiered zip archives, fetched with make data:

make data is idempotent — a tier already present under output/ is skipped (pass TIER=--force to re-download), each download is md5-verified against data-raw/osf_manifest.json, and the archives unpack straight into output/. No credentials are required. Maintainers refresh the deposit with make osf-push (needs an OSF_PAT token); see scripts/osf_publish.R.

4. Run the package tests if you want to verify the analysis functions separately from the manuscript render:

   devtools::test()
   
   Sys.setenv(RUN_BRMS_TESTS = "true")
   devtools::test()

   The first command runs the fast unit tests. The second also runs the gated brms integration tests, which fit small cached models and check parameter recovery.

The manuscript and supplement are independent Quarto documents. There is no project-level _quarto.yml; each .qmd file carries its own YAML so the files can be rendered separately. The Makefile renders outside the Dropbox-synced project directory, then copies only the final HTML, DOCX, and PDF files back to _output/. This avoids conflicted intermediate files while preserving cached model fits in output/models/.

Within a document, use Quarto's @ references as normal (@fig-X, @tbl-X, @eq-X, @sec-X). Between the manuscript and supplement, use plain text, such as "Equation 7 of the manuscript" in the supplement or "Figure S2" in the manuscript. The supplement render automatically labels figures, tables, and equations with an "S" prefix.

See CLAUDE.md §8a for more detail on the render architecture, cross-reference handling, and the brms cache.

The supplement works through the same workflow on simulated data and four empirical examples:

1. Brown shrimp — lethal and sublethal endpoints.
2. Zebrafish — lethal TDT across life stages, fit as separate per-stage 4PLs and as a joint model with life_stage as a covariate.
3. Snow gum leaf PSII — continuous-proportion response fit with a Beta likelihood.
4. Drosophila suzukii — multi-trait TDT data, including mortality, knockdown, and fertility endpoints.

The supplement also contains the two-stage-bias simulation results and sensitivity sweeps used to check the modelling framework.