ATTAINS Assessment Unit and Use Name Crosswalk

This function pulls in all prior ATTAINS Use names associated with each Assessment Unit (AU) from the prior ATTAINS cycle. This function requires an ATTAINS.OrganizationIdentifier and a crosswalk of an organization's WQP Monitoring Locations, ATTAINS Assessment Units, and ATTAINS Water Type as a function input (AUMLRef). The output from the $ATTAINS_crosswalk list from TADA_CreateATTAINSAUMLCrosswalk(.data, return_sf = FALSE) can be used directly as the AUMLRef argument input in this function. Alternatively, a user supplied crosswalk can be entered or TADA_GetATTAINSAUMLCrosswalk() and/or TADA_UpdateATTAINSAUMLCrosswalk() functions can be leveraged to generate the crosswalk.

Usage

TADA_AssignUsesToAU(
  .data,
  org_id = NULL,
  AUMLRef = NULL,
  AU_UsesRef = NULL,
  waterUseRef = NULL,
  excel = FALSE,
  overwrite = FALSE
)

Arguments

.data: A TADA dataframe after all desired data cleaning, processing, harmonization, filtering, and censored data handling functions have been applied.
org_id: The ATTAINS organization identifier must be supplied by the user. "USEPA" may be included as an org_id which will populate the EPA 304(a) recommended criteria for any TADA.CharacteristicName if one is found. "All" or "NULL" are also allowable values and may be helpful for new ATTAINS users or those performing assessments for multiple states and tribes. If "All" is selected, this will return all prior ATTAINS information from all ATTAINS organizations in prior ATTAINS assessment cycles as individual rows for each organization. If "NULL" is selected all unique prior ATTAINS information from any ATTAINS organizations are returned but are not labeled and can be manually edited. Enter rExpertQuery::EQ_DomainValues("org_id") into the console to get a list of valid organization identifiers. A list of organization identifiers can also be found by downloading the ATTAINS Domains Excel file: https://www.epa.gov/system/files/other-files/2025-02/domains_2025-02-25.xlsx. Organization identifiers are listed in the "code" column of the "OrgName" tab.
AUMLRef: An optional data frame input. If provided, this data frame should contain a completed crosswalk of monitoring location sites associated with an assessment unit. This data frame must contain the following column names which can be generated from the output of TADA_CreateAUMLCrosswalk: ATTAINS.OrganizationIdentifier, TADA.MonitoringLocationIdentifier, ATTAINS.AssessmentUnitIdentifier, and ATTAINS.WaterType.
AU_UsesRef: An optional data frame input. If provided, the ATTAINS.UseName will be populated from the ATTAINS.UseName found in this data frame rather than the ATTAINS assessment profile. This data frame must contain the following column names which can be generated from the output of TADA_AssignUsesToAU: ATTAINS.OrganizationIdentifier, ATTAINS.AssessmentUnitIdentifier, ATTAINS.UseName, and ATTAINS.WaterType.
waterUseRef: An optional data frame input containing a user supplied list of ATTAINS uses to ATTAINS water type. Users will need to ensure this crosswalk contains the appropriate column names in order to run the function.
excel: A Boolean value that returns an excel spreadsheet if excel = TRUE. This spreadsheet is created in the user's downloads folder path. If you have any trouble locating the file, please type the following into your R console to locate it: file.path(Sys.getenv("USERPROFILE"), "Downloads"). The file will be named "myfileRef.xlsx". The excel spreadsheet will highlight the cells in which users should input information.
overwrite: A Boolean value. If overwrite = TRUE, the excel file will be replaced (overwritten) by the new file you create if you re-run this function. Users should only specify overwrite = TRUE once they are ready to re-run this function if they have already ran it once.

Value

A data frame with all the MonitoringLocationIdentifier Sites for each defined AU.

Details

This function is mainly designed to assist with pulling existing Uses that have been entered into ATTAINS in the prior ATTAINS cycle (most recent assessment).

