Skip to contents

Package architecture and validation-data policy

package_architecture.Rmd

dhw has three layers. Their separation is primarily about scientific responsibility and dependencies; users still install one package.

Core

The core converts dated SST rasters into NOAA-style monthly climatology, MMM, daily climatology, anomaly, HotSpot, DHW, and BAA products. Core functions are deterministic, require no network connection, preserve missing observations, and are tested against compact committed NOAA reference fixtures.

Data access

Download and processing functions connect the core to NOAA CoralTemp, OISST, ERA5, and external spatial data. Provider-specific dependencies are optional: the package explains what to install only when one of these functions is used. Downloads use temporary files, retries, HTTP validation, and atomic moves so a failed response cannot masquerade as a valid NetCDF file.

Analysis

Reef extraction, hindcasting, general SST metrics, summaries, and plotting are downstream analysis. These functions must not silently change core meanings; in particular, missing DHW remains missing unless a caller explicitly requests legacy zero replacement.

Monthly heat-stress metrics also belong to this layer and are deliberately separated because two published quantities have often been given similar names:

  • calculate_dhm() implements the rolling three- or four-month method used by Mason, Bozec and Mumby (2025). It requires an external MMM. Set alignment = "matlab_previous", incomplete = "matlab_zero", and conversion = "weekly_4" to reproduce the supplied MATLAB workflow and its approximate degree-week output.
  • calculate_dhmi_lough() implements Lough, Anderson and Hughes (2018): positive anomalies are summed over complete 12-month thermal years and each cell/site is divided by the standard deviation of its 1961–1990 annual totals.

The older calculate_dhmi() name is deprecated because it mixed these definitions. It remains only as a temporary compatibility bridge.

dhm <- calculate_dhm(
  monthly_sst, observational_mmm,
  window = 3,
  alignment = "matlab_previous",
  incomplete = "matlab_zero",
  conversion = "weekly_4",
  output = "annual_max"
)

lough_dhmi <- calculate_dhmi_lough(
  monthly_sst,
  reference_period = c(1961, 1990),
  year_start_month = 1
)

Validation data

There are two distinct types of validation data:

  1. Compact immutable fixtures live in inst/extdata. They are sufficient for fast, deterministic, offline unit tests and include exact source metadata.
  2. Regional and global source rasters are optional downloads. They belong in a user cache such as validation-data/, which is ignored by Git, or in an external archival release/DOI store—not inside the installed package.

Run the reproducible regional workflow with:

system2("Rscript", c(
  "data-raw/validate_noaa_regional_tile.R",
  "--cache=validation-data/noaa-florida-keys"
))

The cache contains downloaded NetCDF files and reports with checksums. Deleting it never removes a required package test fixture; it only forces a fresh source download on the next full validation run.