RAQSAPI - RAQSAPI functions Long version

RAQSAPI functions

The RAQSAPI library exports the following functions (in alphabetical order):

knitr::opts_chunk$set(collapse = TRUE, comment = "#>" )
invisible(library(magrittr, warn.conflicts = FALSE, quietly = TRUE))
invisible(library(stringr, warn.conflicts = FALSE, quietly = TRUE))
invisible(library(tibble, warn.conflicts = FALSE, quietly = TRUE))
invisible(library(glue, warn.conflicts = FALSE, quietly = TRUE))

#AQAD-33, using list.files works when knitting the vignette but does
#not seem to work when the vignette is knitted as part of a package.
#Instead function names need to be hard coded.
# RAQSAPI_functions <- list.files(path = "./man/", pattern = ".Rd$") %>%
# stringr::str_remove_all(pattern = ".Rd") %>%
# str_replace("ni_infix_operator", replacement = NA_character_) %>%
# str_replace("RAQSAPI", replacement = NA_character_) %>%
# str_replace_all("_services_", replacement = NA_character_) %>%
# na.omit() %>%
# as.character()
RAQSAPI_functions <- c(
"aqs_annualsummary_by_box",  
"aqs_annualsummary_by_cbsa",  
"aqs_annualsummary_by_county",  
"aqs_annualsummary_by_site",
"aqs_annualsummary_by_state",  
"aqs_cbsas",  
"aqs_classes",  
"aqs_counties_by_state",  
"aqs_credentials",  
"aqs_dailysummary_by_box",  
"aqs_dailysummary_by_cbsa",  
"aqs_dailysummary_by_county",  
"aqs_dailysummary_by_site",  
"aqs_dailysummary_by_state",  
"aqs_fields_by_service",  
"aqs_isavailable",  
"aqs_knownissues",  
"aqs_mas",  
"aqs_monitors_by_box",  
"aqs_monitors_by_cbsa",  
"aqs_monitors_by_county",  
"aqs_monitors_by_site",  
"aqs_monitors_by_state",  
"aqs_parameters_by_class",  
"aqs_pqaos",
"aqs_qa_annualPeferomanceeval_by_county",
"aqs_qa_annualPeferomanceeval_by_MA",
"aqs_qa_annualPeferomanceeval_by_pqao",
"aqs_qa_annualPeferomanceeval_by_site",
"aqs_qa_annualPeferomanceeval_by_state",
"aqs_qa_annualPeferomanceevaltransaction_by_county",
"aqs_qa_annualPeferomanceevaltransaction_by_MA",
"aqs_qa_annualPeferomanceevaltransaction_by_pqao",
"aqs_qa_annualPeferomanceevaltransaction_by_site",
"aqs_qa_annualPeferomanceevaltransaction_by_state",
"aqs_qa_blanks_by_county",  
"aqs_qa_blanks_by_MA",  
"aqs_qa_blanks_by_pqao",  
"aqs_qa_blanks_by_site",  
"aqs_qa_blanks_by_state",  
"aqs_qa_collocated_assessments_by_county",  
"aqs_qa_collocated_assessments_by_MA",  
"aqs_qa_collocated_assessments_by_pqao",  
"aqs_qa_collocated_assessments_by_site",  
"aqs_qa_collocated_assessments_by_state",  
"aqs_qa_flowrateaudit_by_county",  
"aqs_qa_flowrateaudit_by_MA",  
"aqs_qa_flowrateaudit_by_pqao",  
"aqs_qa_flowrateaudit_by_site",  
"aqs_qa_flowrateaudit_by_state",  
"aqs_qa_flowrateverification_by_county",  
"aqs_qa_flowrateverification_by_MA",  
"aqs_qa_flowrateverification_by_pqao",  
"aqs_qa_flowrateverification_by_site",  
"aqs_qa_flowrateverification_by_state",  
"aqs_qa_one_point_qc_by_county",  
"aqs_qa_one_point_qc_by_MA",  
"aqs_qa_one_point_qc_by_pqao",  
"aqs_qa_one_point_qc_by_site",  
"aqs_qa_one_point_qc_by_state",  
"aqs_qa_pep_audit_by_county",  
"aqs_qa_pep_audit_by_MA",  
"aqs_qa_pep_audit_by_pqao",  
"aqs_qa_pep_audit_by_site",  
"aqs_qa_pep_audit_by_state",
"aqs_quarterlysummary_by_box",
"aqs_quarterlysummary_by_county",
"aqs_quarterlysummary_by_pqao",
"aqs_quarterlysummary_by_site",
"aqs_quarterlysummary_by_state",
"aqs_removeheader",
"aqs_revisionhistory",  
"aqs_sampledata_by_box",  
"aqs_sampledata_by_cbsa",  
"aqs_sampledata_by_county",  
"aqs_sampledata_by_site",  
"aqs_sampledata_by_state",  
"aqs_sampledurations",
"aqs_sign_up",  
"aqs_sites_by_county",  
"aqs_states",
"aqs_transactionsample_by_county",
"aqs_transactionsample_by_site",
"aqs_transactionsample_by_state",
"aqs_transactionsample_by_MA"
)

