A function to retrieve Github Releases of taxonomic resources (#247)

* Added function to retrieve different versions and tests * Updated documentation with new version system * Skip CI on connection tests * Update pkgdown yml * Added thumbnail of cheatsheet to README
traitecoevo · Nov 19, 2024 · c1a539a · c1a539a
1 parent 6a97a40
commit c1a539a
Show file tree

Hide file tree

Showing 20 changed files with 338 additions and 194 deletions.
diff --git a/.Rbuildignore b/.Rbuildignore
@@ -18,3 +18,5 @@
 ^CRAN-SUBMISSION$
 ^revdep
 ^.DS_Store
+^help
+
diff --git a/.gitignore b/.gitignore
@@ -12,3 +12,5 @@ docs/
 /doc/
 /Meta/
 revdep/
+inst/cheatsheet/APCalign-cheatsheet.pptx
+inst/cheatsheet/establishment-means.pdf
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,6 +1,6 @@
 Package: APCalign
 Title: Resolving Plant Taxon Names Using the Australian Plant Census
-Version: 1.1.1
+Version: 1.1.2
 Authors@R: c(
   person(given = "Daniel", family = "Falster", role = c("aut", "cre", "cph"), email = "[email protected]", comment = c(ORCID = "0000-0002-9814-092X")),
   person(given = "Elizabeth", family = "Wenk", role = c("aut", "ctb"), email = "[email protected]", comment = c(ORCID = "0000-0001-5640-5910")),

diff --git a/NAMESPACE b/NAMESPACE
@@ -5,6 +5,7 @@ export(create_species_state_origin_matrix)
 export(create_taxonomic_update_lookup)
 export(default_version)
 export(get_apc_genus_family_lookup)
+export(get_versions)
 export(load_taxonomic_resources)
 export(native_anywhere_in_australia)
 export(standardise_names)

diff --git a/NEWS.md b/NEWS.md
@@ -1,3 +1,6 @@
+# APCalign 1.1.2
+
+- Added `get_versions()`
 
 # APCalign 1.1.0
 

diff --git a/R/APCalign-package.R b/R/APCalign-package.R
@@ -99,7 +99,8 @@ utils::globalVariables(
     "accepted_name_2",
     "alternative_accepted_name_tmp",
     "pro_parte",
-    "suggested_collapsed_name"
+    "suggested_collapsed_name",
+    "versions"
   )
 )
 
diff --git a/R/load_taxonomic_resources.R b/R/load_taxonomic_resources.R
@@ -27,7 +27,7 @@
 #' @examples
 #' \donttest{
 #' load_taxonomic_resources(stable_or_current_data="stable", 
-#' version="0.0.2.9000")}
+#' version="2024-10-11")}
 #'
 
 load_taxonomic_resources <-
@@ -302,7 +302,7 @@ load_taxonomic_resources <-
 ##'
 ##'
 ##' # Load the a stable version of the dataset
-##' dataset_access_function(version="0.0.2.9000",type = "stable")
+##' dataset_access_function(version="2024-10-11",type = "stable")
 ##'
 ##' @noRd
 dataset_access_function <-
@@ -487,3 +487,45 @@ dataset_get <- function(version = default_version(),
 
   }
 }
