Snow-to-Flow Regression Notebook for the Logan River, Utah, Updated for Changes in NRCS SNOTEL Data Services

Purpose

This resource provides a Jupyter notebook that develops a simple linear regression model to predict annual maximum daily discharge at USGS gage 10109000 (Logan River above State Dam, near Logan, Utah) from annual maximum snow water equivalent (SWE) at NRCS SNOTEL site 823 (Tony Grove Lake).

This resource contains an updated version of HydroShare_SnowtoFlow_Notebook.ipynb, originally published in the HydroShare resource below and described in the accompanying journal article:

• Horsburgh, J. S. (2025). Supporting Materials for: Advancing Open and Reproducible Water Data Science by Integrating Data Analytics with an Online Data Repository, HydroShare, https://doi.org/10.4211/hs.7440c7feae1f428d91c1e510d23d3e54
• Horsburgh, J. S., Black, S., Castronova, A., & Dash, P. K. (2025). Advancing open and reproducible water data science by integrating data analytics with an online data repository. Environmental Modelling & Software, 188, 106422. https://doi.org/10.1016/j.envsoft.2025.106422

This resource updates only the snow-to-flow notebook. The two hsclient notebooks in the original resource are not included here.

This resource also serves as a worked example of how a published notebook can fail and be repaired after changes in data services and computing environments, in:

• Salehabadi, H., Garousi-Nejad, I., Castronova, A., Tarboton, D., Dash, P., Horsburgh, J. S., & Nassar, A. (in preparation). Ten practical rules for future-proofing notebook-based computational workflows in water science. To be submitted to PLOS Water.

This citation will be updated with the full reference and DOI once the paper is published.

What changed and why

The original notebook stopped working after publication because of changes outside the authors' control. This version makes the following changes:

1. Minimal fix to the original SNOTEL retrieval. The NRCS Report Generator now returns files with more comment lines than the 59 rows the original code skipped. The fixed code skips lines beginning with # instead of a fixed number of rows. The original code is retained in a markdown cell for reference but is not executed.
2. Alternative retrieval using the NRCS AWDB REST API. This is a documented interface designed for machine access, and is a more sustainable choice than parsing the output of a report tool.
3. Matching periods of record. The REST API retrieval requests data through the current date. The SWE record is therefore limited to the end of the streamflow record before it is saved, because the regression requires both records for the same years.
4. Software environment. The notebook has a dependency on the dataretrieval. Library. In many cases this can be installed using with pip. However in one of our test environments this fails and a Conda environment specification and setup script are now provided as a fallback for such platforms (see Software requirements below).
5. Archival mode reader. The archived snotel.csv is now also read by skipping comment lines rather than a fixed number of rows.

The regression method and the archived input data are unchanged.

Resource contents

• HydroShare_SnowtoFlow_Notebook.ipynb: the updated notebook.
• discharge.csv: streamflow data retrieved when the original notebook was first run, copied from the original resource.
• snotel.csv: SWE data retrieved when the original notebook was first run, copied from the original resource.
• conda_env/environment.yml: specification of the Conda environment used for testing.
• conda_env/setup_jupyterhub_conda_env.sh: script that creates the Conda environment and registers it as a Jupyter kernel.
• conda_env/delete_jupyterhub_conda_env.sh: script that removes the environment and kernel.
• readme.md: this file.

Data and modes of use

The notebook can be run in two modes, selected with the use_original_data flag in the Regression Analysis section:

• Archival mode (use_original_data = True, the default): uses the included discharge.csv and snotel.csv to reproduce the published regression. The regression itself needs no network access, although the earlier retrieval cells still contact the data services.
• Live mode (use_original_data = False): uses data retrieved when the notebook runs. Results will differ from the published values as new years are added and as USGS revises provisional and approved data.

Each retrieval saves its data to a CSV file. If discharge.csv or snotel.csv already exists, a new file with the date and time appended to its name is written, so the archived files are never overwritten.

Data sources:

