Python Equivalents to R Vignette Examples
[1]:
from dataretrieval import nwis, waterdata, wqp
The dataRetrieval package was created as a python equivalent to the R dataRetrieval tool.
The following shows python equivalents for methods outlined in the R dataRetrieval Vignette with the equivalent R code in comments
[2]:
"""
library(dataRetrieval)
# Choptank River near Greensboro, MD
siteNumber <- "01491000"
ChoptankInfo <- readNWISsite(siteNumber)
parameterCd <- "00060"
#Raw daily data:
rawDailyData <- readNWISdv(siteNumber,parameterCd,
"1980-01-01","2010-01-01")
# Sample data Nitrate:
parameterCd <- "00618"
qwData <- read_USGS_samples(monitoringLocationIdentifier=sprintf("USGS-%s", siteNumber),usgsPCode=parameterCd,
activityStartDateLower="1980-01-01", activityStartDateUpper="2010-01-01")
pCode <- readNWISpCode(parameterCd)
"""
# Choptank River near Greensboro, MD
siteNumber = "01491000"
chop_tank_info, md = nwis.get_info(sites=siteNumber)
parameterCd = "00060"
# raw daily data
rawDailyData, md = nwis.get_dv(
sites=siteNumber, parameterCd=parameterCd, start="1980-01-01", end="2010-01-01"
)
# sample data Nitrate:
parameterCd = "00618"
samples_data, md = waterdata.get_samples(
monitoringLocationIdentifier=f"USGS-{siteNumber}",
usgsPCode=parameterCd,
activityStartDateLower="1980-01-01",
activityStartDateUpper="2010-01-01",
)
pCode, md = nwis.get_pmcodes(parameterCd=parameterCd)
---------------------------------------------------------------------------
ValueError Traceback (most recent call last)
Cell In[2], line 39
31 parameterCd = "00618"
32 samples_data, md = waterdata.get_samples(
33 monitoringLocationIdentifier=f"USGS-{siteNumber}",
34 usgsPCode=parameterCd,
35 activityStartDateLower="1980-01-01",
36 activityStartDateUpper="2010-01-01",
37 )
---> 39 pCode, md = nwis.get_pmcodes(parameterCd=parameterCd)
File /opt/hostedtoolcache/Python/3.13.12/x64/lib/python3.13/site-packages/dataretrieval/nwis.py:863, in get_pmcodes(parameterCd, partial, ssl_check)
858 if len(response.text.splitlines()) < 10: # empty query
859 raise TypeError(
860 "One of the parameter codes or names entered does not"
861 "return any information, please try a different value"
862 )
--> 863 return_list.append(_read_rdb(response.text))
864 else:
865 raise TypeError("Parameter information (code or name) must be type string")
File /opt/hostedtoolcache/Python/3.13.12/x64/lib/python3.13/site-packages/dataretrieval/nwis.py:1350, in _read_rdb(rdb)
1335 """
1336 Convert NWIS rdb table into a ``pandas.dataframe``.
1337
(...) 1347
1348 """
1349 if "<html>" in rdb.lower() or "<!doctype html>" in rdb.lower():
-> 1350 raise ValueError(
1351 "Received HTML response instead of RDB. This often indicates "
1352 "that the service has been moved or is currently unavailable."
1353 )
1355 count = 0
1357 for line in rdb.splitlines():
1358 # ignore comment lines
ValueError: Received HTML response instead of RDB. This often indicates that the service has been moved or is currently unavailable.
[3]:
"""
{r getSite, echo=TRUE, eval=FALSE}
siteNumbers <- c("01491000","01645000")
siteINFO <- readNWISsite(siteNumbers)
"""
siteNumbers = ["01491000", "01645000"]
siteINFO, md = nwis.get_iv(sites=siteNumbers)
[4]:
"""
# Continuing from the previous example:
# This pulls out just the daily, mean data:
dailyDataAvailable <- whatNWISdata(siteNumbers,
service="dv", statCd="00003")
"""
dailyDataAvailable, md = nwis.get_dv(sites=siteNumbers, statCd="00003")
[5]:
"""
# Using defaults:
parameterCd <- "00618"
parameterINFO <- readNWISpCode(parameterCd)
"""
pCode, md = nwis.get_pmcodes(parameterCd="00618")
---------------------------------------------------------------------------
ValueError Traceback (most recent call last)
Cell In[5], line 7
1 """
2 # Using defaults:
3 parameterCd <- "00618"
4 parameterINFO <- readNWISpCode(parameterCd)
5 """
----> 7 pCode, md = nwis.get_pmcodes(parameterCd="00618")
File /opt/hostedtoolcache/Python/3.13.12/x64/lib/python3.13/site-packages/dataretrieval/nwis.py:863, in get_pmcodes(parameterCd, partial, ssl_check)
858 if len(response.text.splitlines()) < 10: # empty query
859 raise TypeError(
860 "One of the parameter codes or names entered does not"
861 "return any information, please try a different value"
862 )
--> 863 return_list.append(_read_rdb(response.text))
864 else:
865 raise TypeError("Parameter information (code or name) must be type string")
File /opt/hostedtoolcache/Python/3.13.12/x64/lib/python3.13/site-packages/dataretrieval/nwis.py:1350, in _read_rdb(rdb)
1335 """
1336 Convert NWIS rdb table into a ``pandas.dataframe``.
1337
(...) 1347
1348 """
1349 if "<html>" in rdb.lower() or "<!doctype html>" in rdb.lower():
-> 1350 raise ValueError(
1351 "Received HTML response instead of RDB. This often indicates "
1352 "that the service has been moved or is currently unavailable."
1353 )
1355 count = 0
1357 for line in rdb.splitlines():
1358 # ignore comment lines
ValueError: Received HTML response instead of RDB. This often indicates that the service has been moved or is currently unavailable.
[6]:
"""
# Choptank River near Greensboro, MD:
siteNumber <- "01491000"
parameterCd <- "00060" # Discharge
startDate <- "2009-10-01"
endDate <- "2012-09-30"
discharge <- readNWISdv(siteNumber,
parameterCd, startDate, endDate)
"""
# Choptank River near Greensboro, MD:
siteNumber = "01491000"
parameterCd = "00060" # Discharge
startDate = "2009-10-01"
endDate = "2012-09-30"
discharge, md = nwis.get_dv(
sites=siteNumber, parameterCd=parameterCd, start=startDate, end=endDate
)
[7]:
"""
siteNumber <- "01491000"
parameterCd <- c("00010","00060") # Temperature and discharge
statCd <- c("00001","00003") # Mean and maximum
startDate <- "2012-01-01"
endDate <- "2012-05-01"
temperatureAndFlow <- readNWISdv(siteNumber, parameterCd,
startDate, endDate, statCd=statCd)
"""
siteNumber = "01491000"
parameterCd = ["00010", "00060"] # Temperature and discharge
statCd = ["00001", "00003"] # Mean and maximum
startDate = "2012-01-01"
endDate = "2012-05-01"
temperatureAndFlow, md = nwis.get_dv(
sites=siteNumber,
parameterCd=parameterCd,
start=startDate,
end=endDate,
statCd=statCd,
)
[8]:
"""
parameterCd <- "00060" # Discharge
startDate <- "2012-05-12"
endDate <- "2012-05-13"
dischargeUnit <- readNWISuv(siteNumber, parameterCd,
startDate, endDate)
"""
siteNumber = "01491000"
parameterCd = "00060" # Discharge
startDate = "2012-05-12"
endDate = "2012-05-13"
dischargeUnit, md = nwis.get_iv(
sites=siteNumber, parameterCd=parameterCd, start=startDate, end=endDate
)
[9]:
"""
# Dissolved Nitrate parameter codes:
parameterCd <- c("00618","71851")
startDate <- "1985-10-01"
endDate <- "2012-09-30"
dfLong <- read_USGS_samples(monitoringLocationIdentifier=sprintf("USGS-%s", siteNumber), usgsPCode=parameterCd,
activityStartDateLower=startDate, activityStartDateUpper=endDate)
"""
siteNumber = "01491000"
parameterCd = ["00618", "71851"]
startDate = "1985-10-01"
endDate = "2012-09-30"
dfLong, md = waterdata.get_samples(
monitoringLocationIdentifier=f"USGS-{siteNumber}",
usgsPCode=parameterCd,
activityStartDateLower=startDate,
activityStartDateUpper=endDate,
)
[10]:
"""
siteNumber <- "434400121275801"
groundWater <- readNWISgwl(siteNumber)
"""
siteNumber = "434400121275801"
groundWater, md = nwis.get_gwlevels(sites=siteNumber)
[11]:
"""
siteNumber <- '01594440'
peakData <- readNWISpeak(siteNumber)
"""
siteNumber = "01594440"
peakData, md = nwis.get_discharge_peaks(sites=siteNumber)
[12]:
"""
ratingData <- readNWISrating(siteNumber, "base")
attr(ratingData, "RATING")
"""
ratings_data, md = nwis.get_ratings(site="01594440", file_type="base")
[13]:
"""surfaceData <- readNWISmeas(siteNumber)"""
siteNumber = "01594440"
surface_data, md = nwis.get_discharge_measurements(sites=siteNumber)
---------------------------------------------------------------------------
ValueError Traceback (most recent call last)
Cell In[13], line 3
1 """surfaceData <- readNWISmeas(siteNumber)"""
2 siteNumber = "01594440"
----> 3 surface_data, md = nwis.get_discharge_measurements(sites=siteNumber)
File /opt/hostedtoolcache/Python/3.13.12/x64/lib/python3.13/site-packages/dataretrieval/nwis.py:200, in get_discharge_measurements(sites, start, end, ssl_check, **kwargs)
197 kwargs["format"] = "rdb"
199 response = query_waterdata("measurements", ssl_check=ssl_check, **kwargs)
--> 200 return _read_rdb(response.text), NWIS_Metadata(response, **kwargs)
File /opt/hostedtoolcache/Python/3.13.12/x64/lib/python3.13/site-packages/dataretrieval/nwis.py:1350, in _read_rdb(rdb)
1335 """
1336 Convert NWIS rdb table into a ``pandas.dataframe``.
1337
(...) 1347
1348 """
1349 if "<html>" in rdb.lower() or "<!doctype html>" in rdb.lower():
-> 1350 raise ValueError(
1351 "Received HTML response instead of RDB. This often indicates "
1352 "that the service has been moved or is currently unavailable."
1353 )
1355 count = 0
1357 for line in rdb.splitlines():
1358 # ignore comment lines
ValueError: Received HTML response instead of RDB. This often indicates that the service has been moved or is currently unavailable.
[14]:
"""
allegheny <- readNWISuse(stateCd = "Pennsylvania",
countyCd = "Allegheny")
national <- readNWISuse(stateCd = NULL,
countyCd = NULL,
transform = TRUE)
"""
allegheny, md = nwis.get_water_use(state="PA", counties="003")
national, md = nwis.get_water_use()
---------------------------------------------------------------------------
ValueError Traceback (most recent call last)
Cell In[14], line 8
1 """
2 allegheny <- readNWISuse(stateCd = "Pennsylvania",
3 countyCd = "Allegheny")
(...) 6 transform = TRUE)
7 """
----> 8 allegheny, md = nwis.get_water_use(state="PA", counties="003")
10 national, md = nwis.get_water_use()
File /opt/hostedtoolcache/Python/3.13.12/x64/lib/python3.13/site-packages/dataretrieval/nwis.py:941, in get_water_use(years, state, counties, categories, ssl_check)
939 payload.update({"wu_area": "county"})
940 response = query(url, payload, ssl_check=ssl_check)
--> 941 return _read_rdb(response.text), NWIS_Metadata(response)
File /opt/hostedtoolcache/Python/3.13.12/x64/lib/python3.13/site-packages/dataretrieval/nwis.py:1350, in _read_rdb(rdb)
1335 """
1336 Convert NWIS rdb table into a ``pandas.dataframe``.
1337
(...) 1347
1348 """
1349 if "<html>" in rdb.lower() or "<!doctype html>" in rdb.lower():
-> 1350 raise ValueError(
1351 "Received HTML response instead of RDB. This often indicates "
1352 "that the service has been moved or is currently unavailable."
1353 )
1355 count = 0
1357 for line in rdb.splitlines():
1358 # ignore comment lines
ValueError: Received HTML response instead of RDB. This often indicates that the service has been moved or is currently unavailable.
[15]:
"""
discharge_stats <- readNWISstat(siteNumbers=c("02319394"),
parameterCd=c("00060"),
statReportType="annual")
"""
discharge_stats, md = nwis.get_stats(
sites="02319394", parameterCd="00060", statReportType="annual", statTypeCd="all"
)
[16]:
# '''
# specificCond <- readWQPqw('WIDNR_WQX-10032762',
# 'Specific conductance',
# '2011-05-01','2011-09-30')
# '''
# specific_cond, md = wqp.get_results(siteid='WIDNR_WQX-10032762',
# characteristicName = 'Specific conductance',
# startDateLo='2011-05-01', startDateHi='2011-09-30')
[17]:
# '''
# dischargeWI <- readNWISdata(service="dv",
# stateCd="WI",
# parameterCd="00060",
# drainAreaMin="50",
# statCd="00003")
# '''
# dischargeWI, md = nwis.get_dv(stateCd="WI", parameterCd="00060", drainAreaMin="50", statCd="00003")
[18]:
# '''
# sitesNJ <- whatWQPsites(statecode="US:34",
# characteristicName="Chloride")
# '''
# sitesNJ, md = wqp.what_sites(statecode="US:34", characteristicName="Chloride")
[19]:
# '''
# dataPH <- readWQPdata(statecode="US:55",
# characteristicName="pH")
# '''
# dataPH, md = wqp.what_sites(statecode="US:55", characteristicName="pH")
[20]:
# '''
# type <- "Stream"
# sites <- whatWQPdata(countycode="US:55:025",siteType=type)
# '''
# streamType = "Stream"
# sites, md = wqp.get_results(countycode="US:55:025", siteType=streamType)
[21]:
"""site <- whatWQPsamples(siteid="USGS-01594440")"""
site, md = wqp.what_sites(siteid="USGS-01594440")
[22]:
"""
type <- "Stream"
sites <- whatWQPmetrics(countycode="US:55:025",siteType=type)
"""
streamType = "Stream"
sites, md = wqp.what_sites(countycode="US:55:025", siteType=streamType)
Embedded Metadata
All service methods return the DataFrame containing requested data and Metadata as a tuple. Note, a call using get_record will only return the DataFrame to remain compatible with previous usage.
national, md = nwis.get_water_use()
md is an object with the following attributes
Metadata
url # the resulting url to query usgs
query_time # the time it took to query usgs
site_info # a method to call site_info with the site parameters supplied
header # any headers attached to the response object