For any NEW AUs and/or NEW uses, users must modify the output of this function to manually add those uses and AU's to the crosswalk. Alternatively, we have developed a helper function, TADA_AssignUsesToWaterType(), to assist with assigning uses to NEW AUs. This can be leveraged to assign uses for any new AUs based on the water type of the AU. Users can either supply their own Water Type to Use crosswalk or utilize ATTAINS webservices to pull in the Water Type to Use reference file. This Water to Use reference file can be used to assign all unique Uses to a new/modified AU based on which uses have been assigned to that water type in the past by the specified ATTAINS organization. Any new or modified AU and use information that gets submitted to ATTAINS in the current assessment cycle will not be available via ATTAINS webservices until the assessment is approved and completed.

Examples

if (FALSE) { # \dontrun{
# Pull a sample TADA data frame
TADA_AK_Example <- TADA_DataRetrieval(
  startDate = "2022-01-01", endDate = "2022-12-31",
  organization = "AKDECWQ", statecode = "AK",
  characteristicName = c("Enterococcus", "Escherichia", "Escherichia coli"),
  ask = FALSE
)

# Alaska example to update data links with no user supplied crosswalk
AK_adddatalinks <- TADA_UpdateATTAINSAUMLCrosswalk(
  org_id = "AKDECWQ",
  crosswalk = NULL,
  attains_replace = FALSE,
  wqp_data_links = "replace"
)

# Alaska example using a user supplied crosswalk to update entries in
# ATTAINS by appending user supplied information to ATTAINS crosswalk

# example new AU identifiers
ATTAINS.AssessmentUnitIdentifier <- c(
  "NEW:AK_M_1021211_000", "NEW:AK_M_1021008_000",
  "NEW:AK_M_1021109_013", "NEW:AK_L_2040108_063",
  "NEW:AK_M_1021109_013"
)

# example organization identifiers
ATTAINS.OrganizationIdentifier <-
  c("AKDECWQ", "AKDECWQ", "AKDECWQ", "AKDECWQ", "AKDECWQ")

# example ML matched to new AUs, these are only examples
ATTAINS.MonitoringLocationIdentifier <- c(
  "AKDECWQ-Snag Point", "AKDECWQ-Kanakanak", "AKDECWQ-ANC02_HSLP",
  "AKDECWQ-Scandinavian", "AKDECWQ-ANC03_HSLP"
)

ATTAINS.WaterType <- c(
  "BEACH", "BAY", "CREEK",
  "ESTUARY", "CREEK"
)

# create example crosswalk data frame
ex.user.cw <- data.frame(
  ATTAINS.MonitoringLocationIdentifier,
  ATTAINS.OrganizationIdentifier,
  OrganizationIdentifier = ATTAINS.OrganizationIdentifier,
  ATTAINS.AssessmentUnitIdentifier,
  ATTAINS.MonitoringDataLinkText = NA, ATTAINS.WaterType
)

AK_appenduserdata <- TADA_UpdateATTAINSAUMLCrosswalk(
  org_id = "AKDECWQ",
  crosswalk = ex.user.cw,
  attains_replace = FALSE,
  wqp_data_links = "replace"
)

# New AUs that are not found in ATTAINS show blank ATTAINS.UseName
AK_CreateAU_UsesRef <- TADA_AssignUsesToAU(
  TADA_AK_Example,
  org_id = "AKDECWQ",
  AUMLRef = AK_appenduserdata,
  excel = FALSE
)

# Let's use a wateruseRef now to fill in these values.
AK_CreateAU_UsesRef_auto_assign <- TADA_AssignUsesToAU(
  TADA_AK_Example,
  org_id = "AKDECWQ",
  AUMLRef = AK_appenduserdata,
  waterUseRef = TADA_AssignUsesToWaterType(TADA_AK_EXAMPLE, org_id = "AKDECWQ"),
  excel = FALSE
)

# We can save and reuse a AU_UsesRef as desired.
AK_CreateAU_UsesRef2 <- TADA_AssignUsesToAU(
  TADA_AK_Example,
  org_id = "AKDECWQ",
  AU_UsesRef = AK_CreateAU_UsesRef_auto_assign,
  AUMLRef = AK_appenduserdata,
  excel = FALSE
)
} # }

Usage

Arguments

Value

Details

See also

Examples