From 54b2ecb4fd3c8c8f934e76136a72c6b9fc24b448 Mon Sep 17 00:00:00 2001 From: Cole Brokamp Date: Sun, 7 Jul 2024 20:15:33 -0400 Subject: [PATCH] documentation and formatting --- R/check_api_key.R | 19 +++++++++++++------ R/get_organization_data.R | 5 +++-- R/get_sensor_data.R | 10 +++++++--- R/get_sensors_data.R | 23 +++++++++++++---------- R/purple_air_request.R | 2 -- README.Rmd | 6 +++--- man/check_api_key.Rd | 13 +++++++++---- man/get_organization_data.Rd | 7 +++++-- man/get_sensor_data.Rd | 7 +++++-- man/get_sensors_data.Rd | 15 +++++++++------ 10 files changed, 67 insertions(+), 40 deletions(-) diff --git a/R/check_api_key.R b/R/check_api_key.R index 0af26d2..569556b 100644 --- a/R/check_api_key.R +++ b/R/check_api_key.R @@ -1,12 +1,15 @@ -#' check purple air api key +#' Check Purple Air API Key #' #' Use the PurpleAir API to validate your Purple Air API Key. -#' Find more details on this function at https://api.purpleair.com/#api-keys-check-api-key +#' Find more details on this function at https://api.purpleair.com/#api-keys-check-api-key. +#' Storing your key in the environment variable `PURPLE_AIR_API_KEY` is safer than storing it +#' in source code and is used by default in each PurpleAir function. #' @param purple_air_api_key A character that is your PurpleAir API `READ` key -#' @returns if the key is valid, a message is emitted and the input is invisibly returned; +#' @returns If the key is valid, a message is emitted and the input is invisibly returned; #' invalid keys will throw an R error which utilizes information from the underlying http error -#' to inform the user +#' to inform the user. #' @export +#' @seealso get_organization_data #' @examples #' check_api_key() #' try(check_api_key("foofy")) @@ -18,7 +21,11 @@ check_api_key <- function(purple_air_api_key = Sys.getenv("PURPLE_AIR_API_KEY")) ) |> httr2::req_perform() |> httr2::resp_body_json() - # TODO add check that is must be a `READ` type key? - cli::cli_alert_success("Using valid '{resp$api_key_type}' key with version {resp$api_version} of the PurpleAir API on {as.POSIXct(resp$time_stamp)}") + cli::cli_alert_success(c( + "Using valid '{resp$api_key_type}' key ", + "with version {resp$api_version} ", + "of the PurpleAir API on ", + as.POSIXct(resp$time_stamp) + )) return(invisible(purple_air_api_key)) } diff --git a/R/get_organization_data.R b/R/get_organization_data.R index c09ebbb..6cc8cf7 100644 --- a/R/get_organization_data.R +++ b/R/get_organization_data.R @@ -1,10 +1,11 @@ -#' get organization data +#' Get Organization Data #' #' Use the PurpleAir API to retrieve information for the organization containing the provided api_key #' Find more details on this function at https://api.purpleair.com/#api-organization-get-organization-data #' @param purple_air_api_key A character that is your PurpleAir API `READ` key -#' @returns a list of organization info +#' @returns A list of organization info #' @export +#' @seealso check_api_key #' @examples #' get_organization_data() get_organization_data <- function(purple_air_api_key = Sys.getenv("PURPLE_AIR_API_KEY")) { diff --git a/R/get_sensor_data.R b/R/get_sensor_data.R index 23eab4d..b2a1d3f 100644 --- a/R/get_sensor_data.R +++ b/R/get_sensor_data.R @@ -1,4 +1,4 @@ -#' get sensor data +#' Get Sensor Data #' #' Retrieves the latest data of a single sensor matching the provided `sensor_index`. #' Find more details on sensor fields at https://api.purpleair.com/#api-sensors-get-sensor-data. @@ -6,12 +6,16 @@ #' @param fields A character vector of which 'sensor data fields' to return #' @param purple_air_api_key A character that is your PurpleAir API `READ` key #' @param read_key A character key required to read data from private devices -#' @returns a list of sensor data, named by the provided `fields` +#' @returns A list of sensor data, named by the provided `fields` #' @export +#' @seealso get_sensors_data get_sensor_history #' @examples #' get_sensor_data(sensor_index = 175413, fields = c("name", "last_seen", "pm2.5_cf_1", "pm2.5_atm")) #' get_sensor_data(sensor_index = "175413", fields = c("name", "last_seen", "pm2.5_cf_1", "pm2.5_atm")) -get_sensor_data <- function(sensor_index, fields, purple_air_api_key = Sys.getenv("PURPLE_AIR_API_KEY"), read_key = NULL) { +get_sensor_data <- function(sensor_index, + fields, + purple_air_api_key = Sys.getenv("PURPLE_AIR_API_KEY"), + read_key = NULL) { if (!rlang::is_integer(as.integer(sensor_index))) cli::cli_abort("sensor_index must be an integer") if (!rlang::is_character(fields)) cli::cli_abort("fields must be a character") resp <- diff --git a/R/get_sensors_data.R b/R/get_sensors_data.R index 9cf4a97..3fba905 100644 --- a/R/get_sensors_data.R +++ b/R/get_sensors_data.R @@ -1,18 +1,19 @@ -#' get sensors data +#' Get Sensors Data #' #' Retrieves the latest data of multiple sensors matching the provided parameters. #' Find more details on sensor fields at https://api.purpleair.com/#api-sensors-get-sensors-data. #' @param x an input object used to define multiple sensors: -#' - integer (or numeric or character) vector will select sensors based on `sensor_index` (API: `show_only`) -#' - st_bbox object will select sensors geographically (API: `nwlat`, `nwlon`, `selat`, `selon`) -#' - POSIXct object will select sensors modified since then (API: `modified_since`) +#' - an integer (or numeric or character) vector will select sensors based on `sensor_index` (API: `show_only`) +#' - a st_bbox object will select sensors geographically (API: `nwlat`, `nwlon`, `selat`, `selon`) +#' - a POSIXct object will select sensors modified since the given time (API: `modified_since`) #' @param fields A character vector of which 'sensor data fields' to return #' @param location_type character; restrict to only "outside" or "inside" sensors (Outside: 0, Inside: 1) #' @param max_age integer; filter results to only include sensors modified or updated within the last number of seconds #' @param purple_air_api_key Your PurpleAir API `READ` key -#' @param read_keys TODO A character vector of keys required to read data from private devices -#' @returns a list of sensor data, named by the provided `fields` +#' @param read_keys A character vector of keys required to read data from private devices +#' @returns A list of sensor data, named by the provided `fields` #' @export +#' @seealso get_sensor_data #' @examples #' # get sensors data by integer, numeric, or character vector of `sensor_index` #' get_sensors_data( @@ -34,8 +35,12 @@ #' get_sensors_data(fields = c("name")) #' # sensors modified in the last 60 seconds #' get_sensors_data(as.POSIXct(Sys.time()) - 60, fields = "name") -get_sensors_data <- function(x, fields, location_type = c("both", "inside", "outside"), max_age = as.integer(604800), purple_air_api_key = Sys.getenv("PURPLE_AIR_API_KEY"), read_keys = NULL) { - # TODO support multiple read keys +get_sensors_data <- function(x, + fields, + location_type = c("both", "inside", "outside"), + max_age = as.integer(604800), + purple_air_api_key = Sys.getenv("PURPLE_AIR_API_KEY"), + read_keys = NULL) { if (!rlang::is_character(fields)) cli::cli_abort("fields must be a character") if (!rlang::is_integer(max_age)) cli::cli_abort("max_age must be an integer") location_type <- rlang::arg_match(location_type) @@ -98,7 +103,5 @@ get_sensors_data <- function(x, fields, location_type = c("both", "inside", "out purrr::list_rbind() |> tibble::as_tibble() if ("last_seen" %in% resp$fields) out$last_seen <- as.POSIXct.numeric(out$last_seen) - # TODO return metadata how? - md <- purrr::discard_at(resp, c("fields", "data")) return(out) } diff --git a/R/purple_air_request.R b/R/purple_air_request.R index 77d407d..d2ab9a2 100644 --- a/R/purple_air_request.R +++ b/R/purple_air_request.R @@ -26,5 +26,3 @@ purple_air_request <- function(purple_air_api_key = Sys.getenv("PURPLE_AIR_API_K if (resource == "sensor_history") req <- httr2::req_url_path_append(req, "sensors", sensor_index, "history") return(req) } - -# https://api.purpleair.com/#api-sensors-get-sensor-data diff --git a/README.Rmd b/README.Rmd index 2eafc8b..41c3d7e 100644 --- a/README.Rmd +++ b/README.Rmd @@ -16,7 +16,7 @@ knitr::opts_chunk$set( # PurpleAir -[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental) +[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable) [![CRAN status](https://www.r-pkg.org/badges/version/PurpleAir)](https://CRAN.R-project.org/package=PurpleAir) [![R-CMD-check](https://github.com/cole-brokamp/PurpleAir/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/cole-brokamp/PurpleAir/actions/workflows/R-CMD-check.yaml) @@ -41,7 +41,7 @@ pak::pak("cole-brokamp/PurpleAir") library(PurpleAir) ``` -Querying data from the PurpleAir API requires a free [PurpleAir Developer API key](https://develop.purpleair.com/sign-in?redirectURL=%2Fdashboards%2Fkeys) linked to a Google account. Functions in the package each take a `purple_air_api_key` argument or your key can be stored in an environment variable called `PURPLE_AIR_API_KEY`). To check your key, use: +Querying data from the PurpleAir API requires a free [PurpleAir Developer API key](https://develop.purpleair.com/sign-in?redirectURL=%2Fdashboards%2Fkeys) linked to a Google account. Functions in the package each take a `purple_air_api_key` argument or your key can be stored in an environment variable called `PURPLE_AIR_API_KEY`. To check your key, use: ```{r} check_api_key(Sys.getenv("PURPLE_AIR_API_KEY")) @@ -61,7 +61,7 @@ get_sensors_data(x = as.integer(c(175257, 175413)), fields = c("name", "last_seen", "pm2.5_cf_1", "pm2.5_atm")) ``` -a geographic bounding box, +a geographic [bounding box](http://bboxfinder.com), ```{r} sf::st_bbox( diff --git a/man/check_api_key.Rd b/man/check_api_key.Rd index f4ced88..cdf7a54 100644 --- a/man/check_api_key.Rd +++ b/man/check_api_key.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/check_api_key.R \name{check_api_key} \alias{check_api_key} -\title{check purple air api key} +\title{Check Purple Air API Key} \usage{ check_api_key(purple_air_api_key = Sys.getenv("PURPLE_AIR_API_KEY")) } @@ -10,15 +10,20 @@ check_api_key(purple_air_api_key = Sys.getenv("PURPLE_AIR_API_KEY")) \item{purple_air_api_key}{A character that is your PurpleAir API \code{READ} key} } \value{ -if the key is valid, a message is emitted and the input is invisibly returned; +If the key is valid, a message is emitted and the input is invisibly returned; invalid keys will throw an R error which utilizes information from the underlying http error -to inform the user +to inform the user. } \description{ Use the PurpleAir API to validate your Purple Air API Key. -Find more details on this function at https://api.purpleair.com/#api-keys-check-api-key +Find more details on this function at https://api.purpleair.com/#api-keys-check-api-key. +Storing your key in the environment variable \code{PURPLE_AIR_API_KEY} is safer than storing it +in source code and is used by default in each PurpleAir function. } \examples{ check_api_key() try(check_api_key("foofy")) } +\seealso{ +get_organization_data +} diff --git a/man/get_organization_data.Rd b/man/get_organization_data.Rd index 7d9f314..96523c4 100644 --- a/man/get_organization_data.Rd +++ b/man/get_organization_data.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/get_organization_data.R \name{get_organization_data} \alias{get_organization_data} -\title{get organization data} +\title{Get Organization Data} \usage{ get_organization_data(purple_air_api_key = Sys.getenv("PURPLE_AIR_API_KEY")) } @@ -10,7 +10,7 @@ get_organization_data(purple_air_api_key = Sys.getenv("PURPLE_AIR_API_KEY")) \item{purple_air_api_key}{A character that is your PurpleAir API \code{READ} key} } \value{ -a list of organization info +A list of organization info } \description{ Use the PurpleAir API to retrieve information for the organization containing the provided api_key @@ -19,3 +19,6 @@ Find more details on this function at https://api.purpleair.com/#api-organizatio \examples{ get_organization_data() } +\seealso{ +check_api_key +} diff --git a/man/get_sensor_data.Rd b/man/get_sensor_data.Rd index dfdc87a..b74c679 100644 --- a/man/get_sensor_data.Rd +++ b/man/get_sensor_data.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/get_sensor_data.R \name{get_sensor_data} \alias{get_sensor_data} -\title{get sensor data} +\title{Get Sensor Data} \usage{ get_sensor_data( sensor_index, @@ -21,7 +21,7 @@ get_sensor_data( \item{read_key}{A character key required to read data from private devices} } \value{ -a list of sensor data, named by the provided \code{fields} +A list of sensor data, named by the provided \code{fields} } \description{ Retrieves the latest data of a single sensor matching the provided \code{sensor_index}. @@ -31,3 +31,6 @@ Find more details on sensor fields at https://api.purpleair.com/#api-sensors-get get_sensor_data(sensor_index = 175413, fields = c("name", "last_seen", "pm2.5_cf_1", "pm2.5_atm")) get_sensor_data(sensor_index = "175413", fields = c("name", "last_seen", "pm2.5_cf_1", "pm2.5_atm")) } +\seealso{ +get_sensors_data get_sensor_history +} diff --git a/man/get_sensors_data.Rd b/man/get_sensors_data.Rd index b64f11a..1e2ce0c 100644 --- a/man/get_sensors_data.Rd +++ b/man/get_sensors_data.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/get_sensors_data.R \name{get_sensors_data} \alias{get_sensors_data} -\title{get sensors data} +\title{Get Sensors Data} \usage{ get_sensors_data( x, @@ -16,9 +16,9 @@ get_sensors_data( \arguments{ \item{x}{an input object used to define multiple sensors: \itemize{ -\item integer (or numeric or character) vector will select sensors based on \code{sensor_index} (API: \code{show_only}) -\item st_bbox object will select sensors geographically (API: \code{nwlat}, \code{nwlon}, \code{selat}, \code{selon}) -\item POSIXct object will select sensors modified since then (API: \code{modified_since}) +\item an integer (or numeric or character) vector will select sensors based on \code{sensor_index} (API: \code{show_only}) +\item a st_bbox object will select sensors geographically (API: \code{nwlat}, \code{nwlon}, \code{selat}, \code{selon}) +\item a POSIXct object will select sensors modified since the given time (API: \code{modified_since}) }} \item{fields}{A character vector of which 'sensor data fields' to return} @@ -29,10 +29,10 @@ get_sensors_data( \item{purple_air_api_key}{Your PurpleAir API \code{READ} key} -\item{read_keys}{TODO A character vector of keys required to read data from private devices} +\item{read_keys}{A character vector of keys required to read data from private devices} } \value{ -a list of sensor data, named by the provided \code{fields} +A list of sensor data, named by the provided \code{fields} } \description{ Retrieves the latest data of multiple sensors matching the provided parameters. @@ -60,3 +60,6 @@ sf::st_bbox(c("xmin" = -84.82030, "ymin" = 39.02153, # sensors modified in the last 60 seconds get_sensors_data(as.POSIXct(Sys.time()) - 60, fields = "name") } +\seealso{ +get_sensor_data +}