From df1bd41981bcbeef06d53b09a8d59848623452fa Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Th=C3=A9otime=20Pralas?=
 <151254073+thpralas@users.noreply.github.com>
Date: Wed, 22 May 2024 22:02:46 +0300
Subject: [PATCH] Add explanation to rarefyAssay man page (#555)

Co-authored-by: Tuomas Borman <60338854+TuomasBorman@users.noreply.github.com>
---
 NEWS               |  2 ++
 R/rarefyAssay.R    | 13 ++++++-------
 man/rarefyAssay.Rd | 11 ++++++-----
 3 files changed, 14 insertions(+), 12 deletions(-)

diff --git a/NEWS b/NEWS
index 64b6a252f..1887d0ba5 100644
--- a/NEWS
+++ b/NEWS
@@ -131,3 +131,5 @@ Changes in version 1.13.x
 + Rename perSampleDominant* functions to getDominant and addPerSampleDominant* 
   functions to addDominant
 + Rename splitByRanks to agglomerateByRanks and add option as.list
++ Explain that rarefyAssay returns a new SummarizedExperiment object that 
+  includes the newly added subsampled assay.
diff --git a/R/rarefyAssay.R b/R/rarefyAssay.R
index 4a8b00160..934e35935 100644
--- a/R/rarefyAssay.R
+++ b/R/rarefyAssay.R
@@ -1,8 +1,9 @@
 #' Subsample Counts
 #' 
-#' \code{rarefyAssay} will randomly subsample counts in 
-#' \code{SummarizedExperiment} and return the a modified object in which each 
-#' sample has same number of total observations/counts/reads. 
+#' \code{rarefyAssay} randomly subsamples counts within a 
+#' \code{SummarizedExperiment} object and returns a new 
+#' \code{SummarizedExperiment} containing the original assay and the new 
+#' subsampled assay.
 #'
 #' @details
 #' Although the subsampling approach is highly debated in microbiome research, 
@@ -30,15 +31,13 @@
 #'   simulated this can equal to lowest number of total counts 
 #'   found in a sample or a user specified number. 
 #'   
-#'  
-#' 
 #' @param replace Logical Default is \code{TRUE}. The default is with 
 #'   replacement (\code{replace=TRUE}). 
 #'   See \code{\link[phyloseq:rarefy_even_depth]{phyloseq::rarefy_even_depth}}
 #'   for details on implications of this parameter.   
 #' 
 #' @param name A single character value specifying the name of transformed
-#'   abundance table.
+#'   abundance table that will be added to the new \code{SummarizedExperiment}.
 #' 
 #' @param verbose Logical Default is \code{TRUE}. When \code{TRUE} an additional 
 #'   message about the random number used is printed.
@@ -77,7 +76,7 @@
 #'                                   )
 #' tse.subsampled
 #' dim(tse)
-#' dim(tse.subsampled)
+#' dim(assay(tse.subsampled, "subsampled"))
 #' 
 NULL
 
diff --git a/man/rarefyAssay.Rd b/man/rarefyAssay.Rd
index ccf5e3af9..060152c3f 100644
--- a/man/rarefyAssay.Rd
+++ b/man/rarefyAssay.Rd
@@ -51,7 +51,7 @@ See \code{\link[phyloseq:rarefy_even_depth]{phyloseq::rarefy_even_depth}}
 for details on implications of this parameter.}
 
 \item{name}{A single character value specifying the name of transformed
-abundance table.}
+abundance table that will be added to the new \code{SummarizedExperiment}.}
 
 \item{verbose}{Logical Default is \code{TRUE}. When \code{TRUE} an additional
 message about the random number used is printed.}
@@ -62,9 +62,10 @@ message about the random number used is printed.}
 \code{rarefyAssay} return \code{x} with subsampled data.
 }
 \description{
-\code{rarefyAssay} will randomly subsample counts in
-\code{SummarizedExperiment} and return the a modified object in which each
-sample has same number of total observations/counts/reads.
+\code{rarefyAssay} randomly subsamples counts within a
+\code{SummarizedExperiment} object and returns a new
+\code{SummarizedExperiment} containing the original assay and the new
+subsampled assay.
 }
 \details{
 Although the subsampling approach is highly debated in microbiome research,
@@ -88,7 +89,7 @@ tse.subsampled <- rarefyAssay(tse,
                                   )
 tse.subsampled
 dim(tse)
-dim(tse.subsampled)
+dim(assay(tse.subsampled, "subsampled"))
 
 }
 \references{