Skip to contents

TADA_GetATTAINS

Source: R/GeospatialFunctions.R
TADA_GetATTAINS.Rd

Link catchment-based ATTAINS assessment unit data (EPA snapshot of NHDPlus HR catchments associated with entity submitted assessment unit features - points, lines, and polygons) to Water Quality Portal observations, often imported via TADA_DataRetrieval(). This function returns the objects that can be mapped in TADA_ViewATTAINS(). Check out the TADAModule2.Rmd for an example workflow. Note that approximately 80% of state submitted assessment units in ATTAINS were developed based on high res NHDPlus, so we are using that as the default.

Usage

TADA_GetATTAINS(
  .data,
  return_nearest = FALSE,
  fill_catchments = FALSE,
  resolution = "Hi",
  return_sf = TRUE
)

Arguments

.data

A dataframe created by TADA_DataRetrieval() or the sf equivalent made by TADA_MakeSpatial().

return_nearest

If a WQP observation falls within more than one AU, return ONLY the nearest AU (return_nearest = TRUE), or all AUs (return_nearest = FALSE).

fill_catchments

Whether the user would like to return NHD catchments (USGS snapshot of NHDPlus V2) for WQP observations not associated with an ATTAINS assessment unit (TRUE or FALSE). When fill_catchments = TRUE, the returned list splits observations into two dataframes: WQP observations with ATTAINS catchment data (EPA snapshot of NHDPlus V2), and WQP observations without ATTAINS catchment data. Defaults to FALSE.

resolution

If fill_catchments = TRUE, whether to use NHDPlus V2 "Med" catchments or NHDPlus V2 HiRes "Hi" catchments. Default is NHDPlus V2 HiRes ("Hi") because at approximately 80% of state submitted assessment units in ATTAINS were developed based on NHDPlus V2 HiRes.

return_sf

Whether to return the ATTAINS associated catchments, lines, points, and polygon shapefile objects along with the data frame(s). TRUE (yes, return list) or FALSE (no, do not return). All shapefile features are in WGS84 (crs = 4326). If fill_catchments = TRUE and return_sf = TRUE, the function will additionally return the raw catchment features associated with the observations in TADA_without_ATTAINS in a new shapefile called without_ATTAINS_catchments. Defaults to TRUE.

Value

A modified TADA_DataRetrieval() dataframe or list with additional columns associated with the ATTAINS assessment unit data, and, if fill_catchments = TRUE, an additional dataframe of the observations without intersecting ATTAINS features. Moreover, if return_sf = TRUE, this function will additionally return the raw ATTAINS and catchment shapefile features associated with those observations.

This function calculates and reports the distance, 'TADA.DistanceAway.Meters', between each WQP observation and intersecting ATTAINS features within its catchment. A TADA.DistanceAway.Meters value of 0 indicates that the WQP observation is directly on the associated ATTAINS point or line feature, or located inside the associated ATTAINS polygon.

Details

The ATTAINS snapshot of NHDPlus HR catchments is not available for areas that do not have existing Assessment Units in ATTAINS. For these areas where there are WQP sites, but no existing ATTAINS assessment units, a user can choose to associate the WQP sites with NHDPlus catchments available from the USGS nhdplusTools package (please be aware that USGS and EPA ATTAINS snapshots of the NHDPlus catchments may vary) using the optional function param 'fill_catchments'. If desired by the user, the HR catchments could be created as new assessment unit polygons in ATTAINS (that process is outside of TADA).

`ResultIdentifier' identifies rows that are the same observation but are linked to multiple ATTAINS assessment units. It is possible for a single TADA WQP observation to have multiple ATTAINS assessment units linked to it and subsequently more than one row of data.

If TADA_MakeSpatial has not yet been run, this function runs it which also adds another new column to the input dataframe, 'geometry', which allows for mapping and additional geospatial capabilities.

Please review the output of this function carefully, especially waterbody intersections (tributaries), lake/ocean coasts, and other areas with complex hydrology where imprecise WQP monitoring location coordinates can be problematic. Note that many WQP locations will not fall within the bounds of NHDPlus (estuaries, oceans). Manual adjustments and quality control checks are strongly encouraged. WQP monitoring location metadata may also be helpful for matching waterbody names with ATTAINS waterbody names instead of relying solely on the geospatial location (lat/long).

See also

TADA_DataRetrieval()

TADA_MakeSpatial()

TADA_ViewATTAINS()

Examples

if (FALSE) { # \dontrun{
tada_data <- TADA_DataRetrieval(
  startDate = "2018-05-01",
  endDate = "2018-05-05",
  characteristicName = "pH",
  statecode = "VA",
  applyautoclean = TRUE,
  ask = FALSE
)

# note: these example ATTAINS data retrieval queries below may take a long 
# time (10+ minutes) to run
tada_attains <- TADA_GetATTAINS(tada_data,
  fill_catchments = FALSE,
  return_sf = FALSE,
  return_nearest = FALSE,
)

tada_attains_sf <- TADA_GetATTAINS(tada_data,
  fill_catchments = FALSE,
  return_sf = TRUE,
  return_nearest = TRUE
)

tada_attains_filled <- TADA_GetATTAINS(tada_data,
  fill_catchments = TRUE,
  resolution = "Hi",
  return_sf = FALSE,
  return_nearest = TRUE
)

tada_attains_filled_sf <- TADA_GetATTAINS(tada_data,
  fill_catchments = TRUE,
  resolution = "Hi",
  return_sf = TRUE,
  return_nearest = TRUE
)
} # }