Update documentation

R/extract_dataset.R

@@ -1,10 +1,21 @@
 #' @title Extract all data for a particular dataset
 #'
-#' @description Function to subset of all data associated with a particular dataset from austraits
+#' @description Function to subset all data associated with a particular dataset from a traits.build relational database.
+#' 
 #' @usage extract_dataset(austraits, dataset_id)
-#' @param austraits - A large list of tibbles built from austraits
-#' @param dataset_id - character string that matches a dataset_id in the data
-#' @return A large list of tibbles containing all austraits information for one particular dataset
+#' @param austraits a large list of tibbles built by `traits.build` workflow
+#' @param dataset_id character string that matches a `dataset_id` in the database
+#' @return List of tibbles containing all traits.build data and metadata for the specified dataset(s).
+#' @details
+#' `extract_dataset` has been developed to extract data for specific datasets from databases built using the traits.build workflow. 
+#' Learn more at:
+#'   [https://github.com/traitecoevo/traits.build] &
+#'   [https://github.com/traitecoevo/traits.build-book]
+#'
+#' Note to AusTraits users:
+#' -  This function works with AusTraits version >= 5.0.0 (from Nov 2023 release)
+#' -  For AusTraits versions <= 4.2.0 (up to Sept 2023 release) see [https://github.com/traitecoevo/austraits] for how to install old versions of the package or download a newer version of the database."
+#'
 #' @examples
 #' \dontrun{
 #' extract_dataset(austraits, "Falster_2003")

R/extract_taxa.R

@@ -1,11 +1,21 @@
-#' @title Extract data for one specific taxa
+#' @title Extract all data for specific taxa
 #'
-#' @description Function to subset of all data associated with a particular dataset from austraits
-#' @param austraits austraits list object
-#' @param family character string of family
-#' @param genus character string of genus
-#' @param taxon_name character string of taxon name
-#' @return A large list of tibbles containing all austraits information for specificied taxa
+#' @description Function to subset of all data associated with a particular taxon from a traits.build relational database.
+#' 
+#' @param austraits a large list of tibbles built by `traits.build` workflow
+#' @param family character string of family or families
+#' @param genus character string of genus or genera
+#' @param taxon_name character string of taxon name(s)
+#' @return List of tibbles containing all traits.build data and metadata for the specified taxa.
+#' @details
+#' `extract_taxa` has been developed to extract data for specific taxa from databases built using the traits.build workflow. 
+#' Learn more at:
+#'   [https://github.com/traitecoevo/traits.build] &
+#'   [https://github.com/traitecoevo/traits.build-book]
+#'
+#' Note to AusTraits users:
+#' -  This function works with AusTraits version >= 5.0.0 (from Nov 2023 release)
+#' -  For AusTraits versions <= 4.2.0 (up to Sept 2023 release) see [https://github.com/traitecoevo/austraits] for how to install old versions of the package or download a newer version of the database."
 #'
 #' @examples 
 #' \dontrun{

R/extract_trait.R

@@ -1,11 +1,21 @@
-#' @title Extract data for specific traits
+#' @title Extract all data for specific traits
 #'
-#' @description Function to subset of all data associated with a particular dataset from austraits
+#' @description Function to subset all data associated with a particular trait from a traits.build relational database.
+#' 
 #' @usage extract_trait(austraits, trait_names, taxon_names)
-#' @param austraits - A large list of tibbles built from austraits
-#' @param trait_names - character string of trait that will be extracted
-#' @param taxon_names - optional argument
-#' @return A large list of tibbles containing all austraits information for one particular dataset
+#' @param austraits a large list of tibbles built by `traits.build`
+#' @param trait_names character string of trait(s) for which data will be extracted
+#' @param taxon_names optional argument, specifying taxa for which data will be extracted 
+#' @return List of tibbles containing all traits.build data and metadata for the specified trait(s).
+#' @details
+#' `extract_trait` has been developed to extract data for specific traits from databases built using the traits.build workflow. 
+#' Learn more at:
+#'   [https://github.com/traitecoevo/traits.build] &
+#'   [https://github.com/traitecoevo/traits.build-book]
+#'
+#' Note to AusTraits users:
+#' -  This function works with AusTraits version >= 5.0.0 (from Nov 2023 release)
+#' -  For AusTraits versions <= 4.2.0 (up to Sept 2023 release) see [https://github.com/traitecoevo/austraits] for how to install old versions of the package or download a newer version of the database."
 #'
 #' @examples 
 #' \dontrun{

R/join_all.R

@@ -1,9 +1,22 @@
-#' @title Join study details into main `traits` dataset
-#' @description Function to append all study information (method, location, taxonomic, context) variables into trait database
-#' @param austraits dataframe generated by austraits build
-#' @param vars column names from relevant table to select what data is joined
+#' @title Join metadata fields into the core traits table
+#' @description Function to merge metadata stored in relational tables into the core traits table.
+#'
+#' A traits.build database includes relational tables that contain measurement (and observation) metadata pertaining to locations, contexts, methods, and taxonomy. This function merges all (or some) of the metadata from one (or all) of these tables into the traits table.
+#' 
+#' @param austraits traits.build generated database
+#' @param vars vector specifying which columns from a specific relational table to join to the traits table (works only for `join_` functions joining a single dataframe)
 #' @param collapse_context for `join_contexts` only. Logical, whether contexts for a given observation will be concatenated into one cell
