# Introduction

# About

The Assessment, Total Maximum Daily Load (TMDL) Tracking and Implementation System (ATTAINS) is the U.S. Environmental Protection Agency (EPA) database used to track information provided by states about water quality assessments conducted under the Clean Water Act. The assessments are conducted every two years to evaluate if the nation’s water bodies meet water quality standards. States are required to take Actions (TMDLs or other efforts) on water bodies that do not meet standards. Public information in ATTAINS is made available through webservices and provided as JSON files. rATTAINS facilitates accessing this data with various functions that provide raw JSON or formatted “tidy” data for each of the ATTAINS webservice endpoints. More information about Clean Water Act assessment and reporting is available through the EPA. For alternative methods of accessing the same data, see “How’s My Waterway” webpage for interactive data exploration or the ArcGIS MapService for spatial data.

# Functions

## Summary Services

The EPA provides two summary service endpoint that provide summaries of assessed uses by the organization identifier or by hydrologic unit code (HUC). For example, to return a summary of assessed uses by the state of Tennessee the following function is used:

    library(rATTAINS)
    x <- state_summary(organization_id = "TDECWR",
                       reporting_cycle = "2016")
    x
    #> # A tibble: 71 × 24
    #>    organization_identifer organization_name organization_type_text
    #>    <chr>                  <chr>             <chr>
    #>  1 TDECWR                 Tennessee         State
    #>  2 TDECWR                 Tennessee         State
    #>  3 TDECWR                 Tennessee         State
    #>  4 TDECWR                 Tennessee         State
    #>  5 TDECWR                 Tennessee         State
    #>  6 TDECWR                 Tennessee         State
    #>  7 TDECWR                 Tennessee         State
    #>  8 TDECWR                 Tennessee         State
    #>  9 TDECWR                 Tennessee         State
    #> 10 TDECWR                 Tennessee         State
    #> # ℹ 61 more rows
    #> # ℹ 21 more variables: reporting_cycle <chr>, water_type_code <chr>,
    #> #   units_code <chr>, use_name <chr>, fully_supporting <dbl>,
    #> #   fully_supporting_count <int>, use_insufficient_information <dbl>,
    #> #   use_insufficient_information_count <int>, not_assessed <dbl>,
    #> #   not_assessed_count <int>, not_supporting <dbl>, not_supporting_count <int>,
    #> #   parameter_group <chr>, parameter_insufficient_information <dbl>, …

