ReadMe

waterpyk

A python package to analyze hydrological timeseries for a site or watershed using the Google Earth Engine and USGS APIs.

• GitHub repo: https://github.com/erica-mccormick/waterpyk

• Documentation: https://waterpyk.readthedocs.io/en/latest/

• PyPI: https://pypi.org/project/waterpyk/

• Report bugs: https://github.com/erica-mccormick/waterpyk/issues

waterpyk is a simple package for extracting data from the Google Earth Engine (GEE) and USGS APIs and performing simple water-balance analyses. All you need to begin is a lat/long or a USGS gauge ID to start.

For more information on the root-zone water storage capacity and deficit, see Dralle et al., 2021, McCormick et al., 2021, and Rempe, McCormick et al. (in prep).

Check out the tutorial for basic waterpyk usage in GoogleColab here.

Get Started

waterpyk requires geopandas and ee. Read the workflow to install and authenticate ee (GEE) for Google Colab, pip, or conda. You will need to sign up for a GEE account if it is your first time.

Install waterpyk:

pip install waterpyk

To get all of the available data and plots for a site, simply supply a list of coordinates (such as [lat, long] or [gaugeID]).:

from waterpyk install main

coords = [LAT/LONG] # or
gage = [USGS_gage_ID]
yoursitename = main.StudyArea(COORDS_or_GAGE, layers = 'all')

A note on the layers parameter: Two default options are available for extracting data.:

layers = 'all'
layers = 'minimal'

‘All’ will extract precipitation (P), evapotranspiration (ET) from MODIS and PML, MODIS snow cover, MODIS landcover class, and SRTM elevation, including all relevant bands.

‘Minimal’ is the fastest option and extracts only the necessary data for the deficit (P, ET, and snow without extra MODIS products).

Alternatively, layers can also take a dataframe containing a row for each desired GEE asset. See the main and/or gee module docs for more information.

Note that most GEE assets should be extracted with no errors, however not all date formats have been tested, so new assets may throw errors and require manual extraction outside of waterpyk. For these cases, I suggest using the geemap package, which has many fantastic GEE tools and inspired some of this code as well!

Now that you’ve initialized your StudyArea object, all of the dataframes of extracted data will now be available in the form of:

yoursitename.daily_df_wide # includes deficit, wateryear deficit, and cumulative wateryear timeseries
yoursitename.streamflow
yoursitename.wateryear_totals
yoursitename.stats

Some single values are also available as attributes in this way, such as root-zone water storage capacity (Smax, mm) and and mean annual precipitation (MAP, mm):

yoursite.smax
yoursite.MAP

To plot, supply a string for which kind of plot (see below for the 5 options), such as:

yoursitename.plot(kind = 'timeseries')

Extra keyword arguments are available for the plots to change the color, line types, or included data for each kind. See the plots module for default kwargs.

Docs

For full documentation, see full documentation.

What Waterpyk Can Do

• Download timeseries of GEE assets and:

  • Combining bands

  • Applying a scaling factor

  • Interpolating to daily

• Download streamflow for gauged watersheds

• Download watershed information, such as:

  • Boundary and flowline geometry (as GEE or geopandas format)

  • Metadata (such as CRS, name, and gauge ID)

  • Daily discharge (in native units, and converted to mm)

  • Centroid latitude (for calculation of Hargreaves PET)

  • URLs necessary to access all of the above directly

• Calculate cumulative and total wateryear timeseries

• Calculate the root-zone water storage (RWS) deficit

• Create 4 figures, out of the box, with P, ET, Q, and deficit data, including:

  • Wateryear cumulative timeseries (kind = 'wateryear')

  • Daily timeseries, with options (kind = 'timeseries')

  • Plot & calculate Spearman correlation coefficient for summer ET and wateryear P (kind = 'spearman')

  • RWS capacity (Smax) relative to P distribution (kind = 'distribution')

  • RWS timeseries (kind = 'RWS')

Contact

This is a work in progress and is primarily intended for the Rempe Lab Group and co-authors. Feel free to report bugs, and note that major version updates may not be backwards compatible. For more information, contact Erica McCormick at erica.elmstead@gmail.com or the email address given on her homepage.