tsgettoolbox and tstoolbox - Python Programming Interface#
‘tsgettoolbox nwis …’: Download data from the National Water Information System (NWIS)#
This notebook is to illustrate the Python API usage for ‘tsgettoolbox’ to download and work with data from the National Water Information System (NWIS). There is a different notebook to do the same things from the command line called tsgettoolbox-nwis-cli. The CLI version of tsgettoolbox can be used from other languages that have the ability to make a system call.
[1]:
%matplotlib inline
[2]:
# Third party imports
from tstoolbox import tstoolbox
# First party imports
from tsgettoolbox import tsgettoolbox
Let’s say that I want flow (parameterCd=00060) for site ‘02325000’. All of the tsgettoolbox functions create a pandas DataFrame.
[3]:
df = tsgettoolbox.nwis_dv(
sites="02325000", startDT="2000-01-01", endDT="2010-01-01", parameterCd="00060"
).convert_dtypes()
[4]:
df.head() # The .head() function gives the first 5 values of the time-series
[4]:
| USGS_02325000_26719_00060_00003 | |
|---|---|
| Datetime | |
| 2000-01-01 | 82.0 |
| 2000-01-02 | 81.0 |
| 2000-01-03 | 80.0 |
| 2000-01-04 | 79.0 |
| 2000-01-05 | 75.0 |
‘tstoolbox …’: Process data using ‘tstoolbox’#
Now lets use “tstoolbox” to plot the time-series. The ‘input_ts’ option is used to read in the time-series from the DataFrame.
[5]:
df = df.astype("float64")
df
[5]:
| USGS_02325000_26719_00060_00003 | |
|---|---|
| Datetime | |
| 2000-01-01 | 82.0 |
| 2000-01-02 | 81.0 |
| 2000-01-03 | 80.0 |
| 2000-01-04 | 79.0 |
| 2000-01-05 | 75.0 |
| ... | ... |
| 2009-12-28 | 153.0 |
| 2009-12-29 | 153.0 |
| 2009-12-30 | 151.0 |
| 2009-12-31 | 150.0 |
| 2010-01-01 | 148.0 |
3654 rows × 1 columns
[13]:
tstoolbox.plot(input_ts=df, ofilename="flow.png")
[13]:
<module 'matplotlib.pyplot' from '/home/tim/anaconda3/envs/default311/lib/python3.11/site-packages/matplotlib/pyplot.py'>
‘tstoolbox plot’ has many options that can be used to modify the plot.
[12]:
tstoolbox.plot(
input_ts=df,
ofilename="flow_api.png",
ytitle="Flow (cfs)",
title="02325000: FENHOLLOWAY RIVER NEAR PERRY, FLA",
legend=False,
)
[12]:
<module 'matplotlib.pyplot' from '/home/tim/anaconda3/envs/default311/lib/python3.11/site-packages/matplotlib/pyplot.py'>
[14]:
mdf = tstoolbox.aggregate(input_ts=df, agg_interval="M", statistic="mean")
[15]:
tstoolbox.plot(input_ts=mdf, drawstyle="steps-pre", ofilename="flow_api_monthly.png")
[15]:
<module 'matplotlib.pyplot' from '/home/tim/anaconda3/envs/default311/lib/python3.11/site-packages/matplotlib/pyplot.py'>