-#' @return austraits list object, but with additional variables appended to `traits` dataframe
+#' @return traits.build list object, but with additional fields (columns) appended to `traits` dataframe
+#' @details
+#' the `join_` functions have been developed to join relational tables for databases built using the traits.build workflow. 
+#' Learn more at:
+#'   [https://github.com/traitecoevo/traits.build] &
+#'   [https://github.com/traitecoevo/traits.build-book]
+#'
+#' Note to AusTraits users:
+#' -  This function works with AusTraits version >= 5.0.0 (from Nov 2023 release)
+#' -  For AusTraits versions <= 4.2.0 (up to Sept 2023 release) see [https://github.com/traitecoevo/austraits] for how to install old versions of the package or download a newer version of the database."
+#'
 #' @rdname join_all
 
 #' @examples

R/trait_pivot_longer.R

@@ -1,4 +1,4 @@
-#' @title Pivot wide format AusTrait data into a long format
+#' @title Pivot wide format traits table into long format
 #'
 #' @description `r lifecycle::badge('deprecated')`
 #' trait_pivot_longer "gathers" wide format data into a "tidy" format
@@ -12,6 +12,22 @@
 #' - For AusTraits version >3.0.2,  `trait_pivot_longer` will return a tibble with fewer columns than that original traits table
 #'    - The excluded columns include: "unit", "replicates", "measurement_remarks", "basis_of_record", "basis_of_value"
 #' 
+#' This function reverts the actions of the function austraits::trait_pivot_wider.
+#' 
+#' It begins with a derivation of a traits.build traits table, where multiple measurements that comprise a single observation are displayed on a single row,with a column for each trait. It then converts the table into long format where measurements of multiple traits that comprise a single observation are on different rows and a column specifying the trait names is added.
+#' 
+#' @param wide_data output from trait_pivot_wider.
+#' @return A tibble in long format
+#' @details
+#' `trait_pivot_longer` has been developed to pivot the traits table for a database build using the traits.build workflow.
+#' Learn more at:
+#'   [https://github.com/traitecoevo/traits.build] &
+#'   [https://github.com/traitecoevo/traits.build-book]
+#'
+#' Note to AusTraits users:
+#' -  This function works with AusTraits version >= 5.0.0 (from Nov 2023 release)
+#' -  For AusTraits versions <= 4.2.0 (up to Sept 2023 release) see [https://github.com/traitecoevo/austraits] for how to install old versions of the package or download a newer version of the database."
+#'
 #' @examples 
 #' \dontrun{
 #' data <- austraits$traits %>% 

R/trait_pivot_wider.R

@@ -1,17 +1,28 @@
-#' @title Pivot long format austrait data into a wide format
+#' @title Pivot long format traits table into wide format
 #'
-#' @description `trait_pivot_wider` "widens" long format data ("tidy data")
+#' @description Function to "widen" long format data ("tidy data").
 #' 
-#' AusTraits data is organised in a long format where observations are on different rows and the type of observation is denoted by various identifying columns (e.g trait_name, dataset_id, observation_id etc.)
-#' This function converts the data into wide format so that each trait in it's own column. 
-#' @param aus_traits austraits object OR traits table. Note location details must be joined. See join_all and examples
-#' @return list of five tibbles in wide format
-#' @details 
-#' - For AusTraits <=v3.0.2, some studies have multiple rows of data for each observation_id, so `trait_pivot_wider` will return four lists (value, unit, value_type, date and replicates) with the identifying columns and trait data arranged in columns.  
-#' - For AusTraits >3.0.2, `trait_pivot_wider` will return a single widen tibble, note that some meta-data columns (unit, replicates, measurement_remarks, basis_of_record, basis_of_value) will be excluded to produce a useful wide tibble.
+#' Data in a traits.build databases' traits table are organised in a long format where each trait measurement is on a different row and measurement metadata is recorded in other columns. Multiple traits may be measured as part of a single observation and this function pivots the data wider, such that each trait is its own column. <i>Note that if two trait measurements have the same observation_id but different value types (min, mean, mode, etc.) these will be on separate rows.</i>
+#' 
+#' The function austraits::trait_pivot_longer reverts the actions of this function.
+#' 
+#' @param aus_traits The traits table from traits.build database list object
+#' @return traits.build traits table in wide format
+#' @details
+#' `trait_pivot_wider`` has been developed to pivot the traits table for a database build using the traits.build workflow. 
+#' Learn more at:
+#'   [https://github.com/traitecoevo/traits.build] &
+#'   [https://github.com/traitecoevo/traits.build-book]
+#'
+#' Note to AusTraits users:
+#' -  This function works with AusTraits version >= 5.0.0 (from Nov 2023 release)
+#' -  For AusTraits versions <= 4.2.0 (up to Sept 2023 release) see [https://github.com/traitecoevo/austraits] for how to install old versions of the package or download a newer version of the database."
+#' 
+
 #' @examples 
 #' \dontrun{
-#' data <- austraits$traits %>% filter(dataset_id == "Falster_2003")
+#' 
+#' data <- austraits_5.0.0_lite$traits %>% filter(dataset_id == "Falster_2003")
 #' data #long format 
 #' traits_wide <- trait_pivot_wider(data) 
 #' traits_wide #wide format