From 0f3ba328c588ee72d571cfbcc255db378e15b5b1 Mon Sep 17 00:00:00 2001
From: Michael McLaren <m.mclaren42@gmail.com>
Date: Sat, 12 Sep 2020 15:22:50 -0400
Subject: [PATCH] Improve documentation

---
 NEWS.md                   | 14 ++++++++------
 R/merge_samples.R         | 21 ++++++++++++---------
 man/merge_samples2.Rd     | 17 ++++++++++-------
 man/sample_data_stable.Rd |  2 +-
 4 files changed, 31 insertions(+), 23 deletions(-)

diff --git a/NEWS.md b/NEWS.md
index da44748..f9067f7 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,10 +1,10 @@
-# speedyseq (development version)
+# speedyseq 0.3.3
 
-* Add `merge_samples2()` as an alternative to `phyloseq::merge_samples()` that
-  better handles categorical sample variables. Using the `funs` argument, users
-  can specify the function that should be used to merge sample variables within
-  groups. The default is use the new `unique_or_na()` function, which collapses
-  the values to a single unique value if it exists and otherwise returns NA.
+* Add `merge_samples2()` and the helper `unique_or_na()` as an alternative to
+  `phyloseq::merge_samples()` that better handles categorical sample variables.
+  The `funs` argument specifies which summary is used to merge each sample
+  variable within groups. The default is `unique_or_na()`, which collapses the
+  values to a single unique value if it exists and otherwise returns NA.
 
 ```r
 data(enterotype)
@@ -22,6 +22,8 @@ sample_data(ps0) %>% head
 
 * Add `tibble::glimpse()` methods for `sample_data` and `phyloseq` objects
 
+* Fixed bug in `merge_taxa_vec()` when only one tax rank
+
 # speedyseq 0.3.2
 
 * Extend the constructor functions `otu_table()`, `sample_data()`, and
diff --git a/R/merge_samples.R b/R/merge_samples.R
index 42c3578..30568a8 100644
--- a/R/merge_samples.R
+++ b/R/merge_samples.R
@@ -1,10 +1,13 @@
-#' Merge samples by sample variables 
-#' 
-#' Alternative to `phyloseq::merge_samples()` that better handles categorical
-#' sample variables. Using the `funs` argument, users can specify the function
-#' that should be used to merge sample variables within groups. The default is
-#' use the new `unique_or_na()` function, which collapses the values to a
-#' single unique value if it exists and otherwise returns NA.
+#' Merge samples by a sample variable or factor
+#'
+#' This function provides an alternative to `phyloseq::merge_samples()` that
+#' better handles sample variables of different types, especially categorical
+#' sample variables. It combines the samples in `x` defined by the sample
+#' variable or factor `group` by summing the abundances in `otu_table(x)` and
+#' combines sample variables by the summary functions in `funs`. The default
+#' summary function, `unique_or_na()`, collapses the values within a group to a
+#' single unique value if it exists and otherwise returns NA. The new (merged)
+#' samples are named by the values in `group`.
 #' 
 #' @param x A `sample_data` object
 #' @param group A sample variable or a vector of length `nsamples(x)` defining
@@ -18,7 +21,7 @@
 #' @examples
 #' data(enterotype)
 #' 
-#'  # Merge samples with the same project and clinical status
+#' # Merge samples with the same project and clinical status
 #' ps <- enterotype 
 #' sample_data(ps) <- sample_data(ps) %>%
 #'   transform(Project.ClinicalStatus = Project:ClinicalStatus)
@@ -208,7 +211,7 @@ merge_groups <- function(x, group, f = unique_or_na) {
 #' x <- data.frame(var1 = letters[1:3], var2 = 7:9)
 #' rownames(x)
 #' sample_data(x)
-#' sample_data_stable(x)
+#' speedyseq:::sample_data_stable(x)
 sample_data_stable <- function(object) {
   # Modified from phyloseq's sample_data data.frame method; see
   # https://github.com/joey711/phyloseq/blob/master/R/sampleData-class.R
diff --git a/man/merge_samples2.Rd b/man/merge_samples2.Rd
index f8de6e9..af23ff1 100644
--- a/man/merge_samples2.Rd
+++ b/man/merge_samples2.Rd
@@ -5,7 +5,7 @@
 \alias{merge_samples2,phyloseq-method}
 \alias{merge_samples2,otu_table-method}
 \alias{merge_samples2,sample_data-method}
-\title{Merge samples by sample variables}
+\title{Merge samples by a sample variable or factor}
 \usage{
 merge_samples2(x, group, funs = list(), reorder = FALSE)
 
@@ -27,16 +27,19 @@ the sample grouping. A vector must be supplied if x is an otu_table}
 samples by name}
 }
 \description{
-Alternative to \code{phyloseq::merge_samples()} that better handles categorical
-sample variables. Using the \code{funs} argument, users can specify the function
-that should be used to merge sample variables within groups. The default is
-use the new \code{unique_or_na()} function, which collapses the values to a
-single unique value if it exists and otherwise returns NA.
+This function provides an alternative to \code{phyloseq::merge_samples()} that
+better handles sample variables of different types, especially categorical
+sample variables. It combines the samples in \code{x} defined by the sample
+variable or factor \code{group} by summing the abundances in \code{otu_table(x)} and
+combines sample variables by the summary functions in \code{funs}. The default
+summary function, \code{unique_or_na()}, collapses the values within a group to a
+single unique value if it exists and otherwise returns NA. The new (merged)
+samples are named by the values in \code{group}.
 }
 \examples{
 data(enterotype)
 
- # Merge samples with the same project and clinical status
+# Merge samples with the same project and clinical status
 ps <- enterotype 
 sample_data(ps) <- sample_data(ps) \%>\%
   transform(Project.ClinicalStatus = Project:ClinicalStatus)
diff --git a/man/sample_data_stable.Rd b/man/sample_data_stable.Rd
index d986687..1fa2f38 100644
--- a/man/sample_data_stable.Rd
+++ b/man/sample_data_stable.Rd
@@ -18,6 +18,6 @@ names as is.
 x <- data.frame(var1 = letters[1:3], var2 = 7:9)
 rownames(x)
 sample_data(x)
-sample_data_stable(x)
+speedyseq:::sample_data_stable(x)
 }
 \keyword{internal}