From ecb3da7b091c74d54bf3df8eb33c8fac4913c320 Mon Sep 17 00:00:00 2001 From: Elizabeth Wenk Date: Tue, 10 Sep 2024 11:03:11 +1000 Subject: [PATCH 1/3] update documentation for traits_pivot_wider & traits_pivot_longer --- R/trait_pivot_longer.R | 18 +++++++++++------- R/trait_pivot_wider.R | 25 +++++++++++++++++-------- 2 files changed, 28 insertions(+), 15 deletions(-) diff --git a/R/trait_pivot_longer.R b/R/trait_pivot_longer.R index 582dbca..a7c6dac 100644 --- a/R/trait_pivot_longer.R +++ b/R/trait_pivot_longer.R @@ -1,16 +1,20 @@ #' @title Pivot wide format AusTrait data into a long format #' #' @description trait_pivot_longer "gathers" wide format data into a "tidy" format -#' This function converts the data into long format where observations are on different rows and the type of observation is denoted by trait name. +#' This function converts the data into long format where measurements are on different rows and the type of observation is denoted by trait name. #' In other words, trait_pivot_longer reverts the actions of trait_pivot_wider -#' @param wide_data output from trait_pivot_wider. For <= v3.0.2 list object containing wide data generated,For > v3.0.2 a tibble of wide data +#' @param wide_data output from trait_pivot_wider. #' @return A tibble in long format #' @details -#' - If `bind_trait_values` or `summarise_trait_means` was applied prior to `trait_pivot_wider` for AusTraits -#' <= v3.0.2, `trait_pivot_longer` will return a tibble with fewer observations than the original traits table. -#' - 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" -#' +#' trait_pivot_wider has been developed to extract 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{ #' data <- austraits$traits %>% diff --git a/R/trait_pivot_wider.R b/R/trait_pivot_wider.R index b8a92a6..7d17ff4 100644 --- a/R/trait_pivot_wider.R +++ b/R/trait_pivot_wider.R @@ -1,14 +1,23 @@ -#' @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") #' -#' 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 traits The traits table from austraits list object -#' @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. 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. +#' +#' The function austraits::trait_pivot_longer reverts the actions of this function. +#' +#' @param 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 extract 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{ #' data <- austraits$traits %>% filter(dataset_id == "Falster_2003") From e503fc27cc1fb1d41fdc1511f4480b4c63c4f2d8 Mon Sep 17 00:00:00 2001 From: Elizabeth Wenk Date: Tue, 10 Sep 2024 11:31:45 +1000 Subject: [PATCH 2/3] Update documentation for join_ functions --- R/join_all.R | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/R/join_all.R b/R/join_all.R index 1ad1a4b..b631fe3 100644 --- a/R/join_all.R +++ b/R/join_all.R @@ -1,8 +1,11 @@ -#' @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 ... arguments passed to `vars` to subset the columns -#' @return austraits list object, but with additional variables appended to `traits` dataframe +#' @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 for functions joining a single dataframe, vector specifying which columns from a specific relational table to join to the traits table +#' @return traits.build list object, but with additional fields (columns) appended to `traits` dataframe #' @rdname join_all #' @examples From 6001b391eef7d29370e8293c28a6a479b7b9f4c6 Mon Sep 17 00:00:00 2001 From: Elizabeth Wenk Date: Tue, 10 Sep 2024 12:01:11 +1000 Subject: [PATCH 3/3] lots more updated documentation - hyperlinks appear in RStudio for each function documentation, but don't actually work --- R/extract_dataset.R | 19 +++++++++++++++---- R/extract_taxa.R | 24 +++++++++++++++++------- R/extract_trait.R | 22 ++++++++++++++++------ R/join_all.R | 14 ++++++++++++-- R/trait_pivot_longer.R | 21 ++++++++++++--------- R/trait_pivot_wider.R | 10 +++++----- man/bind_trait_values.Rd | 2 +- man/extract_dataset.Rd | 23 ++++++++++++++--------- man/extract_taxa.Rd | 26 +++++++++++++++++++------- man/extract_trait.Rd | 30 ++++++++++++++++++------------ man/join_all.Rd | 24 +++++++++++++++++++----- man/trait_pivot_longer.Rd | 26 +++++++++++++++----------- man/trait_pivot_wider.Rd | 23 +++++++++++++++-------- 13 files changed, 178 insertions(+), 86 deletions(-) diff --git a/R/extract_dataset.R b/R/extract_dataset.R index 5e283fa..f051924 100644 --- a/R/extract_dataset.R +++ b/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") diff --git a/R/extract_taxa.R b/R/extract_taxa.R index 69a4ef1..2a39447 100644 --- a/R/extract_taxa.R +++ b/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{ diff --git a/R/extract_trait.R b/R/extract_trait.R index acce21e..fffbe25 100644 --- a/R/extract_trait.R +++ b/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{ diff --git a/R/join_all.R b/R/join_all.R index b631fe3..9dac49f 100644 --- a/R/join_all.R +++ b/R/join_all.R @@ -1,11 +1,21 @@ #' @title Join metadata fields into the core traits table -#' @description Function to merge metadata stored in relational tables 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 for functions joining a single dataframe, vector specifying which columns from a specific relational table to join to the traits table +#' @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) #' @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 diff --git a/R/trait_pivot_longer.R b/R/trait_pivot_longer.R index a7c6dac..7d177c7 100644 --- a/R/trait_pivot_longer.R +++ b/R/trait_pivot_longer.R @@ -1,19 +1,22 @@ -#' @title Pivot wide format AusTrait data into a long format +#' @title Pivot wide format traits table into long format #' -#' @description trait_pivot_longer "gathers" wide format data into a "tidy" format -#' This function converts the data into long format where measurements are on different rows and the type of observation is denoted by trait name. -#' In other words, trait_pivot_longer reverts the actions of trait_pivot_wider +#' @description Function to "gather" wide format data into a "tidy" format. +#' +#' 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_wider has been developed to extract datasets from databases built using the traits.build workflow. +#' @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 +#' [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." +#' - 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{ diff --git a/R/trait_pivot_wider.R b/R/trait_pivot_wider.R index 7d17ff4..ba328f0 100644 --- a/R/trait_pivot_wider.R +++ b/R/trait_pivot_wider.R @@ -1,6 +1,6 @@ #' @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"). #' #' 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. 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. #' @@ -9,14 +9,14 @@ #' @param 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 extract datasets from databases built using the traits.build workflow. +#' `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 +#' [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." +#' - 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{ diff --git a/man/bind_trait_values.Rd b/man/bind_trait_values.Rd index 3dc5220..724ba97 100644 --- a/man/bind_trait_values.Rd +++ b/man/bind_trait_values.Rd @@ -19,7 +19,7 @@ This function concatenates multiple values into a single cell \examples{ \dontrun{ traits <- austraits$traits \%>\% -dplyr::filter(dataset_id == "Falster_2005_1") +dplyr::filter(dataset_id == "ABRS_1981") traits traits_bind <- bind_trait_values(traits) } diff --git a/man/extract_dataset.Rd b/man/extract_dataset.Rd index 4bd040a..d4f8cc3 100644 --- a/man/extract_dataset.Rd +++ b/man/extract_dataset.Rd @@ -7,22 +7,27 @@ extract_dataset(austraits, dataset_id) } \arguments{ -\item{austraits}{\itemize{ -\item A large list of tibbles built from austraits -}} +\item{austraits}{a large list of tibbles built by \code{traits.build} workflow} -\item{dataset_id}{\itemize{ -\item character string that matches a dataset_id in the data -}} +\item{dataset_id}{character string that matches a \code{dataset_id} in the database} } \value{ -A large list of tibbles containing all austraits information for one particular dataset +List of tibbles containing all traits.build data and metadata for the specified dataset(s). } \description{ -Function to subset of all data associated with a particular dataset from austraits +Function to subset all data associated with a particular dataset from a traits.build relational database. } \details{ -\code{extract_dataset()} no longer supports AusTraits version <= 5.0.0, see \href{https://github.com/traitecoevo/austraits}{this page} for details. \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} +\code{extract_dataset} has been developed to extract data for specific datasets from databases built using the traits.build workflow. +Learn more at: +\link{https://github.com/traitecoevo/traits.build} & +\link{https://github.com/traitecoevo/traits.build-book} + +Note to AusTraits users: +\itemize{ +\item This function works with AusTraits version >= 5.0.0 (from Nov 2023 release) +\item For AusTraits versions <= 4.2.0 (up to Sept 2023 release) see \link{https://github.com/traitecoevo/austraits} for how to install old versions of the package or download a newer version of the database." +} } \examples{ \dontrun{ diff --git a/man/extract_taxa.Rd b/man/extract_taxa.Rd index 9959e3d..90a6a6c 100644 --- a/man/extract_taxa.Rd +++ b/man/extract_taxa.Rd @@ -2,24 +2,36 @@ % Please edit documentation in R/extract_taxa.R \name{extract_taxa} \alias{extract_taxa} -\title{Extract data for one specific taxa} +\title{Extract all data for specific taxa} \usage{ extract_taxa(austraits, family = NULL, genus = NULL, taxon_name = NULL) } \arguments{ -\item{austraits}{austraits list object} +\item{austraits}{a large list of tibbles built by \code{traits.build} workflow} -\item{family}{character string of family} +\item{family}{character string of family or families} -\item{genus}{character string of genus} +\item{genus}{character string of genus or genera} -\item{taxon_name}{character string of taxon name} +\item{taxon_name}{character string of taxon name(s)} } \value{ -A large list of tibbles containing all austraits information for specificied taxa +List of tibbles containing all traits.build data and metadata for the specified taxa. } \description{ -Function to subset of all data associated with a particular dataset from austraits +Function to subset of all data associated with a particular taxon from a traits.build relational database. +} +\details{ +\code{extract_taxa} has been developed to extract data for specific taxa from databases built using the traits.build workflow. +Learn more at: +\link{https://github.com/traitecoevo/traits.build} & +\link{https://github.com/traitecoevo/traits.build-book} + +Note to AusTraits users: +\itemize{ +\item This function works with AusTraits version >= 5.0.0 (from Nov 2023 release) +\item For AusTraits versions <= 4.2.0 (up to Sept 2023 release) see \link{https://github.com/traitecoevo/austraits} for how to install old versions of the package or download a newer version of the database." +} } \examples{ \dontrun{ diff --git a/man/extract_trait.Rd b/man/extract_trait.Rd index 284135f..c96f46a 100644 --- a/man/extract_trait.Rd +++ b/man/extract_trait.Rd @@ -2,28 +2,34 @@ % Please edit documentation in R/extract_trait.R \name{extract_trait} \alias{extract_trait} -\title{Extract data for specific traits} +\title{Extract all data for specific traits} \usage{ extract_trait(austraits, trait_names, taxon_names) } \arguments{ -\item{austraits}{\itemize{ -\item A large list of tibbles built from austraits -}} +\item{austraits}{a large list of tibbles built by \code{traits.build}} -\item{trait_names}{\itemize{ -\item character string of trait that will be extracted -}} +\item{trait_names}{character string of trait(s) for which data will be extracted} -\item{taxon_names}{\itemize{ -\item optional argument -}} +\item{taxon_names}{optional argument, specifying taxa for which data will be extracted} } \value{ -A large list of tibbles containing all austraits information for one particular dataset +List of tibbles containing all traits.build data and metadata for the specified trait(s). } \description{ -Function to subset of all data associated with a particular dataset from austraits +Function to subset all data associated with a particular trait from a traits.build relational database. +} +\details{ +\code{extract_trait} has been developed to extract data for specific traits from databases built using the traits.build workflow. +Learn more at: +\link{https://github.com/traitecoevo/traits.build} & +\link{https://github.com/traitecoevo/traits.build-book} + +Note to AusTraits users: +\itemize{ +\item This function works with AusTraits version >= 5.0.0 (from Nov 2023 release) +\item For AusTraits versions <= 4.2.0 (up to Sept 2023 release) see \link{https://github.com/traitecoevo/austraits} for how to install old versions of the package or download a newer version of the database." +} } \examples{ \dontrun{ diff --git a/man/join_all.Rd b/man/join_all.Rd index ff4dd05..9c4b64d 100644 --- a/man/join_all.Rd +++ b/man/join_all.Rd @@ -6,7 +6,7 @@ \alias{join_methods} \alias{join_locations} \alias{join_contexts} -\title{Join study details into main \code{traits} dataset} +\title{Join metadata fields into the core traits table} \usage{ join_all(austraits) @@ -19,15 +19,29 @@ join_locations(austraits, ...) join_contexts(austraits, ...) } \arguments{ -\item{austraits}{dataframe generated by austraits build} +\item{austraits}{traits.build generated database} -\item{...}{arguments passed to \code{vars} to subset the columns} +\item{vars}{vector specifying which columns from a specific relational table to join to the traits table (works only for \code{join_} functions joining a single dataframe)} } \value{ -austraits list object, but with additional variables appended to \code{traits} dataframe +traits.build list object, but with additional fields (columns) appended to \code{traits} dataframe } \description{ -Function to append all study information (method, location, taxonomic, context) variables into trait database +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. +} +\details{ +the \code{join_} functions have been developed to join relational tables for databases built using the traits.build workflow. +Learn more at: +\link{https://github.com/traitecoevo/traits.build} & +\link{https://github.com/traitecoevo/traits.build-book} + +Note to AusTraits users: +\itemize{ +\item This function works with AusTraits version >= 5.0.0 (from Nov 2023 release) +\item For AusTraits versions <= 4.2.0 (up to Sept 2023 release) see \link{https://github.com/traitecoevo/austraits} for how to install old versions of the package or download a newer version of the database." +} } \examples{ \dontrun{ diff --git a/man/trait_pivot_longer.Rd b/man/trait_pivot_longer.Rd index 1d68a00..d761035 100644 --- a/man/trait_pivot_longer.Rd +++ b/man/trait_pivot_longer.Rd @@ -2,29 +2,33 @@ % Please edit documentation in R/trait_pivot_longer.R \name{trait_pivot_longer} \alias{trait_pivot_longer} -\title{Pivot wide format AusTrait data into a long format} +\title{Pivot wide format traits table into long format} \usage{ trait_pivot_longer(wide_data) } \arguments{ -\item{wide_data}{output from trait_pivot_wider. For <= v3.0.2 list object containing wide data generated,For > v3.0.2 a tibble of wide data} +\item{wide_data}{output from trait_pivot_wider.} } \value{ A tibble in long format } \description{ -trait_pivot_longer "gathers" wide format data into a "tidy" format -This function converts the data into long format where observations are on different rows and the type of observation is denoted by trait name. -In other words, trait_pivot_longer reverts the actions of trait_pivot_wider +Function to "gather" wide format data into a "tidy" format. + +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. } \details{ +\code{trait_pivot_longer} has been developed to pivot the traits table for a database build using the traits.build workflow. +Learn more at: +\link{https://github.com/traitecoevo/traits.build} & +\link{https://github.com/traitecoevo/traits.build-book} + +Note to AusTraits users: \itemize{ -\item If \code{bind_trait_values} or \code{summarise_trait_means} was applied prior to \code{trait_pivot_wider} for AusTraits -<= v3.0.2, \code{trait_pivot_longer} will return a tibble with fewer observations than the original traits table. -\item For AusTraits version >3.0.2, \code{trait_pivot_longer} will return a tibble with fewer columns than that original traits table -\itemize{ -\item The excluded columns include: "unit", "replicates", "measurement_remarks", "basis_of_record", "basis_of_value" -} +\item This function works with AusTraits version >= 5.0.0 (from Nov 2023 release) +\item For AusTraits versions <= 4.2.0 (up to Sept 2023 release) see \link{https://github.com/traitecoevo/austraits} for how to install old versions of the package or download a newer version of the database." } } \examples{ diff --git a/man/trait_pivot_wider.Rd b/man/trait_pivot_wider.Rd index 2cdb3ab..44dfc90 100644 --- a/man/trait_pivot_wider.Rd +++ b/man/trait_pivot_wider.Rd @@ -2,26 +2,33 @@ % Please edit documentation in R/trait_pivot_wider.R \name{trait_pivot_wider} \alias{trait_pivot_wider} -\title{Pivot long format austrait data into a wide format} +\title{Pivot long format traits table into wide format} \usage{ trait_pivot_wider(traits) } \arguments{ -\item{traits}{The traits table from austraits list object} +\item{traits}{The traits table from traits.build database list object} } \value{ -list of five tibbles in wide format +traits.build traits table in wide format } \description{ -\code{trait_pivot_wider} "widens" long format data ("tidy data") +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. +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. \if{html}{\out{}}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.\if{html}{\out{}} + +The function austraits::trait_pivot_longer reverts the actions of this function. } \details{ +`trait_pivot_wider`` has been developed to pivot the traits table for a database build using the traits.build workflow. +Learn more at: +\link{https://github.com/traitecoevo/traits.build} & +\link{https://github.com/traitecoevo/traits.build-book} + +Note to AusTraits users: \itemize{ -\item For AusTraits <=v3.0.2, some studies have multiple rows of data for each observation_id, so \code{trait_pivot_wider} will return four lists (value, unit, value_type, date and replicates) with the identifying columns and trait data arranged in columns. -\item For AusTraits >3.0.2, \code{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. +\item This function works with AusTraits version >= 5.0.0 (from Nov 2023 release) +\item For AusTraits versions <= 4.2.0 (up to Sept 2023 release) see \link{https://github.com/traitecoevo/austraits} for how to install old versions of the package or download a newer version of the database." } } \examples{