The HUC12 service operates similarly but provides data summarized by area, specifically HUC12 units. For example:

    x <- huc12_summary("020700100204")
    x
    #> $huc_summary
    #> # A tibble: 1 × 14
    #>   huc12        assessment_unit_count total_catchment_area…¹ total_huc_area_sq_mi
    #>   <chr>                        <int>                  <dbl>                <dbl>
    #> 1 020700100204                    17                   46.1                 46.2
    #> # ℹ abbreviated name: ¹​total_catchment_area_sq_mi
    #> # ℹ 10 more variables: assessed_catchment_area_sq_mi <dbl>,
    #> #   assessed_cathcment_area_percent <dbl>,
    #> #   assessed_good_catchment_area_sq_mi <dbl>,
    #> #   assessed_good_catchment_area_percent <dbl>,
    #> #   assessed_unknown_catchment_area_sq_mi <dbl>,
    #> #   assessed_unknown_catchment_area_percent <dbl>, …
    #>
    #> $au_summary
    #> # A tibble: 17 × 1
    #>    assessment_unit_id
    #>    <chr>
    #>  1 MD-02140205-Northwest_Branch
    #>  2 MD-02140205
    #>  3 DCTFD01R_00
    #>  4 DCTNA01R_00
    #>  5 DCTFS01R_00
    #>  6 MD-ANATF
    #>  7 DCTTX27R_00
    #>  8 DCTFC01R_00
    #>  9 MD-02140205-Mainstem
    #> 10 DCTWB00R_02
    #> 11 DCANA00E_02
    #> 12 DCTHR01R_00
    #> 13 DCTWB00R_01
    #> 14 DCTPB01R_00
    #> 15 DCTDU01R_00
    #> 16 DCANA00E_01
    #> 17 DCAKL00L_00
    #>
    #> $ir_summary
    #> # A tibble: 2 × 4
    #>   EPA_IR_category_name catchment_size_sq_mi catchment_size_percent
    #>   <chr>                               <dbl>                  <dbl>
    #> 1 4A                                   12.7                   27.5
    #> 2 5                                    25.8                   56.0
    #> # ℹ 1 more variable: assessment_unit_count <int>
    #>
    #> $status_summary
    #> # A tibble: 1 × 4
    #>   overall_status catchment_size_sq_mi catchment_size_percent
    #>   <chr>                         <dbl>                  <dbl>
    #> 1 Not Supporting                 35.2                   76.4
    #> # ℹ 1 more variable: assessment_unit_count <int>
    #>
    #> $use_group_summary
    #> # A tibble: 5 × 5
    #>   use_group_name      use_attainment catchment_size_sq_mi catchment_size_percent
    #>   <chr>               <chr>                         <dbl>                  <dbl>
    #> 1 ECOLOGICAL_USE      Not Supporting               10.9                    23.7
    #> 2 FISHCONSUMPTION_USE Insufficient …               15.9                    34.4
    #> 3 FISHCONSUMPTION_USE Not Supporting               15.9                    34.4
    #> 4 OTHER_USE           Fully Support…                0.683                   1.48
    #> 5 RECREATION_USE      Not Supporting               15.2                    32.9
    #> # ℹ 1 more variable: assessment_unit_count <int>
    #>
    #> $use_summary
    #> # A tibble: 6 × 6
    #>   use_name                    use_group_name use_attainment catchment_size_sq_mi
    #>   <chr>                       <chr>          <chr>                         <dbl>
    #> 1 Navigation                  OTHER_USE      Fully Support…               10.9
    #> 2 Primary Contact Recreation  RECREATION_USE Not Supporting               15.9
    #> 3 Protection and Propagation… ECOLOGICAL_USE Not Supporting               15.9
    #> 4 Protection of Human Health… FISHCONSUMPTI… Insufficient …                0.683
    #> 5 Protection of Human Health… FISHCONSUMPTI… Not Supporting               15.2
    #> 6 Secondary Contact Recreati… RECREATION_USE Not Supporting               15.9
    #> # ℹ 2 more variables: catchment_size_percent <dbl>, assessment_unit_count <int>
    #>
    #> $param_summary
    #> # A tibble: 16 × 4
    #>    parameter_group_name              catchment_size_sq_mi catchment_size_percent
    #>    <chr>                                            <dbl>                  <dbl>
    #>  1 ALGAL GROWTH                                      9.21                  20.0
    #>  2 CHLORINE                                          1.73                   3.75
    #>  3 HABITAT ALTERATIONS                               2.80                   6.07
    #>  4 HYDROLOGIC ALTERATION                             5.98                  13.0
    #>  5 METALS (OTHER THAN MERCURY)                      11.8                   25.7
    #>  6 NUTRIENTS                                         9.21                  20.0
    #>  7 OIL AND GREASE                                   10.9                   23.7
    #>  8 ORGANIC ENRICHMENT/OXYGEN DEPLET…                12.7                   27.5
    #>  9 PATHOGENS                                        15.9                   34.4
    #> 10 PESTICIDES                                       15.2                   32.9
    #> 11 PH/ACIDITY/CAUSTIC CONDITIONS                     1.95                   4.22
    #> 12 POLYCHLORINATED BIPHENYLS (PCBS)                 15.2                   32.9
    #> 13 SEDIMENT                                          1.90                   4.11
    #> 14 TOXIC ORGANICS                                   13.3                   28.7
    #> 15 TRASH                                             9.21                  20.0
    #> 16 TURBIDITY                                        15.9                   34.4
    #> # ℹ 1 more variable: assessment_unit_count <int>
    #>
    #> $res_plan_summary
    #> # A tibble: 1 × 4
    #>   summary_type_name catchment_size_sq_mi catchment_size_percent
    #>   <chr>                            <dbl>                  <dbl>
    #> 1 TMDL                              15.9                   34.4
    #> # ℹ 1 more variable: assessment_unit_count <int>
    #>
    #> $vision_plan_summary
    #> # A tibble: 1 × 4
    #>   summary_type_name catchment_size_sq_mi catchment_size_percent
    #>   <chr>                            <dbl>                  <dbl>
    #> 1 TMDL                              15.9                   34.4
    #> # ℹ 1 more variable: assessment_unit_count <int>

`huc12_summary()` returns a list of tibbles with different summaries of information. Using the above example: - `x$huc_summary` provides a summary of HUC area, and the area and percentage of catchment assessed as good, unknown, or impaired. - `x$au_summary` provides a tibble with the unique identifiers for the assessment units (or distinct sections of waterbodies) within the queried HUC12. - `x$ir_summary` provides a simple summary of the area of the catchment classified under different Integrated Report Categories. - `x$status_summary` provides a summary of the overall status within the HUC12. - `x$use_group_summary` provides a summary of use attainment bu use group within the HUC12. - `x$use_summary` breaks the use summary down further by the use name. - `x$param_summary` provides the same information for parameter groups. - `x$res_plan_summary` and `x$vision_plan_summary` provides a summary of the amount of the watershed covered by particular types of restoration plans or vision plan, such as TMDLs.

## Domains

