Section 1 Introduction

The SHEDS stream temperature model was developed to predict daily stream temperatures at both gauged and un-gauged 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

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 resultion 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 (v0.9). 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 (values in parentheses denote value when temporal auto-correlation term is excluded)
Calibration Validation
# Observations 546,051 60,715
# Time Series 6,442 679
# Catchments 2,463 465
# HUC8s 138 94
# Years 27 22
RMSE (degC) 0.623 (1.111) 0.668 (1.469)
Mean Residual (degC) 0.007 (0.062) 0.016 (0.120)
Median Residual (degC) 0.009 (0.077) 0.013 (0.114)
Mean Absolute Residual (degC) 0.464 (0.840) 0.495 (1.082)
Median Absolute Residual (degC) 0.359 (0.663) 0.383 (0.838)
Minimum Residual (degC) -8.463 (-10.395) -7.824 (-12.045)
1st Percentile Residual (degC) -1.602 (-2.809) -1.696 (-3.550)
99th Percentile Residual (degC) 1.592 (2.834) 1.744 (3.998)
Maximum Residual (degC) 7.542 (13.373) 6.916 (11.046)

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 walkerjeffd/sheds-temp-model. Each version of the model will be included under the list of Releases.

1.5 Change Log

  • 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.


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. doi:10.7717/peerj.1727.