In mps9506/echor: Access EPA 'ECHO' Data

knitr::opts_chunk$set(
  fig.asp = 1 / 1.6,
  out.width = "75%",
  fig.width = 5,
  fig.retina = NULL,
  dpi = 96,
  collapse = TRUE,
  comment = "#>"
)

options(crayon.enabled = NULL)

library(kableExtra)
library(httptest)
library(dplyr)

path <- here::here("vignettes/int")

api_root <- "https://echodata.epa.gov/echo/"

set_redactor(function (response) {
  response %>%
    gsub_response(api_root, "", fixed = TRUE)
})

set_requester(function (request) {
  request %>%
    gsub_request(api_root, "", fixed = TRUE)
})

httptest::start_vignette(path = path)

echor introduction

echor is an R package to search and download data from the US Environmental Protection Agency (EPA) Environmental Compliance and History Online (ECHO). echor uses the ECHO API to download data directly to the R as dataframes or simple features. ECHO provides information about facilities permitted to emitted air pollutants or discharge into water bodies. ECHO also provides data reported by permitted facilities as volume or concentration of pollutants during reporting time periods (typically annually for air emissions and monthly or quarterly for water discharges).

ECHO provides data for:

Stationary sources permitted under the Clean Air Act, including data from the National Emissions Inventory, Greenhouse Gas Reporting Program, Toxics Release Inventory, and Clean Air Markets Division Acid Rain Program and Clean Air Interstate Rule.
Public drinking water systems permitted under the Safe Drinking Water Act, including data from the Safe Drinking Water Information System.
Hazardous Waste Handlers permitted under the Resource Conservation and Recovery Act, with data drawn from the RCRAInfo data system.
Facilities permitted under the Clean Water Act and the National Pollutant Discharge Elimination Systems (NPDES) program, including data from EPA's ICIS-NPDES system and possibly water body information from EPA's ATTAINS data system.

echor currently provides functions to retrieve information about permitted air dischargers, water dischargers, and public drinking water supply systems. It also provides functions to download discharge reports for permitted air and water dischargers. echor does not currently provide functionality to retrieve RCRA data.

See https://echo.epa.gov/tools/web-services for information about ECHO web services and API functions.

Getting started

This vignette documents a few key functions to get started.

There are three types of functions:

Metadata

Retrieve metadata from ECHO to narrow the specify data returned or lookup parameter codes.

echoAirGetMeta() - Returns variable name and descriptions for parameters returned in air facility queries.
echoSDWGetMeta() - Returns variable name and descriptions for parameters returned in public water system queries.
echoWaterGetMeta() - Returns variable name and descriptions for parameters returned in water discharge facility queries (e.g. facilities with an NPDES permit).
echoWaterGetParams() - Search parameter codes for constituent pollutants regulated under NPDES permits.

Query Facilities

Search and return facility information based on lookup parameters.

echoAirGetFacilityInfo() - Returns a dataframe of permitted air discharge facilities and associated information based on lookup parameters specified by the user.
echoSDWGetSystems() - Returns a dataframe of permitted air discharge facilities and associated information based on lookup parameters specified by the user.
echoWaterGetFacilityInfo() - Returns a dataframe of permitted water discharge facilities and associated information based on lookup parameters specified by the user.

Reports

Search and return discharge and emissions reports for specified facilities.

echoGetCAAPR() - Returns a dataframe with reported annual air emissions from permitted facilities.
echoGetEffluent() - Returns a dataframe with reported water effluent discharges from permitted facilities.

Sample workflows

Air

Suppose we want to find facilities permitted under the Clean Air Act requirements.

Step 1 - Identify the information we need returned from the query:

library(echor)
meta <- echoAirGetMeta()
meta

The dataframe includes ColumnID, which can be included as an argument that specifies what information you want returned: qcolumns = "1,2,3,22,23"

Step 2 - Create the query. The ECHO API provides numerous arguments to search by that are not documented in this package. I recommend exploring the documentation here: https://echo.epa.gov/tools/web-services/facility-search-air#!/Facilities/get_air_rest_services_get_facility_info. In this example, we will search by a geographic bounding box and specify the returned information with the qcolumns argument. Each argument should be passed to ECHO as echoAirGetFacilityInfo(parameter = "value"). echor will URL encode strings automatically. Please note that any date argument needs to be entered as "mm/dd/yyyy".

library(echor)

## Retrieve information about facilities within a geographic location
df <- echoAirGetFacilityInfo(output = "df",
                             xmin = '-96.387509',
                             ymin = '30.583572',
                             xmax = '-96.281422',
                             ymax = '30.640008',
                             qcolumns = "1,2,3,22,23")

knitr::kable(head(df), "html") %>%
  kable_styling() %>%
  scroll_box(height = "200px")

Some example arguments are listed below:

p_fn  string  Facility Name Filter.
              One or more case-insesitive facility names.
              Provide multiple values as comma-delimited list
              ex:
              p_fn = "Aggie Cleaners, City of Bryan, TEXAS A&M UNIVERSITY COLLEGE STATION CAMPUS"

p_sa  string  Facility Street Address
              ex:
              p_sa = "WELLBORN ROAD & UNIVERSITY DR"

p_ct  string  Facility City
              Provide a single case-insensitive city name
              ex:
              p_ct = "College Station"

p_co  string  Facility County
              Provide a single county name, in combination with a state value
              provided through p_st
              ex:
              p_co = "Brazos", p_st = "Texas"

p_fips  string  FIPS Code
                Single 5-character Federal Information Processing Standards (FIPS) 
                state+county value

p_st  string  Facility State or State Equivalent Filter
              Provide one or more USPS postal abbreviations
              ex:
              p_st = "TX, NC"

p_zip string  Facility 5-Digit Zip Code
              Provide one or more 5-digit postal zip codes
              ex:
              p_zip = "77843, 77845"

xmin  string  Minimum longitude value in decimal degrees

ymin  string  Minimum latitude value in decimal degrees

xmax  string  Maximum longitude value in decimal degrees

ymax  string  Maximum latitude value in decimal degrees

Step 3 - Download the emission inventory report for a permitted facility:

df <- echoGetCAAPR(p_id = '110000350174')

knitr::kable(head(df), "html") %>%
  kable_styling() %>%
  scroll_box(width = "100%", height = "200px")

There are only two valid arguments for echoGetCAAPR.

p_id    string  EPA Facility Registry Service's REGISTRY_ID.

p_units string  Units of measurement. Defaults is 'lbs'.
                Enter "TPWE" for toxic weighted pounds equivalents.

Water facility and discharge searches

Find facilities with NPDES permits to discharge wastewater:

df <- echoWaterGetFacilityInfo(xmin = '-96.407563', ymin = '30.554395', 
                               xmax = '-96.25947',  ymax = '30.751984', 
                               output = 'df', qcolumns = "1,2,3,4,5,6,7")

knitr::kable(head(df), "html") %>%
  kable_styling() %>%
  scroll_box(width = "100%", height = "200px")

Again, there are a ton of possible arguments to query ECHO with. All arguments are described here: https://echo.epa.gov/tools/web-services/facility-search-water#!/Facility_Information/get_cwa_rest_services_get_facility_info

Commonly used arguments are provided below:

p_fn  string  Facility Name Filter.
              One or more case-insesitive facility names.
              Provide multiple values as comma-delimited list
              ex:
              p_fn = "Aggie Cleaners, City of Bryan, TEXAS A&M UNIVERSITY COLLEGE STATION CAMPUS"

p_sa  string  Facility Street Address
              ex:
              p_sa = "WELLBORN ROAD & UNIVERSITY DR"

p_ct  string  Facility City
              Provide a single case-insensitive city name
              ex:
              p_ct = "College Station"

p_co  string  Facility County
              Provide a single county name, in combination with a state value
              provided through p_st
              ex:
              p_co = "Brazos", p_st = "Texas"

p_fips  string  FIPS Code
                Single 5-character Federal Information Processing Standards (FIPS) 
                state+county value

p_st  string  Facility State or State Equivalent Filter
              Provide one or more USPS postal abbreviations
              ex:
              p_st = "TX, NC"

p_zip string  Facility 5-Digit Zip Code
              Provide one or more 5-digit postal zip codes
              ex:
              p_zip = "77843, 77845"

xmin  string  Minimum longitude value in decimal degrees

ymin  string  Minimum latitude value in decimal degrees

xmax  string  Maximum longitude value in decimal degrees

ymax  string  Maximum latitude value in decimal degrees

p_huc string  2-,4,6-,or 8-digit watershed code.
              May contain comma-seperated values

Download discharge monitoring reports from ECHO from specified facilities:

df <- echoGetEffluent(p_id = 'tx0119407', parameter_code = '50050')

knitr::kable(head(df), "html") %>%
  kable_styling() %>%
  scroll_box(width = "100%", height = "200px")

This function only retrieves from a single facility per call. The following arguments are available from ECHO:

p_id            string  EPA Facility Registry Service's REGISTRY_ID.

outfall         string  Three-character code identifying the point of discharge.

parameter_code  string  Five-digit numeric code identifying the parameter.

start_date      string  Start date of interest. Must be entered as "mm/dd/yyyy"

end_date        string  End date of interest. Must be entered as "mm/dd/yyyy"

Parameters codes can be searched using echoWaterGetParams.

echoWaterGetParams(term = "Oxygen, dissolved")

Multiple DMRs can be downloaded using a helper function: downloadDMRs:

df <- tibble::tibble(permit = c('TX0119407', 'TX0062677'))
df <- downloadDMRs(df, idColumn = permit)
df <- df %>%
  tidyr::unnest(dmr)
tibble::glimpse(df)