Each function has a number of allowable arguments and associated values. In order to explore what values you might be interested in querying, the Domain Value service provides information about allowable options. This is mapped to the `domain_values()` function. When used without any arguments you get a full list of possible “domains.” These are typically searchable parameters used in all the functions in rATTAINS. Note that the domain names returned by these service are not a one to one match with the argument names used in rATTAINS. It is typically fairly easy to figure out which ones match up to which arguments.

For example if I want to find out the possible organization identifiers to query by:

    x <- domain_values(domain_name = "OrgStateCode")
    x
    #> # A tibble: 146 × 5
    #>    domain       name  code  context         context_2
    #>    <chr>        <chr> <chr> <chr>           <chr>
    #>  1 OrgStateCode AK    AK    EPA             <NA>
    #>  2 OrgStateCode FL    FL    21FL303D        <NA>
    #>  3 OrgStateCode PA    PA    EPA             <NA>
    #>  4 OrgStateCode CC    CC    TEST_ORG_C      <NA>
    #>  5 OrgStateCode AZ    AZ    TEST_TRIBE_B    <NA>
    #>  6 OrgStateCode MS    MS    21MSWQ          <NA>
    #>  7 OrgStateCode CT    CT    CT_DEP01        <NA>
    #>  8 OrgStateCode ND    ND    21NDHDWQ        <NA>
    #>  9 OrgStateCode MN    MN    REDLAKE         <NA>
    #> 10 OrgStateCode NM    NM    PUEBLO_POJOAQUE <NA>
    #> # ℹ 136 more rows

The function returns a variable with the state codes and the possible parameter values as the context variable. Similarly if I want to look up possible Use Names that are utilized by the Texas Commission on Environmental Quality:

    x <- domain_values(domain_name = "UseName", context = "TCEQMAIN")
    x
    #> # A tibble: 17 × 5
    #>    domain  name                                        code    context context_2
    #>    <chr>   <chr>                                       <chr>   <chr>   <chr>
    #>  1 UseName Recreation Use                              Recrea… TCEQMA… <NA>
    #>  2 UseName Fish Consumption Use                        Fish C… TCEQMA… <NA>
    #>  3 UseName INTERMEDIATE AQUATIC LIFE                   INTERM… TCEQMA… <NA>
    #>  4 UseName OVERALL USE SUPPORT                         OVERAL… TCEQMA… <NA>
    #>  5 UseName Aquatic Life Use                            Aquati… TCEQMA… <NA>
    #>  6 UseName Oyster Waters Use                           Oyster… TCEQMA… <NA>
    #>  7 UseName FISH CONSUMPTION                            FISH C… TCEQMA… <NA>
    #>  8 UseName OYSTER AQUATIC LIFE                         OYSTER… TCEQMA… <NA>
    #>  9 UseName NON-CONTACT RECREATION                      NON-CO… TCEQMA… <NA>
    #> 10 UseName CONTACT RECREATION USE                      CONTAC… TCEQMA… <NA>
    #> 11 UseName DOMESTIC WATER SUPPLY - PUBLIC WATER SUPPLY DOMEST… TCEQMA… <NA>
    #> 12 UseName Public Water Supply Use                     Public… TCEQMA… <NA>
    #> 13 UseName General Use                                 Genera… TCEQMA… <NA>
    #> 14 UseName PRIMARY RECREATION/SWIMMING                 PRIMAR… TCEQMA… <NA>
    #> 15 UseName CONTACT RECREATION                          CONTAC… TCEQMA… <NA>
    #> 16 UseName NONCONTACT RECREATION USE                   NONCON… TCEQMA… <NA>
    #> 17 UseName Recreational Beaches                        Recrea… TCEQMA… <NA>

## Other Services

- `assessment_units()` : provides information about assessment units by the specified argument parameters.

- `assessments()` provides information about assessment decisions by the specified argument parameters.

- `actions()` provides information about Actions (such as TMDLs, 4B Actions, or similar) that have been finalized by the specified argument parameters.

- `plans()` is similiar to actions but provides information about finalized Actions and assessment units by HUC8.

- `surveys()` provides information about organization conducted statistical surveys about water quality assessment results.

## JSON Files

By default, all the functions rATTAINS return one or more “tidy” dataframes. These dataframe are created by attempting to flatten the nested JSON data returned by the webservice. This does require some opinionated decisions on what constitutes flat data, and at what variable data should be flattened to. We recognize that the dataframe output might not meet user needs. There if you would prefer to parse the JSON data yourself, use the `tidy=FALSE` argument to return an unparsed JSON string. A number of R packages are available to parse and flatten JSON data to prepare it for analysis.

# Notes

The U.S. EPA is the data provider for this public information. rATTAINS and the author are not affiliated with the EPA. Questions about the package functionality should be directed to the package author. Questions about the webservice or underlying data should be directed to the U.S. EPA. Please do not abuse the webservice using this package.