From 0ddd85249524d14d3e2241e73d0106efd0a29b44 Mon Sep 17 00:00:00 2001 From: Najko Jahn Date: Mon, 2 Jan 2017 16:39:11 +0100 Subject: [PATCH] improved documentation --- R/oadoi_fetch.r | 78 +++++++++++++++++-------------- man/oadoi_api_.Rd | 9 ++-- man/oadoi_fetch.Rd | 12 +++-- roadoi.Rproj | 1 + tests/testthat/test_oadoi_fetch.r | 3 ++ 5 files changed, 59 insertions(+), 44 deletions(-) diff --git a/R/oadoi_fetch.r b/R/oadoi_fetch.r index 69c035e..870e646 100644 --- a/R/oadoi_fetch.r +++ b/R/oadoi_fetch.r @@ -3,42 +3,50 @@ #' This is the main function to retrieve comprehensive open acccess status #' information from the oaDOI service. Please play nice with the API. At the #' moment only 10k request are allowed per user and day. -#' For more info see \url{http://oadoi.org/api} +#' For more info see \url{http://oadoi.org/api}. #' -#' @param dois character vector, search by a single DOI or many DOIs. A maximum -#' of 10,000 DOIs are allowed per request. -#' @param email character verctor, tell oaDOI your email adress and get notified +#' @param dois character vector, search by a single DOI or many DOIs. The API is limited +#' to 10,000 requests per day. If you need more, get in touch with +#' team@impactstory.org. +#' @param email character verctor, tell oaDOI your email adress to get notified #' if something breaks. It also helps oaDOI to keep track of usage! #' @param .progress Shows the \code{plyr}-style progress bar. Options are "none", "text", -#' "tk", "win", and "time". See \code{\link[plyr]{create_progress_bar}} for details -#' of each. By default, no progress bar is displayed. +#' "tk", "win", and "time". See \code{\link[plyr]{create_progress_bar}} for details +#' of each. By default, no progress bar is displayed. #' #' @return A tibble #' #' @examples \dontrun{ +#' oadoi_fetch("10.1016/j.shpsc.2013.03.020") #' oadoi_fetch(dois = c("10.1016/j.jbiotec.2010.07.030", #' "10.1186/1471-2164-11-245")) #' } #' #' @export -oadoi_fetch <- function(dois = NULL, email = NULL, .progress = "none") { - # limit - if (length(dois) > api_limit) - stop("The rate limit is 10k requests per day. - Get in touch with team@impactstory.org to get an upgrade.", .call = FALSE) - # validate dois - dois <- plyr::ldply(dois, doi_validate) - if (nrow(dois[dois$is_valid == FALSE,]) > 0) - warning("Found mal-formed DOIs, which will not be send to oaDOI") - dois <- dplyr::filter(dois, is_valid == TRUE) %>% - .$doi %>% - as.character() - plyr::ldply(dois, oadoi_api_, .progress = .progress) %>% - # wrap as tibble - dplyr::as_data_frame() -} +oadoi_fetch <- + function(dois = NULL, + email = NULL, + .progress = "none") { + # limit + if (length(dois) > api_limit) + stop( + "The rate limit is 10k requests per day. + Get in touch with team@impactstory.org to get an upgrade.", + .call = FALSE + ) + # validate dois + dois <- plyr::ldply(dois, doi_validate) + if (nrow(dois[dois$is_valid == FALSE, ]) > 0) + warning("Found mal-formed DOIs, which will not be send to oaDOI") + dois <- dplyr::filter(dois, is_valid == TRUE) %>% + .$doi %>% + as.character() + plyr::ldply(dois, oadoi_api_, .progress = .progress) %>% + # wrap as tibble + dplyr::as_data_frame() + } -#' Post one DOI to access open access status information. +#' Get open access status information. #' #' In general, use oadoi_fetch instead. It calls this method, returning open #' access status information from all your requests. @@ -53,17 +61,17 @@ oadoi_api_ <- function(dois = NULL, email = NULL) { u <- httr::modify_url(oadoi_baseurl(), query = args_(email = email), path = dois) - resp <- httr::GET( - u, - ua, - # be explicit about the API version roadoi has to request - add_headers( - Accept = paste0("application/x.oadoi.", oadoi_api_version(), "+json"))) + resp <- httr::GET(u, + ua, + # be explicit about the API version roadoi has to request + add_headers( + Accept = paste0("application/x.oadoi.", oadoi_api_version(), "+json") + )) - # parse json - if (httr::http_type(resp) != "application/json") { - stop("Ups, something went wrong, because API did not return json", - call. = FALSE) - } - jsonlite::fromJSON(content(resp, "text", encoding = "UTF-8"))$results + # parse json + if (httr::http_type(resp) != "application/json") { + stop("Ups, something went wrong, because API did not return json", + call. = FALSE) + } + jsonlite::fromJSON(content(resp, "text", encoding = "UTF-8"))$results } diff --git a/man/oadoi_api_.Rd b/man/oadoi_api_.Rd index 49af8b9..8a3ee5b 100644 --- a/man/oadoi_api_.Rd +++ b/man/oadoi_api_.Rd @@ -2,15 +2,16 @@ % Please edit documentation in R/oadoi_fetch.r \name{oadoi_api_} \alias{oadoi_api_} -\title{Post one DOI to access open access status information.} +\title{Get open access status information.} \usage{ oadoi_api_(dois = NULL, email = NULL) } \arguments{ -\item{dois}{character vector, search by a single DOI or many DOIs. A maximum -of 10,000 DOIs are allowed per request.} +\item{dois}{character vector, search by a single DOI or many DOIs. The API is limited +to 10,000 requests per day. If you need more, get in touch with +team@impactstory.org.} -\item{email}{character verctor, tell oaDOI your email adress and get notified +\item{email}{character verctor, tell oaDOI your email adress to get notified if something breaks. It also helps oaDOI to keep track of usage!} } \value{ diff --git a/man/oadoi_fetch.Rd b/man/oadoi_fetch.Rd index e3b8993..29be402 100644 --- a/man/oadoi_fetch.Rd +++ b/man/oadoi_fetch.Rd @@ -7,15 +7,16 @@ oadoi_fetch(dois = NULL, email = NULL, .progress = "none") } \arguments{ -\item{dois}{character vector, search by a single DOI or many DOIs. A maximum -of 10,000 DOIs are allowed per request.} +\item{dois}{character vector, search by a single DOI or many DOIs. The API is limited +to 10,000 requests per day. If you need more, get in touch with +team@impactstory.org.} -\item{email}{character verctor, tell oaDOI your email adress and get notified +\item{email}{character verctor, tell oaDOI your email adress to get notified if something breaks. It also helps oaDOI to keep track of usage!} \item{.progress}{Shows the \code{plyr}-style progress bar. Options are "none", "text", "tk", "win", and "time". See \code{\link[plyr]{create_progress_bar}} for details - of each. By default, no progress bar is displayed.} +of each. By default, no progress bar is displayed.} } \value{ A tibble @@ -24,10 +25,11 @@ A tibble This is the main function to retrieve comprehensive open acccess status information from the oaDOI service. Please play nice with the API. At the moment only 10k request are allowed per user and day. -For more info see \url{http://oadoi.org/api} +For more info see \url{http://oadoi.org/api}. } \examples{ \dontrun{ +oadoi_fetch("10.1016/j.shpsc.2013.03.020") oadoi_fetch(dois = c("10.1016/j.jbiotec.2010.07.030", "10.1186/1471-2164-11-245")) } diff --git a/roadoi.Rproj b/roadoi.Rproj index 497f8bf..270314b 100644 --- a/roadoi.Rproj +++ b/roadoi.Rproj @@ -18,3 +18,4 @@ StripTrailingWhitespace: Yes BuildType: Package PackageUseDevtools: Yes PackageInstallArgs: --no-multiarch --with-keep.source +PackageRoxygenize: rd,collate,namespace diff --git a/tests/testthat/test_oadoi_fetch.r b/tests/testthat/test_oadoi_fetch.r index 891fd13..23e39f0 100644 --- a/tests/testthat/test_oadoi_fetch.r +++ b/tests/testthat/test_oadoi_fetch.r @@ -4,14 +4,17 @@ test_that("oadoi_fetch returns", { a <- oadoi_fetch(dois = "10.7717/peerj.2323") b <- oadoi_fetch(dois = c("10.1038/ng.919", "10.1105/tpc.111.088682"), email = "test@test.com") + c <- oadoi_fetch("10.1016/j.shpsc.2013.03.020") # correct classes expect_is(a, "tbl_df") expect_is(b, "tbl_df") + expect_is(c, "tbl_df") # correct dimensions expect_equal(nrow(a), 1) expect_equal(nrow(b), 2) + expect_equal(nrow(c), 1) expect_warning(oadoi_fetch(dois = c("ldld", "10.1038/ng.3260")))