Updated documentation and website for austraits 3.0.0 (#130)

* Update README.Rmd * Returning tibble for flatten_database * Minor updates to dependnencies to pass R CMD check Remove reference to `summarise_trait_means` * Extract_data missing S3 class assign * Updated bootswatch --------- Co-authored-by: ehwenk <[email protected]>
traitecoevo · Nov 17, 2024 · 0c9f8a7 · 0c9f8a7
1 parent a0d902c
commit 0c9f8a7
Show file tree

Hide file tree

Showing 25 changed files with 942 additions and 7,699 deletions.
diff --git a/.gitignore b/.gitignore
@@ -43,6 +43,7 @@ doc/*.html
 # R Environment Variables
 .Renviron
 inst/doc
+inst/cheatsheet/
 /doc/
 /docs/
 /Meta/

diff --git a/NAMESPACE b/NAMESPACE
@@ -1,6 +1,5 @@
 # Generated by roxygen2: do not edit by hand
 
-S3method(print,traits.build)
 export("%>%")
 export(as_wide_table)
 export(bind_databases)
@@ -36,6 +35,7 @@ export(trait_pivot_wider)
 import(RefManageR)
 importFrom(lifecycle,deprecated)
 importFrom(magrittr,"%>%")
+importFrom(rlang,":=")
 importFrom(rlang,.data)
 importFrom(stats,family)
 importFrom(utils,methods)
diff --git a/R/austraits-package.R b/R/austraits-package.R
@@ -35,6 +35,7 @@ utils::globalVariables(c(
   "context_property",
   "contributor",
   "data",
+  "database",
   "dataset_id",
   "data_contributors",
   "identifier",

diff --git a/R/check_compatibility.R b/R/check_compatibility.R
@@ -5,6 +5,7 @@
 #' @param single_table_allowed logical for when the input might be a single table instead of a complete database; defaults to FALSE
 #'
 #' @return logical (T/F) output and messaging for uncompatible versions
+#' @keywords internal
 #'
 #' @examples
 #' \dontrun{
@@ -53,7 +54,7 @@ check_compatibility <- function(database, single_table_allowed = FALSE) {
 #' Check compatibility of traits table
 #'
 #' @param trait_data the traits table in a traits.build database
-#'
+#' @keywords internal
 #' @return logical, TRUE indicating version traits table came from traits.build version > 1.0
 
 check_traits_compatibility <- function(trait_data){

diff --git a/R/extract_data.R b/R/extract_data.R
@@ -10,7 +10,7 @@
 #' @param table Table within a traits.build database
 #' @param col Column name within the specified table.
 #' @param col_value Value (of column, from with a table) that is used to subset database. This can be a single value or a vector. It includes partial string matches. 
-#'
+#' @importFrom rlang :=
 #' @return subset traits.build database
 #' @export
 #'
@@ -232,14 +232,13 @@ extract_data <- function(database, table = NA, col, col_value) {
     # Reorder list to match database
     ret <- ret[c("traits", "locations", "contexts", "methods", "excluded_data", "taxonomic_updates", 
                  "taxa","contributors","sources","definitions","schema", "metadata","build_info")]
-
-    # Assign class
-    attr(data, "class") <- "traits.build"
 
   }
 
+  # Assign class
+  attr(ret, "class") <- "traits.build"
+
   ret
-
 }
 
 

diff --git a/R/flatten_database.R b/R/flatten_database.R
@@ -50,4 +50,6 @@ flatten_database <- function(database,
     join_taxonomic_updates(vars = vars$taxonomic_updates)
 
   combined_table <- combined_table_relational$traits
+
+  return(combined_table)
 }
diff --git a/R/print.traits.build.R b/R/print.traits.build.R
@@ -5,7 +5,7 @@
 #' @param \dots passed to print
 #'
 #' @return nicely printed table
-#' @export
+#' @keywords internal
 
 print.traits.build <- function(x, ...){
 

diff --git a/README.Rmd b/README.Rmd
@@ -32,15 +32,11 @@ library(dplyr)
 [![Codecov test coverage](https://codecov.io/gh/traitecoevo/austraits/branch/master/graph/badge.svg)](https://app.codecov.io/gh/traitecoevo/austraits?branch=master)
 <!-- badges: end -->
 
-`austraits` allow users to access, explore and wrangle data from the AusTraits database in `R`. This package includes several functions such as filtering and pivoting the dataset that we expect will come in handy. 
-
-**For R users**, access and manipulation of the data is assisted with the `austraits` package
-
-**For Python or other users**, the [Zenodo download](https://zenodo.org/record/5112001#collapseTwo) includes a .zip file containing all the data in plain text (.csv files) and associated meta-data 
+`austraits` allow users to **access, explore and wrangle data** from [traits.build](https://github.com/traitecoevo/traits.build) relational databases. It is also an R interface to [AusTraits](https://austraits.org/), the Australian plant trait database. This package contains functions for joining data from various tables, filtering to specific records, combining multiple databases and visualising the distribution of the data. We expect this package will assist users in working with `traits.build` databases.
 
 ### Installation
 
-The package is not on CRAN yet and is still under active development. For the current stable release of `austraits`, which has full capabilities of the functions used in vignettes (e.g. plotting functions), use: 
+This package is not on CRAN yet and is still under active development. For the current stable release of `austraits`, which has full capabilities of the functions used in vignettes (e.g. plotting functions), use: 
 
 ```{r setup, results = 'hide', eval = FALSE}
 #install.packages("remotes")
@@ -49,37 +45,46 @@ remotes::install_github("traitecoevo/austraits", dependencies = TRUE, upgrade =
 library(austraits) 
 ```
 
-Otherwise, for a lightweight installation where dependencies for plotting and the vignettes will not be installed, use:
+For a lightweight installation where dependencies for plotting and producing the vignettes will not be installed, use:
 
 ```{r light, results = 'hide', eval = FALSE}
 remotes::install_github("traitecoevo/austraits", upgrade = "ask")
 ```
 
-#### Backwards compatibility with old AusTraits versions
+### Details for AusTraits users
 
-In September 2024 austraits functions were revamped to support all [traits.build](https://github.com/traitecoevo/traits.build) compiled databases, rather than being linked to [austraits.build](https://github.com/traitecoevo/austraits.build).
+#### Retrieve AusTraits data
 
-Versions of austraits.build (the AusTraits plant trait database) < 5.0 are no longer supported by the current functions. If you are working with an older version of AusTraits, please install an older version of austraits:
+- **For R users**, the AusTraits database can be accessed through the `austraits` package using `load_austraits()`
 
-For austraits.build versions 4.2 and older: 
-```{r setup, results = 'hide', eval = FALSE}
+- **For Python or other users**, the [Zenodo download](https://zenodo.org/record/5112001#collapseTwo) includes a `.zip` file containing all the data in plain text (`.csv` files) and associated meta-data 
+
+#### Backwards compatibility with past AusTraits versions
+
+From September 2024, `austraits` functions were revamped to support all [traits.build](https://github.com/traitecoevo/traits.build) compiled databases, rather than being linked to [austraits.build](https://github.com/traitecoevo/austraits.build).
+
+Versions of `austraits.build` (the AusTraits plant trait database) **< 5.0 are no longer supported** by the latest version of the package. If you are working with an older version of AusTraits, please install an older version of austraits:
+
+For `austraits.build` versions 4.2 and older: 
+
+```{r backwards, results = 'hide', eval = FALSE}
 #install.packages("remotes")
-remotes::install_github("traitecoevo/austraits@53b637c", dependencies = TRUE, upgrade = "ask")
+remotes::install_github("traitecoevo/austraits@v2.2.2", dependencies = TRUE, upgrade = "ask")
 
 library(austraits)
 ```
 
 Note, if you are unsure what version of AusTraits you are working with, run:
-```{r setup, results = 'hide', eval = FALSE}
+
+```{r version, results = 'hide', eval = FALSE}
 austraits$build_info$version
 ```
 
+### Getting started  `r emo::ji("eyes")`
 
-### Take a good look at our vignettes! `r emo::ji("eyes")`
-
-In our website, we have also included information about the [structure of the database](https://traitecoevo.github.io/austraits/articles/structure.html), [definitions of the traits](https://traitecoevo.github.io/austraits/articles/dictionary.html) and some [tutorials](https://traitecoevo.github.io/austraits/articles/austraits.html) that uses our functions as well as some `tidyverse` functions to create some commonly used data output formats. We highly recommend starting here before jumping into the database! 
+We highly recommend taking a look at our [Getting Started tutorial](https://traitecoevo.github.io/austraits/) on our website before jumping into the `austraits` R package!
 
-If you prefer to view the vignettes in R, we recommend installing the package with `build_vignettes = TRUE`. 
+If you prefer to view this vignette in R, we recommend installing the package with `build_vignettes = TRUE`. 
 
 ```{r, eval = FALSE}
 remotes::install_github("traitecoevo/austraits", 
@@ -89,6 +94,12 @@ remotes::install_github("traitecoevo/austraits",
 vignette("austraits")
 ```
 
+### Learn more about AusTraits
+
+AusTraits is a relational database, you can learn more about it's structure from the [traits.build book](https://traitecoevo.github.io/traits.build-book/AusTraits_tutorial.html).  
+
+You can also learn about the definitions of each plant trait with the [AusTraits Plant Dictionary!](https://w3id.org/APD)
+
 ### Show us some support `r emo::ji("green heart")`
 
 Please consider citing `austraits`, we would super appreciate it! 
@@ -99,7 +110,7 @@ citation("austraits")
 
 ### Behind the scenes `r emo::ji("spanner")`
 
-Check out [austraits.build](http://traitecoevo.github.io/austraits.build/), if you are interested in how AusTraits the database is managed and created
+Check out [austraits.build](https://github.com/traitecoevo/austraits.build?tab=readme-ov-file), if you are interested in how AusTraits the database is managed and created
 
 ### Find a bug? `r emo::ji("bug")`
 

diff --git a/README.md b/README.md
@@ -1,31 +1,30 @@
+
 <!-- README.md is generated from README.Rmd. Please edit that file -->
 
-# austraits <img src="man/figures/austraits_hex.png" align="right" width="120"/>
+# austraits <img src="man/figures/austraits_hex.png" align="right" alt="" width="120" />
 
 <!-- badges: start -->
 
 [![R-CMD-check](https://github.com/traitecoevo/austraits/actions/workflows/R-CMD-check.yml/badge.svg)](https://github.com/traitecoevo/austraits/actions/workflows/R-CMD-check.yml)
 [![codecov](https://codecov.io/gh/traitecoevo/austraits/branch/master/graph/badge.svg?token=JT1M0AMZ44)](https://codecov.io/gh/traitecoevo/austraits)
 [![](https://img.shields.io/badge/doi-10.1038/s41597--021--01006--6-blue.svg)](https://doi.org/10.1038/s41597-021-01006-6)
 [![](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)
-
+[![Codecov test
+coverage](https://codecov.io/gh/traitecoevo/austraits/branch/master/graph/badge.svg)](https://app.codecov.io/gh/traitecoevo/austraits?branch=master)
 <!-- badges: end -->
 
-`austraits` allow users to access, explore and wrangle data from the
-AusTraits database in `R`. This package includes several functions such
-as filtering and pivoting the dataset that we expect will come in handy.
-
-**For R users**, access and manipulation of the data is assisted with
-the `austraits` package
-
-**For Python or other users**, the [Zenodo
-download](https://zenodo.org/record/5112001#collapseTwo) includes a .zip
-file containing all the data in plain text (.csv files) and associated
-meta-data
+`austraits` allow users to **access, explore and wrangle data** from
+[traits.build](https://github.com/traitecoevo/traits.build) relational
+databases. It is also an R interface to
+[AusTraits](https://austraits.org/), the Australian plant trait
+database. This package contains functions for joining data from various
+tables, filtering to specific records, combining multiple databases and
+visualising the distribution of the data. We expect this package will
+assist users in working with `traits.build` databases.
 
 ### Installation
 
-The package is not on CRAN yet and is still under active development.
+This package is not on CRAN yet and is still under active development.
 For the current stable release of `austraits`, which has full
 capabilities of the functions used in vignettes (e.g. plotting
 functions), use:
@@ -37,27 +36,60 @@ remotes::install_github("traitecoevo/austraits", dependencies = TRUE, upgrade =
 library(austraits) 
 ```
 
-Otherwise, for a lightweight installation where dependencies for
-plotting and the vignettes will not be installed, use:
+For a lightweight installation where dependencies for plotting and
+producing the vignettes will not be installed, use:
 
 ``` r
 remotes::install_github("traitecoevo/austraits", upgrade = "ask")
 ```
 
-### Take a good look at our vignettes! 👀
+### Details for AusTraits users
+
+#### Retrieve AusTraits data
+
+- **For R users**, the AusTraits database can be accessed through the
+  `austraits` package using `load_austraits()`
+
+- **For Python or other users**, the [Zenodo
+  download](https://zenodo.org/record/5112001#collapseTwo) includes a
+  `.zip` file containing all the data in plain text (`.csv` files) and
+  associated meta-data
 
-In our website, we have also included information about the [structure
-of the
-database](https://traitecoevo.github.io/austraits/articles/structure.html),
-[definitions of the
-traits](https://traitecoevo.github.io/austraits/articles/dictionary.html)
-and some
-[tutorials](https://traitecoevo.github.io/austraits/articles/austraits.html)
-that uses our functions as well as some `tidyverse` functions to create
-some commonly used data output formats. We highly recommend starting
-here before jumping into the database!
+#### Backwards compatibility with past AusTraits versions
+
+From September 2024, `austraits` functions were revamped to support all
+[traits.build](https://github.com/traitecoevo/traits.build) compiled
+databases, rather than being linked to
+[austraits.build](https://github.com/traitecoevo/austraits.build).
+
+Versions of `austraits.build` (the AusTraits plant trait database) **\<
+5.0 are no longer supported** by the latest version of the package. If
+you are working with an older version of AusTraits, please install an
+older version of austraits:
+
+For `austraits.build` versions 4.2 and older:
+
+``` r
+#install.packages("remotes")
+remotes::install_github("traitecoevo/[email protected]", dependencies = TRUE, upgrade = "ask")
 
-If you prefer to view the vignettes in R, we recommend installing the
+library(austraits)
+```
+
+Note, if you are unsure what version of AusTraits you are working with,
+run:
+
+``` r
+austraits$build_info$version
+```
+
+### Getting started 👀
+
+We highly recommend taking a look at our [Getting Started
+tutorial](https://traitecoevo.github.io/austraits/) on our website
+before jumping into the `austraits` R package!
+
+If you prefer to view this vignette in R, we recommend installing the
 package with `build_vignettes = TRUE`.
 
 ``` r
@@ -68,13 +100,21 @@ remotes::install_github("traitecoevo/austraits",
 vignette("austraits")
 ```
 
+### Learn more about AusTraits
+
+AusTraits is a relational database, you can learn more about it’s
+structure from the [traits.build
+book](https://traitecoevo.github.io/traits.build-book/AusTraits_tutorial.html).
+
+You can also learn about the definitions of each plant trait with the
+[AusTraits Plant Dictionary!](https://w3id.org/APD)
+
 ### Show us some support 💚
 
 Please consider citing `austraits`, we would super appreciate it!
 
 ``` r
 citation("austraits")
-#> 
 #> To cite austraits in publications use:
 #> 
 #>   Falster, D., Gallagher, R., Wenk, E.H. et al. AusTraits, a curated
@@ -98,8 +138,9 @@ citation("austraits")
 ### Behind the scenes 🔧
 
 Check out
-[austraits.build](http://traitecoevo.github.io/austraits.build/), if you
-are interested in how AusTraits the database is managed and created
+[austraits.build](https://github.com/traitecoevo/austraits.build?tab=readme-ov-file),
+if you are interested in how AusTraits the database is managed and
+created
 
 ### Find a bug? 🐛