Python Equivalents to R Vignette Examples

[1]:

from dataretrieval import nwis, waterdata, wqp

The dataretrieval Python package was created as an equivalent to the R dataRetrieval package.

The following shows Python equivalents for the methods outlined in the R dataRetrieval vignette, with the equivalent R code in comments.

[2]:

"""
{r getSite, echo=TRUE, eval=FALSE}
siteNumbers <- c("01491000","01645000")
siteINFO <- readNWISsite(siteNumbers)
"""
siteNumbers = ["USGS-01491000", "USGS-01645000"]
siteINFO, md = waterdata.get_monitoring_locations(
    monitoring_location_id=siteNumbers, skip_geometry=True
)

Retrieving: monitoring-locations · 1 page · 2 rows
No API key detected — register for higher rate limits at https://api.waterdata.usgs.gov/signup/

[3]:

"""
# Continuing from the previous example:
# This pulls out just the daily, mean data:
dailyDataAvailable <- whatNWISdata(siteNumbers,
                    service="dv", statCd="00003")
"""
dailyDataAvailable, md = waterdata.get_time_series_metadata(
    monitoring_location_id=siteNumbers, statistic_id="00003", skip_geometry=True
)

Retrieving: time-series-metadata · 1 page · 11 rows

[4]:

"""
# 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 = "USGS-01491000"
parameterCd = "00060"  # Discharge

discharge, md = waterdata.get_daily(
    monitoring_location_id=siteNumber,
    parameter_code=parameterCd,
    time="2009-10-01/2012-09-30",
)

Retrieving: daily · 1 page · 1,096 rows

[5]:

"""
siteNumber <- "01491000"
parameterCd <- c("00010","00060")  # Temperature and discharge
statCd <- c("00001","00003")  # Maximum and mean
startDate <- "2012-01-01"
endDate <- "2012-05-01"

temperatureAndFlow <- readNWISdv(siteNumber, parameterCd, startDate, endDate, statCd=statCd)
"""
siteNumber = "USGS-01491000"
parameterCd = ["00010", "00060"]  # Temperature and discharge
statisticId = ["00001", "00003"]  # Maximum and mean

temperatureAndFlow, md = waterdata.get_daily(
    monitoring_location_id=siteNumber,
    parameter_code=parameterCd,
    statistic_id=statisticId,
    time="2012-01-01/2012-05-01",
)

Retrieving: daily · 1 page · 364 rows

[6]:

"""
parameterCd <- "00060"  # Discharge
startDate <- "2012-05-12"
endDate <- "2012-05-13"
dischargeUnit <- readNWISuv(siteNumber, parameterCd, startDate, endDate)
"""
siteNumber = "USGS-01491000"
parameterCd = "00060"  # Discharge

dischargeUnit, md = waterdata.get_continuous(
    monitoring_location_id=siteNumber,
    parameter_code=parameterCd,
    time="2012-05-12/2012-05-13",
)

Retrieving: continuous · 1 page · 97 rows

[7]:

"""
# 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 = "USGS-01491000"
parameterCd = ["00618", "71851"]

dfLong, md = waterdata.get_samples(
    monitoringLocationIdentifier=siteNumber,
    usgsPCode=parameterCd,
    activityStartDateLower="1985-10-01",
    activityStartDateUpper="2012-09-30",
)

[8]:

"""
siteNumber <- '01594440'
peakData <- readNWISpeak(siteNumber)
"""
peakData, md = waterdata.get_peaks(
    monitoring_location_id="USGS-01594440", parameter_code="00060"
)

Retrieving: peaks · 1 page · 49 rows

[9]:

"""
ratingData <- readNWISrating(siteNumber, "base")
attr(ratingData, "RATING")
"""
# get_ratings returns a dict keyed by "<id>.<file_type>.rdb"
ratings_data = waterdata.get_ratings(
    monitoring_location_id="USGS-01594440", file_type="base"
)
list(ratings_data.keys())

[9]:

['USGS-01594440.base.rdb']

[10]:

"""
discharge_stats <- readNWISstat(siteNumbers=c("02319394"),
                   parameterCd=c("00060"),
                   statReportType="annual")
"""
discharge_stats, md = waterdata.get_stats_date_range(
    monitoring_location_id="USGS-02319394",
    parameter_code="00060",
    computation_type="arithmetic_mean",
)

Retrieving: observationIntervals · 1 page · 344 rows

[11]:

# R: readNWISdata(service="dv", stateCd="WI", parameterCd="00060",
#                 drainAreaMin="50", statCd="00003")
#
# The Water Data API serves daily values per monitoring location. To assemble a
# state-wide set, first find the locations (optionally filtering by drainage
# area) with waterdata.get_monitoring_locations(state_name="Wisconsin", ...),
# then pass their ids to waterdata.get_daily(parameter_code="00060",
# statistic_id="00003").

[12]:

# '''
# sitesNJ <- whatWQPsites(statecode="US:34",
#                        characteristicName="Chloride")
# '''
# sitesNJ, md = wqp.what_sites(statecode="US:34", characteristicName="Chloride")

[13]:

# '''
# dataPH <- readWQPdata(statecode="US:55",
#                  characteristicName="pH")
# '''
# dataPH, md = wqp.what_sites(statecode="US:55", characteristicName="pH")

[14]:

# '''
# type <- "Stream"
# sites <- whatWQPdata(countycode="US:55:025",siteType=type)
# '''
# streamType = "Stream"
# sites, md = wqp.get_results(countycode="US:55:025", siteType=streamType)

[15]:

"""site <- whatWQPsamples(siteid="USGS-01594440")"""

site, md = wqp.what_sites(siteid="USGS-01594440")

[16]:

"""
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

Most waterdata and wqp service methods return a tuple of the requested data (a pandas DataFrame) and a metadata object.

md is an object with the following attributes:

Metadata
    url         # the URL used to query the service
    query_time  # how long the query took
    header      # the response headers

Note: USGS water use data has no Water Data API equivalent yet, so it remains available only through the deprecated nwis module:

national, md = nwis.get_water_use()