Introduction to echor

Michael Schramm

2021-08-20

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:

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.

Query Facilities

Search and return facility information based on lookup parameters.

Reports

Search and return discharge and emissions reports for specified 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
#> # A tibble: 144 x 6
#>    ColumnName                DataType DataLength ColumnID ObjectName Description
#>    <chr>                     <chr>    <chr>      <chr>    <chr>      <chr>      
#>  1 AIR_NAME                  VARCHAR2 200        1        AIRName    The name o~
#>  2 SOURCE_ID                 VARCHAR2 30         2        SourceID   Unique Ide~
#>  3 AIR_STREET                VARCHAR2 200        3        AIRStreet  The street~
#>  4 AIR_CITY                  VARCHAR2 100        4        AIRCity    The city w~
#>  5 AIR_STATE                 CHAR     2          5        AIRState   The state ~
#>  6 LOCAL_CONTROL_REGION_CODE CHAR     3          6        LocalCont~ Code for r~
#>  7 AIR_ZIP                   VARCHAR2 10         7        AIRZip     The five-d~
#>  8 REGISTRY_ID               VARCHAR2 50         8        RegistryID An interna~
#>  9 AIR_COUNTY                VARCHAR2 100        9        AIRCounty  The name o~
#> 10 AIR_EPA_REGION            CHAR     2          10       AIREPAReg~ The EPA re~
#> # ... with 134 more rows

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")
AIRName SourceID AIRStreet FacLat FacLong
AGGIE CLEANERS 06000000480416E020 111 COLLEGE MAIN 30.61869 -96.34588
ALL SEASONS 1 HR CLEANERS 06000000480416E015 2501 TEXAS AVENUE SOUTH #D100 30.60704 -96.30875
BRYAN CLEANERS & LAUNDRY 06000000480416E012 1803 HOLLEMAN DRIVE 30.61225 -96.31750
COMET 1 HR CLEANERS 06000000480416E013 1712 SOUTHWEST PARKWAY #101 30.60616 -96.31034
EAGLE DRY CLEANING 06000000480416E017 900-8 HARVEY ROAD 30.62254 -96.31053
EARLY BIRD CLEANERS (CROWN) 06000000480416E019 615 EAST UNIVERSITY DRIVE 30.61976 -96.34399

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')
Name SourceID Street City State Zip County Region Latitude Longitude Pollutant UnitsOfMeasure Program Year Discharge
CP&L - SUTTON PLANT 110000350174 801 SUTTON STEAM PLANT ROAD WILMINGTON NC 28401 NEW HANOVER 04 NA NA 1,3-Butadiene Pounds NEI 2010 NA
CP&L - SUTTON PLANT 110000350174 801 SUTTON STEAM PLANT ROAD WILMINGTON NC 28401 NEW HANOVER 04 NA NA 1,3-Butadiene Pounds NEI 2011 15.14
CP&L - SUTTON PLANT 110000350174 801 SUTTON STEAM PLANT ROAD WILMINGTON NC 28401 NEW HANOVER 04 NA NA 1,3-Butadiene Pounds NEI 2012 NA
CP&L - SUTTON PLANT 110000350174 801 SUTTON STEAM PLANT ROAD WILMINGTON NC 28401 NEW HANOVER 04 NA NA 1,3-Butadiene Pounds NEI 2013 NA
CP&L - SUTTON PLANT 110000350174 801 SUTTON STEAM PLANT ROAD WILMINGTON NC 28401 NEW HANOVER 04 NA NA 1,3-Butadiene Pounds NEI 2014 3.26
CP&L - SUTTON PLANT 110000350174 801 SUTTON STEAM PLANT ROAD WILMINGTON NC 28401 NEW HANOVER 04 NA NA 1,3-Butadiene Pounds NEI 2015 NA

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")
CWPName SourceID CWPStreet CWPCity CWPState CWPStateDistrict CWPZip
3444 MAHOGANY DRIVE TXR1509EW SOUTHWEST OF THE INTERSECTION OF MAHOGANY DRIVE AN BRYAN TX 77807
5113 INVERNESS DR TXR1542EK 5113 INVERNESS DR BRYAN TX 77802
777 GRAHAM RD TXR1578AE 777 GRAHAM RD COLLEGE STATION TX 77845
8.5 ACRE DEVELOPMENT SH-6 TXR1535BW NORTHWEST INTERSECTION OF MARTIN LUTHER KING JR ST BRYAN TX 77803
ACADEMY CONDOMINIUMS TXR1508FA 1326 PRAIRIE DR BRYAN TX 77803
ACE TOWNHOME TXR15667I 2136 CHESTNUT OAK CIR COLLEGE STATION TX 77845-4168

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')
activity_id npdes_id version_nmbr perm_feature_id perm_feature_nmbr perm_feature_type_code perm_feature_type_desc limit_set_id limit_set_schedule_id limit_id limit_type_code limit_begin_date limit_end_date nmbr_of_submission parameter_code parameter_desc monitoring_location_code monitoring_location_desc stay_type_code stay_type_desc limit_value_id limit_value_type_code limit_value_type_desc limit_value_nmbr limit_unit_code limit_unit_desc standard_unit_code standard_unit_desc limit_value_standard_units statistical_base_code statistical_base_short_desc statistical_base_type_code statistical_base_type_desc limit_value_qualifier_code stay_value_nmbr dmr_event_id monitoring_period_end_date dmr_form_value_id value_type_code value_type_desc dmr_value_id dmr_value_nmbr dmr_unit_code dmr_unit_desc dmr_value_standard_units dmr_value_qualifier_code value_received_date days_late nodi_code nodi_desc exceedence_pct npdes_violation_id violation_code violation_desc rnc_detection_code rnc_detection_desc rnc_detection_date rnc_resolution_code rnc_resolution_desc rnc_resolution_date violation_severity
3600178396 TX0119407 4 3600049681 001 EXO External Outfall 3600061722 3600073706 3600437316 ENF 08/01/2015 03/01/2020 1 50050 Flow, in conduit or thru treatment plant 1 Effluent Gross 3600678123 Q1 Quantity1 .131 03 MGD 03 MGD .131 DB DAILY AV AVG Average <= 3601380418 04/30/2018 3618540579 Q1 Quantity1 3667289417 .0523 03 MGD .0523 = 05/17/2018 No Violation Identified
3600178396 TX0119407 4 3600049681 001 EXO External Outfall 3600061722 3600073706 3600437316 ENF 08/01/2015 03/01/2020 1 50050 Flow, in conduit or thru treatment plant 1 Effluent Gross 3600678122 Q2 Quantity2 03 MGD 03 MGD DD DAILY MX MAX Maximum 3601380418 04/30/2018 3618540580 Q2 Quantity2 3667289418 .089 03 MGD .089 = 05/17/2018 No Violation Identified
3600178396 TX0119407 4 3600049681 001 EXO External Outfall 3600061722 3600073706 3600437316 ENF 08/01/2015 03/01/2020 1 50050 Flow, in conduit or thru treatment plant 1 Effluent Gross 3600678122 Q2 Quantity2 03 MGD 03 MGD DD DAILY MX MAX Maximum 3601380419 05/31/2018 3618540598 Q2 Quantity2 3669642407 .1059 03 MGD .1059 = 06/19/2018 No Violation Identified
3600178396 TX0119407 4 3600049681 001 EXO External Outfall 3600061722 3600073706 3600437316 ENF 08/01/2015 03/01/2020 1 50050 Flow, in conduit or thru treatment plant 1 Effluent Gross 3600678123 Q1 Quantity1 .131 03 MGD 03 MGD .131 DB DAILY AV AVG Average <= 3601380419 05/31/2018 3618540597 Q1 Quantity1 3669642404 .0503 03 MGD .0503 = 06/19/2018 No Violation Identified
3600178396 TX0119407 4 3600049681 001 EXO External Outfall 3600061722 3600073706 3600437316 ENF 08/01/2015 03/01/2020 1 50050 Flow, in conduit or thru treatment plant 1 Effluent Gross 3600678123 Q1 Quantity1 .131 03 MGD 03 MGD .131 DB DAILY AV AVG Average <= 3601380420 06/30/2018 3618540615 Q1 Quantity1 3670879559 .0651 03 MGD .0651 = 07/16/2018 No Violation Identified
3600178396 TX0119407 4 3600049681 001 EXO External Outfall 3600061722 3600073706 3600437316 ENF 08/01/2015 03/01/2020 1 50050 Flow, in conduit or thru treatment plant 1 Effluent Gross 3600678122 Q2 Quantity2 03 MGD 03 MGD DD DAILY MX MAX Maximum 3601380420 06/30/2018 3618540616 Q2 Quantity2 3670879560 .3805 03 MGD .3805 = 07/16/2018 No Violation Identified

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")
#> # A tibble: 5 x 2
#>   ValueCode ValueDescription                     
#>   <chr>     <chr>                                
#> 1 00300     Oxygen, dissolved [DO]               
#> 2 51646     Oxygen, dissolved [DO] maximum       
#> 3 51645     Oxygen, dissolved [DO] minimum       
#> 4 00301     Oxygen, dissolved percent saturation 
#> 5 00399     Oxygen, dissolved, % of time violated

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)
#> Rows: 2,705
#> Columns: 62
#> $ permit                      <chr> "TX0119407", "TX0119407", "TX0119407", "TX~
#> $ activity_id                 <chr> "3600178396", "3600178396", "3600178396", ~
#> $ npdes_id                    <chr> "TX0119407", "TX0119407", "TX0119407", "TX~
#> $ version_nmbr                <chr> "4", "4", "4", "4", "4", "4", "4", "4", "4~
#> $ perm_feature_id             <chr> "3600049681", "3600049681", "3600049681", ~
#> $ perm_feature_nmbr           <chr> "001", "001", "001", "001", "001", "001", ~
#> $ perm_feature_type_code      <chr> "EXO", "EXO", "EXO", "EXO", "EXO", "EXO", ~
#> $ perm_feature_type_desc      <chr> "External Outfall", "External Outfall", "E~
#> $ limit_set_id                <chr> "3600061722", "3600061722", "3600061722", ~
#> $ limit_set_schedule_id       <chr> "3600073706", "3600073706", "3600073706", ~
#> $ limit_id                    <chr> "3600437315", "3600437315", "3600437315", ~
#> $ limit_type_code             <chr> "ENF", "ENF", "ENF", "ENF", "ENF", "ENF", ~
#> $ limit_begin_date            <chr> "08/01/2015", "08/01/2015", "08/01/2015", ~
#> $ limit_end_date              <chr> "03/01/2020", "03/01/2020", "03/01/2020", ~
#> $ nmbr_of_submission          <chr> "1", "1", "1", "1", "1", "1", "1", "1", "1~
#> $ parameter_code              <chr> "00300", "00300", "00300", "00300", "00300~
#> $ parameter_desc              <chr> "Oxygen, dissolved [DO]", "Oxygen, dissolv~
#> $ monitoring_location_code    <chr> "1", "1", "1", "1", "1", "1", "1", "1", "1~
#> $ monitoring_location_desc    <chr> "Effluent Gross", "Effluent Gross", "Efflu~
#> $ stay_type_code              <chr> "", "", "", "", "", "", "", "", "", "", ""~
#> $ stay_type_desc              <chr> "", "", "", "", "", "", "", "", "", "", ""~
#> $ limit_value_id              <chr> "3600678121", "3600678121", "3600678121", ~
#> $ limit_value_type_code       <chr> "C1", "C1", "C1", "C1", "C1", "C1", "C1", ~
#> $ limit_value_type_desc       <chr> "Concentration1", "Concentration1", "Conce~
#> $ limit_value_nmbr            <chr> "4", "4", "4", "4", "4", "4", "4", "4", "4~
#> $ limit_unit_code             <chr> "19", "19", "19", "19", "19", "19", "19", ~
#> $ limit_unit_desc             <chr> "mg/L", "mg/L", "mg/L", "mg/L", "mg/L", "m~
#> $ standard_unit_code          <chr> "19", "19", "19", "19", "19", "19", "19", ~
#> $ standard_unit_desc          <chr> "mg/L", "mg/L", "mg/L", "mg/L", "mg/L", "m~
#> $ limit_value_standard_units  <chr> "4", "4", "4", "4", "4", "4", "4", "4", "4~
#> $ statistical_base_code       <chr> "MO", "MO", "MO", "MO", "MO", "MO", "MO", ~
#> $ statistical_base_short_desc <chr> "MO MIN", "MO MIN", "MO MIN", "MO MIN", "M~
#> $ statistical_base_type_code  <chr> "MIN", "MIN", "MIN", "MIN", "MIN", "MIN", ~
#> $ statistical_base_type_desc  <chr> "Minimum", "Minimum", "Minimum", "Minimum"~
#> $ limit_value_qualifier_code  <chr> ">=", ">=", ">=", ">=", ">=", ">=", ">=", ~
#> $ stay_value_nmbr             <chr> "", "", "", "", "", "", "", "", "", "", ""~
#> $ dmr_event_id                <chr> "3601380418", "3601380419", "3601380420", ~
#> $ monitoring_period_end_date  <chr> "04/30/2018", "05/31/2018", "06/30/2018", ~
#> $ dmr_form_value_id           <chr> "3618540570", "3618540588", "3618540606", ~
#> $ value_type_code             <chr> "C1", "C1", "C1", "C1", "C1", "C1", "C1", ~
#> $ value_type_desc             <chr> "Concentration1", "Concentration1", "Conce~
#> $ dmr_value_id                <chr> "3667289411", "3669642431", "3670879558", ~
#> $ dmr_value_nmbr              <chr> "4.97", "4.8", "5.14", "5.51", "5.38", "5.~
#> $ dmr_unit_code               <chr> "19", "19", "19", "19", "19", "19", "19", ~
#> $ dmr_unit_desc               <chr> "mg/L", "mg/L", "mg/L", "mg/L", "mg/L", "m~
#> $ dmr_value_standard_units    <chr> "4.97", "4.8", "5.14", "5.51", "5.38", "5.~
#> $ dmr_value_qualifier_code    <chr> "=", "=", "=", "=", "=", "=", "=", "=", "=~
#> $ value_received_date         <chr> "05/17/2018", "06/19/2018", "07/16/2018", ~
#> $ days_late                   <chr> "", "", "", "", "", "", "", "", "", "", ""~
#> $ nodi_code                   <chr> "", "", "", "", "", "", "", "", "", "", ""~
#> $ nodi_desc                   <chr> "", "", "", "", "", "", "", "", "", "", ""~
#> $ exceedence_pct              <chr> "", "", "", "", "", "", "", "", "", "", ""~
#> $ npdes_violation_id          <chr> "", "", "", "", "", "", "", "", "", "", ""~
#> $ violation_code              <chr> "", "", "", "", "", "", "", "", "", "", ""~
#> $ violation_desc              <chr> "", "", "", "", "", "", "", "", "", "", ""~
#> $ rnc_detection_code          <chr> "", "", "", "", "", "", "", "", "", "", ""~
#> $ rnc_detection_desc          <chr> "", "", "", "", "", "", "", "", "", "", ""~
#> $ rnc_detection_date          <chr> "", "", "", "", "", "", "", "", "", "", ""~
#> $ rnc_resolution_code         <chr> "", "", "", "", "", "", "", "", "", "", ""~
#> $ rnc_resolution_desc         <chr> "", "", "", "", "", "", "", "", "", "", ""~
#> $ rnc_resolution_date         <chr> "", "", "", "", "", "", "", "", "", "", ""~
#> $ violation_severity          <chr> "No Violation Identified", "No Violation I~

Spatial data

echor can also return spatial data frames known as simple features (https://r-spatial.github.io/sf/), to facilitate creation of maps. Both echoAirGetFacilityInfo and echoWaterGetFacilityInfo include arguments to return simple feature dataframes.

Using sf, ggplot, and ggspatial we can quickly create a map of downloaded data.


library(ggplot2)
library(ggspatial)
library(dplyr)
library(sf)

## Download data as a simple feature
df <- echoWaterGetFacilityInfo(xmin = '-96.407563', ymin = '30.554395',
                                        xmax = '-96.25947', ymax = '30.751984',
                                        output = 'sf')

## Make the map
ggplot(df) +
  annotation_map_tile(zoomin = 0, progress = "none") +
  geom_sf(inherit.aes = FALSE, shape = 21, 
          color = "darkred", fill = "darkred", 
          size = 2) +
  labs(x = "Longitude", y = "Latitude", 
       title = "NPDES permits near Texas A&M",
       caption = "Source: EPA ECHO database")