Imports data from Water Quality Portal web service. This function gets the data from here: https://www.waterqualitydata.us.
Usage
readWQPdata(
...,
service = "ResultWQX3",
querySummary = FALSE,
tz = "UTC",
ignore_attributes = FALSE,
convertType = TRUE
)
Arguments
- ...
see https://www.waterqualitydata.us/webservices_documentation for a complete list of options. A list of arguments can also be supplied. For more information see the above description for this help file. If no "service" argument is supplied, it will default to "ResultWQX3". One way to figure out how to construct a WQP query is to go to the "Advanced" form in the Water Quality Portal. Use the form to discover what parameters are available. Once the query is set in the form, scroll down to the "Query URL". You will see the parameters after "https://www.waterqualitydata.us/#". For example, if you chose "Nutrient" in the Characteristic Group dropdown, you will see characteristicType=Nutrient in the Query URL. The corresponding argument for dataRetrieval is characteristicType = "Nutrient". dataRetrieval users do not need to include mimeType, and providers is optional (these arguments are picked automatically).
- service
character. See Details for more information.
- querySummary
logical to only return the number of records and unique sites that will be returned from this query. Choosing TRUE is deprecated, readWQPsummary is recommended instead.
- tz
character to set timezone attribute of dateTime. Default is "UTC", and converts the date times to UTC, properly accounting for daylight savings times based on the data's provided tz_cd column. Possible values to provide are "America/New_York","America/Chicago", "America/Denver","America/Los_Angeles", "America/Anchorage", as well as the following which do not use daylight savings time: "America/Honolulu", "America/Jamaica","America/Managua","America/Phoenix", and "America/Metlakatla". See also
OlsonNames()
for more information on time zones.- ignore_attributes
logical to choose to ignore fetching site and status attributes. Default is
FALSE
.- convertType
logical, defaults to
TRUE
. IfTRUE
, the function will convert the data to dates, datetimes, numerics based on a standard algorithm. If false, everything is returned as a character.
Value
A data frame, the specific columns will depend on the "service" and/or "dataProfile".
There are also several useful attributes attached to the data frame:
Name | Type | Description |
url | character | The url used to generate the data |
siteInfo | data.frame | A data frame containing information on the requested sites |
headerInfo | data.frame | A data frame returned from the WQP status service |
queryTime | POSIXct | The time the data was returned |
Details
This function uses ... as a query input, which can be very flexible, but also has a steeper learning curve. For a quick overview, scroll down to the Examples in this help file to see many query options.
There are currently 10 legacy and 4 modern WQX options for data provided by the Water Quality Portal:
WQX:
WQP Radio Button | service argument | Base URL | dataProfile |
Monitoring Locations | StationWQX3 | /wqx3/Station/search | |
Full Physical Chemical | ResultWQX3 | /wqx3/Result/search | fullPhysChem |
Narrow | ResultWQX3 | /wqx3/Result/search | narrow |
Basic Physical Chemical | ResultWQX3 | /wqx3/Result/search | basicPhysChem |
Sampling Activity | ActivityWQX3 | /wqx3/Activity/search |
Legacy:
WQP Radio Button | service argument | Base URL |
Sample Results | Result | /data/Result/search |
Site Data Only | Station | /data/Station/search |
Sampling Activity | Activity | /data/Activity/search |
Sampling Activity Metrics | ActivityMetric | /data/ActivityMetric/search |
Site Summary (not advertised on WQP) | SiteSummary | /data/summary/monitoringLocation/search |
Project Data | Project | /data/Project/search |
Project Monitoring Location Weighting Data | ProjectMonitoringLocationWeighting | /data/ProjectMonitoringLocationWeighting/search |
Result Detection Quantitation Limit Data | ResultDetectionQuantitationLimit | /data/ResultDetectionQuantitationLimit/search |
Biological Habitat Metrics | BiologicalMetric | /data/BiologicalMetric/search |
Organization Data | Organization | /data/Organization/search |
Examples
# \donttest{
nameToUse <- "pH"
pHData <- readWQPdata(siteid = "USGS-04024315",
characteristicName = nameToUse)
ncol(pHData)
#> [1] 182
attr(pHData, "url")
#> [1] "https://www.waterqualitydata.us/wqx3/Result/search?siteid=USGS-04024315&characteristicName=pH&mimeType=csv&dataProfile=fullPhysChem"
attr(pHData, "siteInfo")
#> # A tibble: 1 × 56
#> Org_Identifier Org_FormalName ProviderName Location_Identifier Location_Name
#> <chr> <chr> <chr> <chr> <chr>
#> 1 USGS U.S. Geological… USGS USGS-04024315 LITTLE BALSA…
#> # ℹ 51 more variables: Location_Type <chr>, Location_Description <chr>,
#> # Location_State <chr>, Location_CountryName <chr>,
#> # Location_CountyName <chr>, Location_CountryCode <chr>,
#> # Location_StatePostalCode <chr>, Location_CountyCode <chr>,
#> # Location_HUCEightDigitCode <chr>, Location_HUCTwelveDigitCode <chr>,
#> # Location_TribalLandIndicator <chr>, Location_TribalLand <chr>,
#> # Location_Latitude <dbl>, Location_Longitude <dbl>, …
attr(pHData, "headerInfo")[["dataProviders"]]
#> name completeOrCancelled failed sourceRowCount outputRowCount
#> 1 usgs TRUE FALSE 33 32
#> 2 epa TRUE FALSE 1 0
#> millisecondsToFirstResponse secondsToCompletion
#> 1 4 0
#> 2 242 0
attr(pHData, "queryTime")
#> [1] "2024-08-30 17:36:44 GMT"
# dataProfile = Basic Physical Chemical
pHData_basic <- readWQPdata(siteid = "USGS-04024315",
characteristicName = nameToUse,
dataProfile = "basicPhysChem")
attr(pHData_basic, "url")
#> [1] "https://www.waterqualitydata.us/wqx3/Result/search?siteid=USGS-04024315&characteristicName=pH&dataProfile=basicPhysChem&mimeType=csv"
ncol(pHData_basic)
#> [1] 100
# dataProfile = Narrow
pHData_narrow <- readWQPdata(siteid = "USGS-04024315",
characteristicName = nameToUse,
dataProfile = "narrow")
attr(pHData_narrow, "url")
#> [1] "https://www.waterqualitydata.us/wqx3/Result/search?siteid=USGS-04024315&characteristicName=pH&dataProfile=narrow&mimeType=csv"
ncol(pHData_narrow)
#> [1] 65
# Data profiles: "Site Data Only"
site_data <- readWQPdata(
statecode = "WI",
countycode = "Dane",
service = "StationWQX3"
)
# More examples:
# querying by county
DeWitt <- readWQPdata(
statecode = "Illinois",
countycode = "DeWitt",
characteristicName = "Nitrogen"
)
# Data profile: "Sampling Activity"
activity <- readWQPdata(
siteid = "USGS-04024315",
service = "ActivityWQX3"
)
Dane_activity <- readWQPdata(
statecode = "Wisconsin",
countycode = "Dane",
startDateLo = "2023-01-01",
startDateHi = "2023-12-31",
service = "ActivityWQX3"
)
########################################################
# Legacy examples:
pHData_legacy <- readWQPdata(siteid = "USGS-04024315",
characteristicName = nameToUse,
service = "Result",
dataProfile = "narrowResult")
#> NEWS: Legacy data profiles will be retired. Please begin converting
#> workflows to the WQX 3.0 profiles. Also, data from legacy profiles do not
#> include USGS data newer than March 11, 2024. More details:
#> https://doi-usgs.github.io/dataRetrieval/articles/Status.html
attr(pHData_legacy, "url")
#> [1] "https://www.waterqualitydata.us/data/Result/search?siteid=USGS-04024315&characteristicName=pH&dataProfile=narrowResult&mimeType=csv"
# Data profiles: "Organization Data" (legacy)
org_data <- readWQPdata(
statecode = "WI",
countycode = "Dane",
service = "Organization"
)
#> NEWS: Legacy profile requested, and no equivalent/similar WQX 3.0
#> profile currently exists. Legacy profiles do not include USGS data newer
#> than March 11, 2024.
#> More details:
#> https://doi-usgs.github.io/dataRetrieval/articles/Status.html
# Data profiles: "Project Data" (legacy)
project_data <- readWQPdata(
statecode = "WI",
countycode = "Dane",
service = "Project"
)
#> NEWS: Legacy profile requested, and no equivalent/similar WQX 3.0
#> profile currently exists. Legacy profiles do not include USGS data newer
#> than March 11, 2024.
#> More details:
#> https://doi-usgs.github.io/dataRetrieval/articles/Status.html
# Data profiles: "Project Monitoring Location Weighting Data" (legacy)
proj_mlwd <- readWQPdata(
statecode = "WI",
countycode = "Dane",
service = "ProjectMonitoringLocationWeighting"
)
#> NEWS: Legacy profile requested, and no equivalent/similar WQX 3.0
#> profile currently exists. Legacy profiles do not include USGS data newer
#> than March 11, 2024.
#> More details:
#> https://doi-usgs.github.io/dataRetrieval/articles/Status.html
#> New names:
#> • `ResourceSubjectText` -> `ResourceSubjectText...13`
#> • `ResourceSubjectText` -> `ResourceSubjectText...15`
# Data profiles: "Sample Results (physical/chemical metadata)" (legacy)
samp_data <- readWQPdata(
siteid = "USGS-04024315",
dataProfile = "resultPhysChem",
service = "Result"
)
#> NEWS: Legacy data profiles will be retired. Please begin converting
#> workflows to the WQX 3.0 profiles. Also, data from legacy profiles do not
#> include USGS data newer than March 11, 2024. More details:
#> https://doi-usgs.github.io/dataRetrieval/articles/Status.html
# Data profiles: "Sample Results (biological metadata)" (legacy)
samp_bio <- readWQPdata(
siteid = "USGS-04024315",
dataProfile = "biological",
service = "Result"
)
#> NEWS: Legacy data profiles will be retired. Please begin converting
#> workflows to the WQX 3.0 profiles. Also, data from legacy profiles do not
#> include USGS data newer than March 11, 2024. More details:
#> https://doi-usgs.github.io/dataRetrieval/articles/Status.html
# Data profiles: "Sample Results (narrow)" (legacy)
samp_narrow <- readWQPdata(
siteid = "USGS-04024315",
service = "Result",
dataProfile = "narrowResult"
)
#> NEWS: Legacy data profiles will be retired. Please begin converting
#> workflows to the WQX 3.0 profiles. Also, data from legacy profiles do not
#> include USGS data newer than March 11, 2024. More details:
#> https://doi-usgs.github.io/dataRetrieval/articles/Status.html
# Data profiles: "Sampling Activity" (legacy)
samp_activity <- readWQPdata(
siteid = "USGS-04024315",
dataProfile = "activityAll",
service = "Activity"
)
#> NEWS: Legacy data profiles will be retired. Please begin converting
#> workflows to the WQX 3.0 profiles. Also, data from legacy profiles do not
#> include USGS data newer than March 11, 2024. More details:
#> https://doi-usgs.github.io/dataRetrieval/articles/Status.html
# Data profile: "Sampling Activity Metrics" (legacy)
act_metrics <- readWQPdata(
statecode = "WI",
countycode = "Dane",
service = "ActivityMetric"
)
#> NEWS: Legacy profile requested, and no equivalent/similar WQX 3.0
#> profile currently exists. Legacy profiles do not include USGS data newer
#> than March 11, 2024.
#> More details:
#> https://doi-usgs.github.io/dataRetrieval/articles/Status.html
# Data profile: "Result Detection Quantitation Limit Data" (legacy)
dl_data <- readWQPdata(
siteid = "USGS-04024315",
service = "ResultDetectionQuantitationLimit"
)
#> NEWS: Legacy profile requested, and no equivalent/similar WQX 3.0
#> profile currently exists. Legacy profiles do not include USGS data newer
#> than March 11, 2024.
#> More details:
#> https://doi-usgs.github.io/dataRetrieval/articles/Status.html
# other options:
Phosphorus <- readWQPdata(
statecode = "WI", countycode = "Dane",
characteristicName = "Phosphorus",
startDateLo = "2023-01-01",
ignore_attributes = TRUE,
convertType = FALSE
)
# }