• Daily mean discharge (parameter 00060) for USGS gage 10109000, from the USGS National Water Information System, retrieved with the dataretrieval Python package. Requested period: 1953-10-01 onward.
• Daily SWE (element WTEQ) for SNOTEL site 823 (station triplet 823:UT:SNTL), from the NRCS Report Generator and the NRCS AWDB REST API (https://wcc.sc.egov.usda.gov/awdbRestApi/swagger-ui/index.html). Requested period: 1972-05-01 onward.

Software requirements

The notebook requires Python with numpy, pandas, scipy, matplotlib, and dataretrieval. The other modules used (urllib, os, json, datetime, and ssl) are part of the standard Python library.

Try the following approaches in order:

1. Default environment with pip. Open the notebook in the platform's default environment and run it from the top. The first code cell installs or updates dataretrieval with pip. If the import cell that follows succeeds, continue with the rest of the notebook.
2. Dedicated Conda environment. If the pip cell fails (for example with a permission error), or the imports fail (for example with a message that a module compiled using NumPy 1.x cannot be run in NumPy 2.x), do not try to fix the default environment by installing further packages. Instead, create a dedicated Conda environment from conda_env/environment.yml, which specifies tested versions of the required packages. On a HydroShare-linked JupyterHub:
3. Open this resource using HydroShare's "Open With" function.
4. Open a terminal in the resource folder.

5. Run:

   chmod +x conda_env/setup_jupyterhub_conda_env.sh ./conda_env/setup_jupyterhub_conda_env.sh snowflow

6. Switch the notebook's kernel to the snowflow environment, skip the pip cell, and run the rest of the notebook.

If the JupyterHub keeps user files between sessions, the environment only needs to be created once. Step-by-step instructions are provided in Salehabadi, H., D. Tarboton, P. Dash (2026), Creating a Conda Environment for Future-Proofing Jupyter Notebooks to Support Computational Reproducibility, HydroShare, http://www.hydroshare.org/resource/1c5fd6dd6b0c4fb4b5f65cce35550a38. Outside HydroShare linked platforms, create and activate the environment with:

conda env create -f conda_env/environment.yml conda activate snowflow

If a pip install has already changed the default environment and the imports still fail, restarting the JupyterHub server (not just the kernel) may restore the platform's original environment.

Tested environments

Not tested: local Windows, macOS, or Linux installations; other JupyterHub platforms; and the default environments of either platform after the dates above.

Checking a run

A successful run in archival mode should reproduce the following values. If a run completes but gives different values, check that use_original_data = True and that discharge.csv and snotel.csv are the original files.

Assumptions and limitations

• Annual maxima are taken over calendar years (January 1 to December 31). The first year of SWE data is skipped, because the record begins partway through a snow season.
• The regression requires SWE and streamflow data for the same years. In live mode, the SWE record is limited to the end of the streamflow record.
• The model is a single-predictor linear regression intended as a teaching and demonstration example, not as an operational forecasting tool.

External dependencies outside the authors' control

The notebook depends on the following, any of which may change:

• the USGS NWIS web services and the dataretrieval package that accesses them
• the NRCS Report Generator and the NRCS AWDB REST API
• the JupyterHub platforms and images on which the notebook is run
• HydroShare's "Open With" integration with those platforms

If a data service changes, archival mode can still be used to reproduce the published regression from the included CSV files.

Maintenance status

This resource reflects a one-time repair, tested on the dates above. It is maintained on a best-effort basis: the author may release further fixes if the data services change, but does not guarantee them. Any update will be released as a new version of this resource and linked from this page, so check for a newer version before use. Please report problems to the contact below.

Use of AI assistance

Diagnosis of the failures and drafting of the revised code were assisted by an AI coding assistant (Anthropic Claude). All changes were reviewed, tested, and verified against the original archived data by the author.

Authors and contact

• Original notebook: Jeffery S. Horsburgh (jeff.horsburgh@usu.edu)
• Updates: David Tarboton (david.tarboton@usu.edu)

How to cite

• Horsburgh, J. S., Tarboton, D. G. (2026). Snow-to-Flow Regression Notebook for the Logan River, Utah, Updated for Changes in NRCS SNOTEL Data Services, HydroShare, http://www.hydroshare.org/resource/855b50938ec6498997a72586673c41d3

Please also cite the original resource (Horsburgh, 2025) and article (Horsburgh et al., 2025). If you use this resource as an example of notebook repair or future-proofing, please cite Salehabadi et al. (in preparation). All three are listed under Purpose.

Funding

This work was supported by the Cooperative Institute for Research to Operations in Hydrology (CIROH) with funding under award NA22NWS4320003 from the NOAA Cooperative Institute Program.