added examples

Author: zachary-foster

R/taxmap--arrange.R

@@ -5,12 +5,17 @@
 #' \link[dplyr]{arrange} for more details.
 #' 
 #' @param .data \code{\link{taxmap}}
-#' @param ... One or more column names to sort on. Newly created columns can be referenced in the
-#'   same function call.
+#' @param ... One or more column names to sort on.
 #'   
 #' @return An object of type \code{\link{taxmap}}
 #'   
 #' @family dplyr-like functions
+#' 
+#' @examples
+#' # Sort by taxon name alphabetically
+#' arrange_taxa(unite_ex_data_3, name)
+#' # Reverse order of sort
+#' arrange_taxa(unite_ex_data_3, desc(name))
 #'   
 #' @export
 arrange_taxa <- function(.data, ...) {
@@ -29,13 +34,18 @@ arrange_taxa <- function(.data, ...) {
 #' \link[dplyr]{arrange} for more details.
 #' 
 #' @param .data \code{\link{taxmap}}
-#' @param ... One or more column names to sort on. Newly created columns can be referenced in the
-#'   same function call.
+#' @param ... One or more column names to sort on.
 #'   
 #' @return An object of type \code{\link{taxmap}}
 #'   
 #' @family dplyr-like functions
 #'   
+#' @examples
+#' # Sort observations by sequence name alphabetically
+#' arrange_obs(unite_ex_data_3, seq_name)
+#' # Reverse order of sort
+#' arrange_obs(unite_ex_data_3, desc(seq_name))
+#' 
 #' @export
 arrange_obs <- function(.data, ...) {
   my_obs_data <- obs_data(.data, col_subset = obs_data_cols_used(.data, ...))

R/taxmap--filter.R

@@ -31,7 +31,19 @@
 #' @return An object of type \code{\link{taxmap}}
 #'   
 #' @family dplyr-like functions
-#'   
+#' 
+#' @examples
+#' # Remove singleton taxa, but reassign singletons to supertaxa that pass filter
+#' filter_taxa(unite_ex_data_3, n_obs > 1)
+#' # Remove singleton taxa and associated seqeuence data
+#' filter_taxa(unite_ex_data_3, n_obs > 1, taxonless = FALSE, reassign_obs = FALSE)
+#' # Subset to a single taxon and its subtaxa
+#' filter_taxa(unite_ex_data_3, name == "Basidiomycota", subtaxa = TRUE)
+#' # Remove a taxon and its subtaxa
+#' filter_taxa(unite_ex_data_3, name == "Basidiomycota", subtaxa = TRUE, invert = TRUE)
+#' # Remove taxa, reassigning supertaxa and subtaxa 
+#' filter_taxa(unite_ex_data_3, unite_rank != "p")
+#' 
 #' @export
 filter_taxa <- function(.data, ..., subtaxa = FALSE, supertaxa = FALSE, taxonless = FALSE,
                         reassign_obs = TRUE, reassign_taxa = TRUE, invert = FALSE) {
@@ -134,7 +146,13 @@ filter_taxa <- function(.data, ..., subtaxa = FALSE, supertaxa = FALSE, taxonles
 #' @return An object of type \code{\link{taxmap}}
 #'   
 #' @family dplyr-like functions
-#'   
+#'
+#' @examples 
+#' # Filter by sequence name, but preserve all taxa
+#' filter_obs(unite_ex_data_3, grepl("Lachnum", seq_name))
+#' # Filter by sequence name and only keep taxa with sequences that pass the filter
+#' filter_obs(unite_ex_data_3, grepl("Lachnum", seq_name), unobserved = FALSE)
+#' 
 #' @export
 filter_obs <- function(.data, ..., unobserved = TRUE) {
   # non-standard argument evaluation ---------------------------------------------------------------

R/taxmap--mutate.R

@@ -11,7 +11,11 @@
 #' @return An object of type \code{\link{taxmap}}
 #'   
 #' @family dplyr-like functions
-#'   
+#' 
+#' @examples 
+#' # Add one or more taxon columns
+#' mutate_taxa(unite_ex_data_3, x = 1, y = x+2)
+#' 
 #' @export
 mutate_taxa <- function(.data, ...) {
   data_used <- taxon_data(.data, col_subset = taxon_data_cols_used(.data, ...))
@@ -39,6 +43,10 @@ mutate_taxa <- function(.data, ...) {
 #' @return An object of type \code{\link{taxmap}}
 #'   
 #' @family dplyr-like functions
+#' 
+#' @examples 
+#' # Add one or more observation columns
+#' mutate_obs(unite_ex_data_3, x = 1, y = x+2)
 #'   
 #' @export
 mutate_obs <- function(.data, ...) {
@@ -66,6 +74,10 @@ mutate_obs <- function(.data, ...) {
 #' @return An object of type \code{\link{taxmap}}
 #'   
 #' @family dplyr-like functions
+#' 
+#' @examples 
+#' # Replace all taxon columns with new columns
+#' transmute_taxa(unite_ex_data_3, x = 1, y = x+2)
 #'   
 #' @export
 transmute_taxa <- function(.data, ...) {
@@ -94,6 +106,10 @@ transmute_taxa <- function(.data, ...) {
 #' @return An object of type \code{\link{taxmap}}
 #'   
 #' @family dplyr-like functions
+#' 
+#' @examples 
+#' # Replace all observation columns with new columns
+#' transmute_obs(unite_ex_data_3, x = 1, y = x+2)
 #'   
 #' @export
 transmute_obs <- function(.data, ...) {

R/taxmap--sample.R

@@ -31,6 +31,16 @@
 #' @return An object of type \code{\link{taxmap}}
 #'   
 #' @family dplyr-like functions
+#' 
+#' @examples
+#' # Subsample without replacement, keeping all taxa
+#' sample_n_obs(unite_ex_data_3, 100)
+#' # Subsample without replacement and remove unsampled taxa
+#' sample_n_obs(unite_ex_data_3, 100, unobserved = FALSE)
+#' # Subsample with taxon weight 
+#' sample_n_obs(unite_ex_data_3, 100, unobserved = FALSE, taxon_weight = 1 / n_obs)
+#' # Sample with replacement
+#' sample_n_obs(unite_ex_data_3, 10000, replace = TRUE)
 #'   
 #' @export
 sample_n_obs <- function(.data, size, replace = FALSE, taxon_weight = NULL, obs_weight = NULL,
@@ -80,6 +90,17 @@ sample_n_obs <- function(.data, size, replace = FALSE, taxon_weight = NULL, obs_
 #'   
 #' @family dplyr-like functions
 #'   
+#'   
+#' @examples
+#' # Subsample without replacement, keeping all taxa
+#' sample_frac_obs(unite_ex_data_3, 0.1)
+#' # Subsample without replacement and remove unsampled taxa
+#' sample_frac_obs(unite_ex_data_3, 0.1, unobserved = FALSE)
+#' # Subsample with taxon weight 
+#' sample_frac_obs(unite_ex_data_3, 0.1, unobserved = FALSE, taxon_weight = 1 / n_obs)
+#' # Sample with replacement
+#' sample_frac_obs(unite_ex_data_3, 10, replace = TRUE)
+#' 
 #' @export
 sample_frac_obs <- function(.data, size = 1, replace = FALSE, taxon_weight = NULL, obs_weight = NULL,
                            use_supertaxa = TRUE, collapse_func = mean, ...) {
@@ -121,7 +142,14 @@ sample_frac_obs <- function(.data, size = 1, replace = FALSE, taxon_weight = NUL
 #' @return An object of type \code{\link{taxmap}}
 #'   
 #' @family dplyr-like functions
-#'   
+#' 
+#' @examples 
+#' # subsample taxa, preserving shared supertaxa
+#' sample_n_taxa(unite_ex_data_3, 100, supertaxa = TRUE)
+#' # subsample taxa using weights, preserving subtaxa
+#' sample_n_taxa(unite_ex_data_3, 10, subtaxa = TRUE,
+#'               taxon_weight = ifelse(unite_rank == "g" & n_subtaxa > 3, 1, 0))
+#'
 #' @export
 sample_n_taxa <- function(.data, size, taxon_weight = NULL, obs_weight = NULL,
                           use_subtaxa = TRUE, collapse_func = mean, ...) {
@@ -168,6 +196,13 @@ sample_n_taxa <- function(.data, size, taxon_weight = NULL, obs_weight = NULL,
 #'   
 #' @family dplyr-like functions
 #'   
+#' @examples 
+#' # subsample taxa, preserving shared supertaxa
+#' sample_frac_taxa(unite_ex_data_3, 0.1, supertaxa = TRUE)
+#' # subsample taxa using weights, preserving subtaxa
+#' sample_frac_taxa(unite_ex_data_3, 0.01, subtaxa = TRUE,
+#'                  taxon_weight = ifelse(unite_rank == "g" & n_subtaxa > 3, 1, 0))
+#'               
 #' @export
 sample_frac_taxa <- function(.data, size = 1, taxon_weight = NULL, obs_weight = NULL,
                               use_subtaxa = TRUE, collapse_func = mean, ...) {

R/taxmap--select.R

@@ -15,6 +15,10 @@
 #' @return An object of type \code{\link{taxmap}}
 #'   
 #' @family dplyr-like functions
+#' 
+#' @examples
+#' # subset taxon columns
+#' select_taxa(unite_ex_data_3, name)
 #'   
 #' @export
 select_taxa <- function(.data, ...) {
@@ -41,6 +45,10 @@ select_taxa <- function(.data, ...) {
 #' @return An object of type \code{\link{taxmap}}
 #'   
 #' @family dplyr-like functions
+#' 
+#' @examples
+#' # subset observation columns
+#' select_obs(unite_ex_data_3, other_id, seq_id)
 #'   
 #' @export
 select_obs <- function(.data, ...) {