Section 1 Introduction

The EcoSHEDS northeast stream temperature model was developed to predict daily stream temperatures at both gaged and ungaged catchments across the northeast U.S. based on geospatial characteristics and weather conditions.

The model is based on a linear mixed effects framework that accounts for spatial and temporal correlations using a hierachical Bayesian structure. Letcher et al. (2016) describe the initial development of this model framework, and apply it to a small region in western Massachusetts. See the Model Overview section below for a brief introduction to the model, or the Theory section a more detailed explanation.

The documentation is divided into the following sections:

  1. Introduction : provides an overview the stream temperature model and documentation, as well as a snapshot of the current calibration
  2. Theory : describes how the model works including the underlying structure and theory
  3. Data Sources : describes the datasets used as inputs to the model
  4. Data Processing : describes how input datasets are processed prior to model fitting (i.e. QAQC procedures)
  5. Calibration and Validation : describes how well the model predicts stream temperature based on observations that were included (calibration) and excluded (validation) from the model fitting process
  6. Predictions : describes how predictions are generated after the model is calibrated and describes the various summary metrics that are computed for each catchment
  7. Download : provides links to download the model predictions, catchment delineation (shapefiles), and covariates dataset.

The model will be periodically updated and re-calibrated (approximately once every 6 months) to incorporate any new temperature observations, and to make any necessary revisions to the data processing and/or model structure. With each update, a new version will be assigned to the model, and this documentation website will be updated to reflect the most recent performance of the model. A brief summary of the changes associated with each new version is provided in the Change Log below.

1.1 Model Overview

The SHEDS stream temperature model predicts daily mean stream temperature based on geospatial characteristics and daily weather conditions. Predictions are made at a relatively fine spatial resolution based on a customized catchment delineation (average size about 2 km2) across the northeast U.S. from Maine to Virginia. Predictions are limited to streams and rivers with drainage areas less than 200 km2. Heavily impounded rivers are also excluded from the model.

The model uses a hierarchical Bayesian structure to account for spatial correlation in temperature between near-by locations through random effects for both the individual catchments and the larger watershed (HUC8) containing that catchment. Therefore, catchments within the same HUC8 watershed share a set of HUC-specific coefficients. Year to year variations in temperature are also accounted for using a random effect for the year.

1.2 Current Snapshot

Table 1.1 provides a snapshot of the calibration and validation performance for the current version of the model (v1.4.0). More details about the model performance can be found in the Calibration and Validation section.

Table 1.1: Summary statistics of model calibration and validation
Calibration Validation
# Daily Observations 705,509 80,035
# Time Series 7,814 863
# Catchments 2,971 566
# HUC8s 144 109
# Years 31 27
RMSE (degC) 1.061 1.342
Mean Residual (degC) 0.061 0.079
Median Residual (degC) 0.075 0.062
Mean Absolute Residual (degC) 0.813 1.021
Median Absolute Residual (degC) 0.649 0.805
Minimum Residual (degC) -7.570 -7.665
1st Percentile Residual (degC) -2.674 -3.225
99th Percentile Residual (degC) 2.659 3.697
Maximum Residual (degC) 9.196 7.411

1.3 Model Versioning

The SHEDS stream temperature model uses semantic versioning of the form: vX.Y.Z

  • X is the major version, which will be incremented when there is a major change to the model theory, code, or datasets.
  • Y is the minor version, which will be incremented when there is a new set of results due to changes in the model code, datasets, processing procedures, etc.
  • Z is the patch version, which will be incremented only when there is a change to the documentation or code that does not yield different results.

1.4 Source Code

The source code for the model itself and this documentation is available in the Github repository ecosheds/northeast-temp-model. Each version of the model will be included under the list of Releases.

1.5 Change Log

  • v1.4.0 (Jan 3, 2024)
    Add 2021-2022 daymet, add stream temperature data from USGS NWIS, re-calibrate full model.
  • v1.3.0 (Sep 7, 2021)
    Add 2020 daymet, revise data screening procedures, re-calibrate full model.
  • v1.2.0 (Jul 10, 2020)
    Add 2019 daymet, re-calibrate full model.
  • v1.1.1 (Jan 16, 2020)
    Add air temperature scenarios (+2, +4, +6 degC), and # days >= 24.9 and 27 degC to prediction derived metrics.
  • v1.1.0 (Dec 2, 2019)
    Add 2018 daymet data, re-calibrated full model.
  • v1.0.2 (Mar 26, 2019)
    Update documentation, add Download section containing links to model predictions, catchment delineation, and covariates.
  • v1.0.1 (Dec 10, 2018)
    Update documentation, remove auto-correlation term from goodness-of-fit summaries
  • v1.0.0 (Oct 25, 2018)
    Re-calibrated model, and finished documentation.
  • v0.9.2 (Jul 6, 2018)
    Major updates to documentation (introduction, theory, calibration and validation sections).
  • v0.9.1 (Jun 6, 2018)
    Updates to model versioning and configuration framework, and minor updates to documentation (still incomplete).
  • v0.9.0 (May 30, 2018)
    Preliminary release of the new model framework and documentation.
  • Previous Versions (prior to 2018)
    Previous versions of the stream temperature model can be found here. That website is now deprecated, but will remain available for future reference. Beginning with v1.0.0 of the new framework and codebase, all model changes and results will be tracked and made available.

References

Letcher, Benjamin H., Daniel J. Hocking, Kyle O’Neil, Andrew R. Whiteley, Keith H. Nislow, and Matthew J. O’Donnell. 2016. “A Hierarchical Model of Daily Stream Temperature Using Air-Water Temperature Synchronization, Autocorrelation, and Time Lags.” PeerJ 4: e1727. https://doi.org/10.7717/peerj.1727.