RAQSAPI_functions %>%
  cat(sep = "  \n")

RAQSAPI functions are named according to the service and filter variables that are available by the AQS Data Mart API.^[See (https://aqs.epa.gov/aqsweb/documents/data_api.html) for full details of the Data Mart API]

Variable descriptions and usage.

These are all the available variables that can be used with various functions exported from the RAQSAPI library listed alphabetically. Not all of these variables are used with every function, and not all of these parameters are required. See the RAQSAPI functional families section to see which parameters are used with each function.

RAQSAPI functional families

Sign up and credentials

The functions included in this family of functions are:

signupandcredentials <- paste(".sign_up", ".credentials", sep = '|')

str_subset(string = RAQSAPI_functions, pattern = signupandcredentials) %>%
  cat(sep = "  \n")

These functions are used to sign up with Data Mart and to store credential information to use with RAQSAPI. The RAQSAPI::aqs_signup function takes one parameter:

The RAQSAPI::aqs_credentials function takes two parameters:

Data Mart API metadata functions

metadatafunctions <- paste(".available",
                           ".field_by_service",
                           ".knownissues", sep = '|')

str_subset(string = RAQSAPI_functions, pattern = metadatafunctions) %>%
  cat(sep = "  \n")

These functions return Data Mart meta data

The RAQSAPI::aqs_isavailable function takes no parameters and returns a table which details the status of the AQS API.

The RAQSAPI::aqs_field_by_Service function takes one parameter, service, which is a R character object which represents the services provided by the AQS API. For a list of available services see Air Quality System (AQS) API - Services Overview

The RAQSAPI::aqs_knownissues function takes no parameters and Returns a table of any known issues with system functionality or the data. These are usually issues that have been identified internally and will require some time to correct in Data Mart or the API. This function implements a direct API call to Data Mart and returns data directly from the API. Issues returned via this function do not include any issues from the RAQSAPI R package.

The RAQSAPI::aqs_revisionhistory function is used to query Data Mart for the change history to the API.

Data Mart API list functions

listfunctions <- paste(".states",
                       ".counties_by_state",
                       ".sites_by_county",
                       ".cbsas",
                       ".classes",
                       ".pqaos",
                       ".mas",
                       sep = '|'
                       )

str_subset(string = RAQSAPI_functions, pattern = listfunctions) %>%
  cat(sep = "  \n")

List functions return options or groupings that can be used in conjunction with other API calls. By default each function in this category returns results as a tibble. If return_header parameter is set to TRUE a AQSAPI_v2 object is returned instead.

RAQSAPI::aqs_cbsas returns a table of all available Core Based Statistical Areas (cbsas) and their respective cbsa codes.

RAQSAPI::aqs_states takes no arguments and returns a table of the available states and their respective state FIPS codes.

RAQSAPI::aqs_sampledurations takes no arguments and returns a table of the available sample duration code used to construct other requests.

RAQSAPI::aqs_classes takes no arguments and returns a table of parameter classes (groups of parameters, i.e. "criteria" or "all").

RAQSAPI::aqs_counties_by_state takes one parameter, stateFIPS, which is a two digit state FIPS code for the state being requested represented as a R character object and returns a table of counties and their respective FIPS code for the state requested. Use RAQSAPI::aqs_states to receive a table of valid state FIPS codes.

RAQSAPI::aqs_sites_by_county takes two parameters, stateFIPS, which is a two digit state FIPS code for the state being requested and county_code which is a three digit county FIPS code for the county being requested, both stateFIPS and county_code should be encoded as a R character object This function returns a table of all air monitoring sites with the requested state and county FIPS code combination.

RAQSAPI::aqs_pqaos takes no parameters and returns an AQS_DATAMART_APIv2 S3 object containing a table of primary quality assurance organizations (pqaos).

RAQSAPI::aqs_mas takes no parameters and returns an AQS_DATAMART_APIv2 S3 object containing a table of monitoring agencies (MA).

Data Mart aggregate functions

| Information: AQS Data Mart API restricts the \ maximum amount of monitoring data to one full year of data per \ API call. These functions are able to return multiple years of data by \ making repeated calls to the API. Each call to the Data Mart API will take \ time to complete. The more years of data being requested the longer RAQSAPI \ will take to return the results. | | -- |

These functions retrieve aggregated data from the Data Mart API and are grouped by how each function aggregates the data. There are 5 different families of related aggregate functions. These families are arranged by how the Data Mart API groups the returned data, by_site, _by_county, _by_state, _by (by_box) and _by (_by_cbsa). Within each family of aggregated data functions there are functions that call on the 10 different services that the Data Mart API provides. All Aggregate functions return a tibble by default. If the return_Header parameter is set to TRUE an AQS_DATAMART_APIv2 S3 object is returned instead.

Data Mart aggregate functions _by_site

by_sitefunctions <- paste("_by_site", sep = '|')

str_subset(string = RAQSAPI_functions, pattern = by_sitefunctions) %>%
  cat(sep = "  \n")

functions in this family of functions aggregate data at the site level. All *_by_site functions accept the following variables:

Data Mart aggregate functions _by_county

by_countyfunctions <- paste("._by_county", sep = '|')

str_subset(string = RAQSAPI_functions, pattern = by_countyfunctions) %>%
  cat(sep = "  \n")

functions in this family of functions aggregate data at the county level. All functions accept the following variables:

Data Mart aggregate functions by Monitoring agency (MA)

by_STATEfunctions <- paste("._by_state", sep = '|')

str_subset(string = RAQSAPI_functions, pattern = by_STATEfunctions) %>%
  cat(sep = "  \n")

functions in this family of functions aggregate data at the state level. All functions accept the following variables:

by_MAfunctions <- paste("._by_MA", sep = '|')

str_subset(string = RAQSAPI_functions, pattern = by_MAfunctions) %>%
  cat(sep = "  \n")

functions in this family of functions aggregate data at the Monitoring Agency (MA) level. All functions accept the following variables:

Data Mart aggregate functions by Core Based Statistical Area (cbsa)

by_cbsafunctions <- paste("._by_cbsa", sep = '|')

str_subset(string = RAQSAPI_functions, pattern = by_cbsafunctions) %>%
  cat(sep = "  \n")

functions in this family of functions aggregate data at the Core Based Statistical Area (cbsa, as defined by the US Census Bureau) level. All functions accept the following variables:

Data Mart aggregate functions by Primary Quality Assurance Organization (pqao)

by_pqaofunctions <- paste("._by_pqao", sep = '|')

str_subset(string = RAQSAPI_functions, pattern = by_pqaofunctions) %>%
  cat(sep = "  \n")

functions in this family of functions aggregate data at the Primary Quality Assurance Organization (pqao) level. All functions accept the following variables:

Data Mart aggregate functions by latitude/longitude bounding box (_by_box)

by_BOXfunctions <- paste("._by_box", sep = '|')

str_subset(string = RAQSAPI_functions, pattern = by_BOXfunctions) %>%
  cat(sep = "  \n")

Functions in this family of functions aggregate data by a latitude/longitude bounding box (_by_box) level. All functions accept the following variables:

Data Mart aggregate functions _by_state

RAQSAPI Miscellaneous functions

misc_functions <- paste("aqs_removeheader", sep = '|')

str_subset(string = RAQSAPI_functions, pattern = misc_functions) %>%
  cat(sep = "  \n")

These are miscellaneous functions exported by RAQSAPI.

RAQSAPI::aqs_removeheader is the function that the RAQSAPI library uses internally to coerce an AQS_DATAMART_APIv2 S3 object into a tibble. This is useful if the user saves the output from another RAQSAPI function with return_header = TRUE set but later decides that they want just a simple tibble object. This function takes only one variable:



Try the RAQSAPI package in your browser

Any scripts or data that you put into this service are public.

RAQSAPI documentation built on Jan. 29, 2022, 1:08 a.m.