new API for BacDiveR

[katrinleinweber]

Currently, the API looks as follows:

• retrieve_search_results(queryURL)
• retrieve_data(searchTerm, searchType = "…") where … is exactly the "API endpoint" of BacDive's web service.

I'm considering a more stringent design, that

1. reads more fluently, e.g.:
   • retrieve_by_culture(collection_no = "…")
   • …_sequence(accession ="…")
   • …_taxon(name = "…") (maybe with genus = "…", species = "…", subspecies = "…" separately & optionally)
2. hides the actual data download/retrieval …_by_id() through the bacdive_id endpoint from the user. The 3 "front" functions above could return the URLs or IDs to be downloaded, which could be fed into …_by_id().

Additional considerations:

1. maybe use download as the verb (although less common than retrieve)
2. maybe use BD_ or bd_ in front like ROpenSci's function naming guide suggests. This would be a workable abbreviation for BacDive data, but is already in use by other packages (not with _download or _retrieve, though).
3. or BacDive_… or bacbive_…?

Feedback on this major change, the naming details, etc. is very welcome :-)

• draw mermaid diagram:

graph TD

A(BD_retrieve_culture) --chr: collectionno--> J
B(BD_retrieve_sequence) --chr: accession--> J
C(BD_retrieve_by_taxon) --chr: name, genus, species, subspecies--> J
J[.json] --> SM

SM(single_or_multi?) --chr--> E
SM--multi--> G
G(aggregate_result_URLs) --chr_list--> E

D(BD_retrieve_by_search) --chr: query_URL--> Q
Q[.csv] --> E
E(extract_IDs) --chr_list--> U

I(BD_retrieve_by_id) --chr: ID--> U

U(construct_URL) --chr: URL--> S
S[dataset_or_sets]

[katrinleinweber]

I need to simplify that scheme to a flowchart with only high-level function calls & server responses:

graph TD

FC(function calls)
SR[server response]

cul(BD_retrieve_culture<br>collectionno='chr') --> JU
seq(BD_retrieve_sequence<br>accession='chr') --> JU
JU[.json url] -- JSON2list --> rb_URL

tax(BD_retrieve_by_taxon<br>name='chr')--> JR
JR[.json results] --> rb_URL

rb_adv(BD_retrieve_by_search<br>query_URL='chr') --> CSV
CSV[.csv] -- lines2list --> rb_ID

rb_ID(BD_retrieve_by_id<br>ID='chr')--> rb_URL

rb_URL(BD_retrieve_by_URL<br>URL='chr') --> DSL
DSL[list with 1 or more dataset*s]


classDef public fill:white
class cul,seq,tax,rb_adv public

classDef WS stroke:#A30000
class cul,seq,tax,I WS

classDef AdvSearch stroke:#5290b2
class rb_adv AdvSearch

classDef semi_public fill:lightgrey
class rb_ID,rb_URL semi_public

[katrinleinweber]

An alternative, simpler idea might be to provide the above-mentioned "front" functions in parallel to (or on top of) the current retrieve_data(searchTerm = "…" , searchType = "…"):

graph TD

cul(bd_culture<br>collectionno='chr') --Type='culturecollectionno'--> rd

seq(bd_sequence<br>accession='chr') --Type='sequence'--> rd

tax(bd_taxon<br>name='chr')--Type='taxon'--> rd

bd_id --Type='bacdive_id'--> rd

rd(retrieve_data<br>Term='chr', Type='chr') --> DSL
DSL[list with 1 or more dataset*s]

rb_adv(bd_download_adv<br>searchURL='chr')--unchanged, just renamed-->DSL

This might lend itself to later converting this into object-oriented code.

• consider deprecation warning, see http://r-pkgs.had.co.nz/release.html#compatibility & https://github.com/search?q=org%3Atidyverse+deprecated & https://ropensci.org/technotes/2017/01/05/package-evolution/#functions-changing-function-names
• use @rdname to mass-document a function family (see purrr::map or dplyr::lead-lag)
• [-] write ADR No, already explained in the changelog

[katrinleinweber]

Or dive_in...:

• ...to_taxon(name = ...)
• ...to_culture(collection_number = ...)
• ...to_sequence(accession = ...)
• ...to_dataset(id = ...)
  ?