+
+
+#' Which versions of taxonomic resources are available?
+#'
+#' @return tibble of dates when APC/APNI resources were downloaded as a Github Release
+#' @export
+#'
+#' @examples
+#' get_versions()
+get_versions <- function() {
+  # Check if there is internet connection
+  ## Dummy variable to allow testing of network
+  network <- as.logical(Sys.getenv("NETWORK_UP", unset = TRUE)) 
+
+  if (!curl::has_internet() | !network) { # Simulate if network is down
+    message("No internet connection, please retry with stable connection (default_version)")
+    return(invisible(NULL))
+  } else {
+
+    # Get all the releases
+    url <-
+      paste0(
+        "https://api.github.com/repos/",
+        "traitecoevo",
+        "/",
+        "APCalign",
+        "/releases"
+      )
+
+    response <- httr::GET(url)
+
+    if(httr::http_error(response) | !network){
+      message("API currently down, try again later")
+      return(invisible(NULL))
+    } else
+      release_data <- httr::content(response, "text") |> jsonlite::fromJSON()
+
+    # Create table
+    dplyr::tibble(versions = unique(release_data$tag_name) |> sort(decreasing = TRUE)) |> 
+      dplyr::filter(!versions == "2020-05-14") #Excluding first ever release because it is not in parquet format
+  }
+}
diff --git a/README.Rmd b/README.Rmd
@@ -29,31 +29,28 @@ library(APCalign)
 `APCalign` uses the [Australian Plant Census (APC)](https://biodiversity.org.au/nsl/services/search/taxonomy) and [Australian Plant Name Index](https://biodiversity.org.au/nsl/services/search/names) to align and update Australian plant taxon name strings. 'APCalign' also supplies information about
 the established status (native/introduced) of plant taxa across different states/territories. It's useful for updating species list and intersecting them with the APC consensus understanding of established status (native/introduced).
 
-## Installation 
+## Installation 🛠️
 
 From CRAN:
 
-
 ```{r install, eval= FALSE}
  install.packages("APCalign")
+
+library(APCalign)
 ```
 
- OR for the github version:
+OR for the GitHub version:
 
 ```{r install2, eval= FALSE}
-
- install.packages("remotes")
- remotes::install_github("traitecoevo/APCalign")
+install.packages("remotes")
+remotes::install_github("traitecoevo/APCalign")
 ```
 
 ## A quick demo
 
 Generating a look-up table can be done with just one function:
 
 ```{r,message=FALSE}
-
-library(APCalign)
-
 create_taxonomic_update_lookup( 
   taxa = c(
     "Banksia integrifolia",
@@ -63,10 +60,9 @@ create_taxonomic_update_lookup(
 )
 ```
 
-if you're going to use APCalign more than once, it will save you time to load the taxonomic resources into memory first:
+If you're going to use `APCalign` more than once, it will save you time to load the taxonomic resources into memory first:
 
 ```{r,message=FALSE}
-
 tax_resources <- load_taxonomic_resources()
 
 create_taxonomic_update_lookup( 
@@ -83,36 +79,43 @@ create_taxonomic_update_lookup(
 Checking for a list of species to see if they are classified as Australian natives:
 
 ```{r, message=FALSE}
-
 native_anywhere_in_australia(c("Eucalyptus globulus","Pinus radiata"), resources = tax_resources)
 
 ```
 
 Getting a family lookup table for genera from the specified taxonomy:
 
 ```{r, message=FALSE}
-
 get_apc_genus_family_lookup(c("Eucalyptus",
                               "Pinus",
                               "Actinotus",
                               "Banksia",
                               "Acacia",
                               "Triodia"), 
                             resources = tax_resources)
-
 ```
 
-
-## Shiny application
+## Shiny application ✨
 
 We also developed a shiny application for non-R users to update and align their taxonomic names. You can find the application here: https://unsw.shinyapps.io/APCalign-app
 
-## Learn more
+## Cheatsheet
+
+<a href="https://github.com/traitecoevo/APCalign/tree/master/inst/cheatsheet/APCalign-cheatsheet.pdf"><img src="man/figures/APCalign-cheatsheet.png" width="60%"/></a>
+
+## Learn more 📚
 
 Highly recommend looking at our [Getting Started](https://traitecoevo.github.io/APCalign/articles/APCalign.html) vignette to learn about how to use `APCalign`. You can also learn more about our [taxa matching  algorithm](https://traitecoevo.github.io/APCalign/articles/updating-taxon-names.html).
 
+## Show us support 💛
+
+Please consider citing our work, we are really proud of it!
+
+```{r}
+citation("APCalign")
+```
 
-## Found a bug? 
+## Found a bug? 🐛
 
 Did you come across an unexpected taxon name change? Elusive error you can't debug - [submit an issue](https://github.com/traitecoevo/APCalign/issues) and we will try our best to help.
 

diff --git a/README.md b/README.md
@@ -21,86 +21,81 @@ taxa across different states/territories. It’s useful for updating
 species list and intersecting them with the APC consensus understanding
 of established status (native/introduced).
 
-## Installation
+## Installation 🛠️
 
 From CRAN:
 
 ``` r
  install.packages("APCalign")
-```
 
-OR for the github version:
+library(APCalign)
+```
 
+OR for the GitHub version:
 
 ``` r
- install.packages("remotes")
- remotes::install_github("traitecoevo/APCalign")
+install.packages("remotes")
+remotes::install_github("traitecoevo/APCalign")
 ```
 
 ## A quick demo
 
 Generating a look-up table can be done with just one function:
 
 ``` r
-
-library(APCalign)
-
 create_taxonomic_update_lookup( 
   taxa = c(
     "Banksia integrifolia",
     "Acacia longifolia",
     "Commersonia rosea"
     )
 )
-#> ================================================================================================================================================================
-#> # A tibble: 3 × 12
-#>   original_name       aligned_name accepted_name suggested_name genus taxon_rank
-#>   <chr>               <chr>        <chr>         <chr>          <chr> <chr>     
-#> 1 Banksia integrifol… Banksia int… Banksia inte… Banksia integ… Bank… species   
-#> 2 Acacia longifolia   Acacia long… Acacia longi… Acacia longif… Acac… species   
-#> 3 Commersonia rosea   Commersonia… Androcalva r… Androcalva ro… Andr… species   
-#> # ℹ 6 more variables: taxonomic_dataset <chr>, taxonomic_status <chr>,
-#> #   scientific_name <chr>, aligned_reason <chr>, update_reason <chr>,
-#> #   number_of_collapsed_taxa <dbl>
 ```
 
-if you’re going to use APCalign more than once, it will save you time to
-load the taxonomic resources into memory first:
+    #> ================================================================================================================================================================
+    #> # A tibble: 3 × 12
+    #>   original_name       aligned_name accepted_name suggested_name genus taxon_rank
+    #>   <chr>               <chr>        <chr>         <chr>          <chr> <chr>     
+    #> 1 Banksia integrifol… Banksia int… Banksia inte… Banksia integ… Bank… species   
+    #> 2 Acacia longifolia   Acacia long… Acacia longi… Acacia longif… Acac… species   
+    #> 3 Commersonia rosea   Commersonia… Androcalva r… Androcalva ro… Andr… species   
+    #> # ℹ 6 more variables: taxonomic_dataset <chr>, taxonomic_status <chr>,
+    #> #   scientific_name <chr>, aligned_reason <chr>, update_reason <chr>,
+    #> #   number_of_collapsed_taxa <dbl>
 
-``` r
+If you’re going to use `APCalign` more than once, it will save you time
+to load the taxonomic resources into memory first:
 
+``` r
 tax_resources <- load_taxonomic_resources()
-#> ================================================================================================================================================================
 ```
 
-``` r
+    #> ================================================================================================================================================================
 
-create_taxonomic_update_lookup( 
-  taxa = c(
-    "Banksia integrifolia",
-    "Acacia longifolia",
-    "Commersonia rosea",
-    "not a species"
-    ),
-  resources = tax_resources
-)
-#> # A tibble: 4 × 12
-#>   original_name       aligned_name accepted_name suggested_name genus taxon_rank
-#>   <chr>               <chr>        <chr>         <chr>          <chr> <chr>     
-#> 1 Banksia integrifol… Banksia int… Banksia inte… Banksia integ… Bank… species   
-#> 2 Acacia longifolia   Acacia long… Acacia longi… Acacia longif… Acac… species   
-#> 3 Commersonia rosea   Commersonia… Androcalva r… Androcalva ro… Andr… species   
-#> 4 not a species       <NA>         <NA>          <NA>           <NA>  <NA>      
-#> # ℹ 6 more variables: taxonomic_dataset <chr>, taxonomic_status <chr>,
-#> #   scientific_name <chr>, aligned_reason <chr>, update_reason <chr>,
-#> #   number_of_collapsed_taxa <dbl>
-```
+    create_taxonomic_update_lookup( 
+      taxa = c(
+        "Banksia integrifolia",
+        "Acacia longifolia",
+        "Commersonia rosea",
+        "not a species"
+        ),
+      resources = tax_resources
+    )
+    #> # A tibble: 4 × 12
+    #>   original_name       aligned_name accepted_name suggested_name genus taxon_rank
+    #>   <chr>               <chr>        <chr>         <chr>          <chr> <chr>     
+    #> 1 Banksia integrifol… Banksia int… Banksia inte… Banksia integ… Bank… species   
+    #> 2 Acacia longifolia   Acacia long… Acacia longi… Acacia longif… Acac… species   
+    #> 3 Commersonia rosea   Commersonia… Androcalva r… Androcalva ro… Andr… species   
+    #> 4 not a species       <NA>         <NA>          <NA>           <NA>  <NA>      
+    #> # ℹ 6 more variables: taxonomic_dataset <chr>, taxonomic_status <chr>,
+    #> #   scientific_name <chr>, aligned_reason <chr>, update_reason <chr>,
+    #> #   number_of_collapsed_taxa <dbl>
 
 Checking for a list of species to see if they are classified as
 Australian natives:
 
 ``` r
-
 native_anywhere_in_australia(c("Eucalyptus globulus","Pinus radiata"), resources = tax_resources)
 #> # A tibble: 2 × 2
 #>   species             native_anywhere_in_aus
@@ -112,7 +107,6 @@ native_anywhere_in_australia(c("Eucalyptus globulus","Pinus radiata"), resources
 Getting a family lookup table for genera from the specified taxonomy:
 
 ``` r
-
 get_apc_genus_family_lookup(c("Eucalyptus",
                               "Pinus",
                               "Actinotus",
@@ -131,21 +125,51 @@ get_apc_genus_family_lookup(c("Eucalyptus",
 #> 6 Triodia    Poaceae
 ```
 
-## Shiny application
+## Shiny application ✨
 
 We also developed a shiny application for non-R users to update and
 align their taxonomic names. You can find the application here:
 <https://unsw.shinyapps.io/APCalign-app>
 
-## Learn more
+## Cheatsheet
+
+<a href="https://github.com/traitecoevo/APCalign/tree/master/inst/cheatsheet/APCalign-cheatsheet.pdf"><img src="man/figures/APCalign-cheatsheet.png" width="60%"/></a>
+
+## Learn more 📚
 
 Highly recommend looking at our [Getting
 Started](https://traitecoevo.github.io/APCalign/articles/APCalign.html)
 vignette to learn about how to use `APCalign`. You can also learn more
 about our [taxa matching
 algorithm](https://traitecoevo.github.io/APCalign/articles/updating-taxon-names.html).
 
-## Found a bug?
+## Show us support 💚
+
+Please consider citing our work, we are really proud of it!
+
+``` r
+citation("APCalign")
+#> To cite package 'APCalign' in publications use:
+#> 
+#>   Wenk E, Cornwell W, Fuchs A, Kar F, Monro A, Sauquet H, Stephens R,
+#>   Falster D (2024). "APCalign: an R package workflow and app for
+#>   aligning and updating flora names to the Australian Plant Census."
+#>   _Australian Journal of Botany_. R package version: 1.0.1,
+#>   <https://www.biorxiv.org/content/10.1101/2024.02.02.578715v1>.
+#> 
+#> A BibTeX entry for LaTeX users is
+#> 
+#>   @Article{,
+#>     title = {APCalign: an R package workflow and app for aligning and updating flora names to the Australian Plant Census},
+#>     journal = {Australian Journal of Botany},
+#>     author = {Elizabeth Wenk and Will Cornwell and Ann Fuchs and Fonti Kar and Anna Monro and Herve Sauquet and Ruby Stephens and Daniel Falster},
+#>     year = {2024},
+#>     note = {R package version: 1.0.1},
+#>     url = {https://www.biorxiv.org/content/10.1101/2024.02.02.578715v1},
+#>   }
+```
+
+## Found a bug? 🐛
 
 Did you come across an unexpected taxon name change? Elusive error you
 can’t debug - [submit an
-Original file line number
+Diff line change
@@ Expand Up / @@ -18,3 +18,5 @@ @@
     ^CRAN-SUBMISSION$
     ^revdep
     ^.DS_Store
+    ^help