From 046f0bdf2b2a2f86a7c8cb9420c728ae19662784 Mon Sep 17 00:00:00 2001
From: Louise Huuki <lahuuki@gmail.com>
Date: Fri, 19 Apr 2024 10:06:51 -0400
Subject: [PATCH] Improve doccumentation for fetch_deconvo_data #8

---
 R/fetch_deconvo_data.R    | 27 +++++++++++++++++++++++++--
 man/fetch_deconvo_data.Rd | 27 ++++++++++++++++++++++++---
 2 files changed, 49 insertions(+), 5 deletions(-)

diff --git a/R/fetch_deconvo_data.R b/R/fetch_deconvo_data.R
index 4da625e..fdb6336 100644
--- a/R/fetch_deconvo_data.R
+++ b/R/fetch_deconvo_data.R
@@ -1,6 +1,14 @@
 
 
 #' Download Human DLPFC Deconvolution Data
+#' 
+#'  This function downloads from ExperimentHub, if ExperimentHub is not 
+#'  available, this function will download the files from Dropbox using 
+#'  BiocFileCache::bfcrpath() unless the files are present already at destdir. 
+#'  
+#'  Note that ExperimentHub and BiocFileCache will cache the data and 
+#'  automatically detect if you have previously downloaded it, thus making it 
+#'  the preferred way to interact with the data.
 #'
 #' @param type A `character(1)` specifying which file you want to download. 
 #' `rse_gene` {RangedSummarizedExperiment} with 110 bulk RNA-seq samples
@@ -14,7 +22,7 @@
 #' [BiocFileCache-class][BiocFileCache::BiocFileCache-class]. Used when
 #' `eh` is not available.
 #'
-#' @return The requested object
+#' @return The requested object: `rse_gene` that you assign to an object
 #' @export
 #' @import ExperimentHub
 #' @import BiocFileCache
@@ -22,7 +30,22 @@
 #' @importFrom methods is
 #'
 #' @examples
-#' rse_gene <- fetch_deconvo_data("rse_gene")
+#' ## Download the bulk RNA gene expression data
+#' ## A RangedSummarizedExperiment (41.16 MB)
+#' 
+#' if (!exists("rse-gene")) rse_gene <- fetch_deconvo_data("rse_gene")
+#' 
+#' ## explore data
+#' rse_gene
+#' class: RangedSummarizedExperiment 
+#' # dim: 21745 110 
+#' # metadata(1): SPEAQeasy_settings
+#' # assays(2): counts logcounts
+#' # rownames(21745): ENSG00000227232.5 ENSG00000278267.1 ... ENSG00000210195.2 ENSG00000210196.2
+#' # rowData names(11): Length gencodeID ... gencodeTx passExprsCut
+#' # colnames(110): 2107UNHS-0291_Br2720_Mid_Bulk 2107UNHS-0291_Br2720_Mid_Cyto ... AN00000906_Br8667_Mid_Cyto
+#' # AN00000906_Br8667_Mid_Nuc
+#' # colData names(78): SAMPLE_ID Sample ... diagnosis qc_class
 #' 
 fetch_deconvo_data <- function(type = c("rse_gene"),
                              destdir = tempdir(),
diff --git a/man/fetch_deconvo_data.Rd b/man/fetch_deconvo_data.Rd
index 98b13a9..59c1633 100644
--- a/man/fetch_deconvo_data.Rd
+++ b/man/fetch_deconvo_data.Rd
@@ -28,12 +28,33 @@ were previously downloaded to avoid re-downloading them.}
 \code{eh} is not available.}
 }
 \value{
-The requested object
+The requested object: \code{rse_gene} that you assign to an object
 }
 \description{
-Download Human DLPFC Deconvolution Data
+This function downloads from ExperimentHub, if ExperimentHub is not
+available, this function will download the files from Dropbox using
+BiocFileCache::bfcrpath() unless the files are present already at destdir.
+
+Note that ExperimentHub and BiocFileCache will cache the data and
+automatically detect if you have previously downloaded it, thus making it
+the preferred way to interact with the data.
 }
 \examples{
-rse_gene <- fetch_deconvo_data("rse_gene")
+## Download the bulk RNA gene expression data
+## A RangedSummarizedExperiment (41.16 MB)
+
+if (!exists("rse-gene")) rse_gene <- fetch_deconvo_data("rse_gene")
+
+## explore data
+rse_gene
+class: RangedSummarizedExperiment 
+# dim: 21745 110 
+# metadata(1): SPEAQeasy_settings
+# assays(2): counts logcounts
+# rownames(21745): ENSG00000227232.5 ENSG00000278267.1 ... ENSG00000210195.2 ENSG00000210196.2
+# rowData names(11): Length gencodeID ... gencodeTx passExprsCut
+# colnames(110): 2107UNHS-0291_Br2720_Mid_Bulk 2107UNHS-0291_Br2720_Mid_Cyto ... AN00000906_Br8667_Mid_Cyto
+# AN00000906_Br8667_Mid_Nuc
+# colData names(78): SAMPLE_ID Sample ... diagnosis qc_class
 
 }