Complete API transition before v0.9.0 (#108)

.travis.yml

@@ -1,6 +1,9 @@
 # R for travis: see documentation at https://docs.travis-ci.com/user/languages/r
 
 language: R
+r:
+  - release
+  - devel
 sudo: false
 cache: packages
 
@@ -10,3 +13,4 @@ git:
 before_install:
   - echo "BacDive_email=$ID" > ~/.Renviron
   - echo "BacDive_password=$PW" >> ~/.Renviron
+  - tlmgr install texinfo

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: BacDiveR
 Title: Programmatic Interface For The DSMZ' Bacterial Diversity Metadatabase
-Version: 0.8.0
-Date: 2019-01-28
+Version: 0.9.0
+Date: 2019-04-30
 Authors@R: 
     person(given = "Katrin",
            family = "Leinweber",
@@ -20,12 +20,12 @@ BugReports: https://github.com/TIBHannover/BacDiveR/issues
 Imports: 
     httr (>= 1.3.0),
     jsonlite (>= 1.5),
-    purrr (>= 0.2.5),
     utils (>= 3.5.0)
 Suggests:
     ggplot2 (>= 3.0.0),
     knitr (>= 1.20),
     magrittr (>= 1.5),
+    purrr (>= 0.2.5),
     rmarkdown (>= 1.10),
     spelling (>= 1.2),
     testthat (>= 2.0.0)

NAMESPACE

@@ -4,8 +4,5 @@ export(bd_retrieve)
 export(bd_retrieve_by_culture)
 export(bd_retrieve_by_search)
 export(bd_retrieve_by_sequence)
-export(bd_retrieve_data)
 export(bd_retrieve_taxon)
 export(prepare_Renviron)
-export(retrieve_data)
-export(retrieve_search_results)

NEWS.md

@@ -1,7 +1,3 @@
-All notable changes to this project will be documented in this file.
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
 ## Unreleased
 
 ### Added
@@ -11,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 ### Security
 
+## BacDiveR 0.9.0
+
+All notable changes to this project will be documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+### Changed
+
+- NEW API: The deprecations announced in v0.8.0 are now completed: The
+  `bd_retrieve()` family of functions has replaced `retrieve_data()` and
+  `retrieve_search_results()` has been renamed to `bd_retrieve_by_search()`,
+  see #96. **Please update scripts and other downstream code that use BacDiveR.**
+- `purrr` is no longer an imported / required dependency, but only suggested
+  due to use in the [introductory vignette], see #98.
+
+[introductory vignette]: ../articles/BacDive-ing-in.html#extracting-data-fields
+
+
+## BacDiveR 0.8.1
+
+### Changed
+
+- Warning message about no data being found is more informative now
+- Documentation to follow BacDive's database updates
+- Use pandoc 2.7.2 to generate the website
+
 
 ## BacDiveR 0.8.0
 

R/bd_retrieve.R

@@ -1,9 +1,5 @@
 #' Retrieve (a) Dataset(s) from BacDive
 #'
-#' This function family replaces the old `retrieve_data(searchTerm = "…", searchType = "…")`
-#' function. It still works, but is deprecated and will be removed soon.
-#' Please update your scripts to these new functions!
-#'
 #' @param id Mandatory character string or integer. The BacDive strain ID
 #'   whose data you want to retrieve.
 #'

R/retrieve_search_results.R → R/bd_retrieve_by_search.R

@@ -1,9 +1,3 @@
-#' @export
-retrieve_search_results <- function(queryURL) {
-  .Deprecated("bd_retrieve_by_search")
-  bd_retrieve_by_search(queryURL)
-}
-
 #' Retrieve the Results of an Advanced Search
 #'
 #' [BacDive.DSMZ.de/AdvSearch](https://bacdive.dsmz.de/advsearch) returns a
@@ -18,7 +12,15 @@ retrieve_search_results <- function(queryURL) {
 #' @export
 #'
 #' @examples
-#'   plant_animal_pathogens <- bd_retrieve_by_search(queryURL = "https://bacdive.dsmz.de/advsearch?site=advsearch&searchparams%5B5%5D%5Bsearchterm%5D=1&searchparams%5B157%5D%5Bsearchterm%5D=1&searchparams%5B158%5D%5Bsearchterm%5D=1&advsearch=search")
+#'   plant_animal_pathogens <-
+#'     bd_retrieve_by_search(
+#'       queryURL = paste(
+#'         "https://bacdive.dsmz.de/advsearch?site=advsearchsearch",
+#'         "params%5B5%5D%5Bsearchterm%5D=1",
+#'         "searchparams%5B157%5D%5Bsearchterm%5D=1",
+#'         "searchparams%5B158%5D%5Bsearchterm%5D=1",
+#'         "advsearch=search", sep = "&")
+#'         )
 bd_retrieve_by_search <- function(queryURL) {
   # guard against other URLs
   if (!grepl(pattern = "^https:\\/\\/bacdive\\.dsmz\\.de\\/advsearch", queryURL) |

R/retrieve_data.R → R/bd_retrieve_data.R

@@ -1,29 +1,7 @@
-#' @export
-retrieve_data <- function(searchTerm,
-                          searchType = "taxon") {
-  .Deprecated(
-    c(
-      "bd_retrieve_by_culture",
-      "bd_retrieve_by_sequence",
-      "bd_retrieve",
-      "bd_retrieve_taxon"
-    )
-  )
-
-  # guard against invalid input
-  searchTerm <- sanitise_term(searchTerm)
+#' @keywords internal
+bd_retrieve_data <- function(searchTerm, searchType) {
   searchType <- sanitise_type(searchType)
-
-  bd_retrieve_data(searchTerm, searchType)
-}
-
-#' @export
-bd_retrieve_data <- function(searchTerm, searchType = "taxon") {
-
-  # expand taxon/species
-  if (identical(searchType, "taxon") & grepl("\\s", searchTerm)) {
-    searchTerm <- sanitise_taxon(searchTerm)
-  }
+  searchTerm <- sanitise_term(searchTerm, searchType)
 
   payload <- download(construct_url(searchTerm, searchType))
 
@@ -43,11 +21,9 @@ bd_retrieve_data <- function(searchTerm, searchType = "taxon") {
   }
   else if (identical(payload$detail, "Not found")) {
     warning(
-      "BacDive responded: 'Not found' to our query for '",
-      searchType,
-      " = ",
-      searchTerm,
-      "'. Please double-check both these query parameters, or try https://BacDive.DSMZ.de/AdvSearch"
+      "BacDive responded: '", payload$detail,
+      "' to our last search for '", searchTerm,
+      "'. Please double-check this parameter or try https://TIBHannover.GitHub.io/BacDiveR/articles/pre-configuring-advanced-searches-and-retrieving-the-results.html"
     )
 
     list()
@@ -76,15 +52,12 @@ is_results_list <- function(payload) {
 }
 
 is_ID_reference <- function(payload) {
-  all.equal(nrow(payload), ncol(payload), 1) &&
-    # class(payload) == "data.frame" &&
-    names(payload) == "url"
-  # && grepl("https://bacdive.dsmz.de/api/bacdive/bacdive_id/\\d+/",
-  #          payload$url)
+  all.equal(nrow(payload), ncol(payload), 1) &
+    "url" %in% names(payload)
 }
 
 
-sanitise_term <- function(searchTerm) {
+sanitise_term <- function(searchTerm, searchType) {
   if (grepl(
     pattern = "[^[:alnum:] ]",
     x = searchTerm,
@@ -94,6 +67,9 @@ sanitise_term <- function(searchTerm) {
     stop(
       "Illegal character detected! My apologies, but your search can only contain letters, numbers and white-space. Abbreviating genus names (e.g. 'B. subtilis') is not supported. Please spell out your searchTerm ('Bacillus subtilis'), don't use any 'special' characters and try again."
     )
+  } else if (identical(searchType, "taxon") & grepl("\\s", searchTerm)) {
+    gsub(pattern = "\\s", replacement = "/", searchTerm)
+    # expand "Taxon species" to "taxon/species"
   } else {
     searchTerm
   }
@@ -114,6 +90,16 @@ sanitise_type <- function(searchType) {
 }
 
 
-sanitise_taxon <- function(searchTerm) {
-  gsub(pattern = "\\s", replacement = "/", searchTerm)
+construct_url <- function(searchTerm,
+                          searchType = "bacdive_id") {
+  utils::URLencode(
+    paste0(
+      "https://bacdive.dsmz.de/api/bacdive/",
+      searchType,
+      "/",
+      searchTerm,
+      "/",
+      "?format=json"
+    )
+  )
 }

R/bd_retrieve_taxon.R

@@ -3,8 +3,8 @@
 #'   like "B. halotolerans" are not allowed!
 #' @export
 #' @examples
-#'   datasets_Bh <- bd_retrieve_taxon(name = "Bacillus halotolerans")
-#'   datasets_Thh <- bd_retrieve_taxon(name = "Tetragenococcus halophilus halophilus")
+#' datasets_Bh <- bd_retrieve_taxon(name = "Bacillus halotolerans")
+#' datasets_Thh <- bd_retrieve_taxon(name = "Tetragenococcus halophilus halophilus")
 bd_retrieve_taxon <- function(name) {
   bd_retrieve_data(searchTerm = name, searchType = "taxon")
 }

R/util-aggregate_datasets.R

@@ -2,7 +2,7 @@ aggregate_datasets <- function(payload, from_IDs = FALSE) {
   if (from_IDs) {
     warn_slow_download(length(payload))
     IDs <- payload
-    URLs <- purrr::map_chr(.x = IDs, .f = construct_url)
+    URLs <- lapply(X = IDs, FUN = construct_url)
   }
   else {
     warn_slow_download(payload$count)
@@ -17,7 +17,7 @@ aggregate_datasets <- function(payload, from_IDs = FALSE) {
     max(as.integer(IDs)),
     " (but not necessarily contiguously): "
   )
-  taxon_data <- purrr::map(URLs, download)
+  taxon_data <- lapply(X = URLs, download)
   names(taxon_data) <- IDs
 
   taxon_data

R/util-warn_slow_download.R

@@ -32,7 +32,7 @@ warn_slow_download <- function(N_datasets) {
     #   bd_retrieve_taxon("Bacillus subtilis subtilis")
     #   bd_retrieve_taxon("Pseudomonas")
     #   bd_retrieve_by_search("https://bacdive.dsmz.de/advsearch?advsearch=search&site=advsearch&searchparams%5B70%5D%5Bcontenttype%5D=text&searchparams%5B70%5D%5Btypecontent%5D=contains&searchparams%5B70%5D%5Bsearchterm%5D=archaea")
-    #   retrieve_search_results("https://bacdive.dsmz.de/advsearch?advsearch=search&site=advsearch&searchparams%5B70%5D%5Bcontenttype%5D=text&searchparams%5B70%5D%5Btypecontent%5D=contains&searchparams%5B70%5D%5Bsearchterm%5D=bacteria")
+    #   bd_retrieve_by_search("https://bacdive.dsmz.de/advsearch?advsearch=search&site=advsearch&searchparams%5B70%5D%5Bcontenttype%5D=text&searchparams%5B70%5D%5Btypecontent%5D=contains&searchparams%5B70%5D%5Bsearchterm%5D=bacteria")
     # resulting in: 31.83312, 260.64956, 171.851 and 25353.37 s respectively, indicating a download
     # rate of about 2 to 4 datasets per second.
   }

README.md

@@ -1,4 +1,4 @@
-# BacDiveR [![lifecycle](https://img.shields.io/badge/lifecycle-maturing-blue.svg)](https://www.tidyverse.org/lifecycle/#maturing) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.1308060.svg)](https://zenodo.org/record/1308060)
+# BacDiveR [![lifecycle](https://img.shields.io/badge/lifecycle-maturing-blue.svg)](https://www.tidyverse.org/lifecycle/#maturing) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.1308060.svg)](https://zenodo.org/record/1308060) [![Travis build status](https://travis-ci.org/TIBHannover/BacDiveR.svg?branch=master)](https://travis-ci.org/TIBHannover/BacDiveR)
 
 This R package provides a programmatic interface to the [Bacterial Diversity Metadatabase][BD] of the [DSMZ (German Collection of Microorganisms and Cell Cultures)][DMSZ]. BacDiveR helps you improve your research on bacteria and archaea by providing access to "structured information on [...] their taxonomy, morphology, physiology, cultivation, geographic origin, application, interaction" and more ([Söhngen et al. 2016](#references)). Specifically, you can: