@@ -186,9 +186,9 @@ cbioportal2clinicaldf <- function(files) {

 #' @description **Note** that these functions should be used when a particular

 #' study is _not_ currently available as a `MultiAssayExperiment`

 #' representation. Otherwise, use `cBioDataPack`. Provide a `cancer_study_id`

-#' from the `studiesTable` and retrieve the study tarball from cBioPortal.

-#' These functions are used by `cBioDataPack` under the hood to download,

-#' untar, and load the tarball datasets with caching. As stated in

+#' from the `studiesTable` and retrieve the study tarball from the cBio

+#' Genomics Portal.  These functions are used by `cBioDataPack` under the hood

+#' to download,untar, and load the tarball datasets with caching. As stated in

 #' `?cBioDataPack`, not all studies are currently working as

 #' `MultiAssayExperiment` objects. As of July 2020, about ~80% of

 #' datasets can be successfully imported into the `MultiAssayExperiment` data

@@ -196,6 +196,13 @@ cbioportal2clinicaldf <- function(files) {

 #' study. You may also check `studiesTable$pack_build` for a more current

 #' status.

 #'

+#' @details When attempting to load a dataset using `loadStudy`, note that

+#' the `cleanup` argument is set to `TRUE` by default. Change the argument

+#' to `FALSE` if you would like to keep the untarred data in the `exdir`

+#' location. `downloadStudy` and `untarStudy` are not affected by this change.

+#' The tarball of the downloaded data is cached via `BiocFileCache` when

+#' `use_cache` is `TRUE`.

+#'

 #' @param cancer_study_id character(1) The study identifier from cBioPortal as

 #' in \url{https://cbioportal.org/webAPI}

 #'

@@ -203,16 +210,16 @@ cbioportal2clinicaldf <- function(files) {

 #' and use it to track downloaded data. If data found in the cache, data will

 #' not be re-downloaded. A path can also be provided to data cache location.

 #'

-#' @param force logical(1) (default FALSE) whether to force re-download data from

-#' remote location

+#' @param force logical(1) (default FALSE) whether to force re-download data

+#' from remote location

 #'

 #' @param url_location character(1)

 #' (default "https://cbioportal-datahub.s3.amazonaws.com") the URL location for

 #' downloading packaged data. Can be set using the 'cBio_URL' option (see

 #' `?cBioDataPack` for more details)

 #'

-#' @param names.field A character vector of possible column names for the column

-#' that is used to label ranges from a mutations or copy number file.

+#' @param names.field A character vector of possible column names for the

+#' column that is used to label ranges from a mutations or copy number file.

 #'

 #' @param cancer_study_file character(1) indicates the on-disk location

 #' of the downloaded tarball

@@ -223,6 +230,9 @@ cbioportal2clinicaldf <- function(files) {

 #' @param filepath character(1) indicates the folder location where

 #' the contents of the tarball are *located* (usually the same as `exdir`)

 #'

+#' @param cleanup logical(1) whether to delete the `untar`-red contents from

+#' the `exdir` folder (default TRUE)

+#'

 #' @return \itemize{

 #'   \item {downloadStudy - The file location of the data tarball}

 #'   \item {untarStudy - The directory location of the contents}

@@ -294,11 +304,14 @@ untarStudy <- function(cancer_study_file, exdir = tempdir()) {

 #' @rdname downloadStudy

 #'

 #' @export

-loadStudy <-

-    function(

-        filepath, names.field = c("Hugo_Symbol", "Entrez_Gene_Id", "Gene")

-    )

-{

+loadStudy <- function(

+    filepath,

+    names.field = c("Hugo_Symbol", "Entrez_Gene_Id", "Gene"),

+    cleanup = TRUE

+) {

+    if (cleanup)

+        on.exit(unlink(filepath, recursive = TRUE))

+

     datafiles <- getRelevantFilesFromStudy(

         list.files(filepath, recursive = TRUE)

     )

@@ -454,8 +467,9 @@ loadStudy <-

 #'

 #' @export

 cBioDataPack <- function(cancer_study_id, use_cache = TRUE,

-    names.field = c("Hugo_Symbol", "Entrez_Gene_Id", "Gene"), ask = TRUE) {

-

+    names.field = c("Hugo_Symbol", "Entrez_Gene_Id", "Gene"),

+    cleanup = TRUE, ask = TRUE)

+{

     denv <- new.env(parent = emptyenv())

     data("studiesTable", package = "cBioPortalData", envir = denv)

     studiesTable <- denv[["studiesTable"]]

@@ -481,6 +495,6 @@ cBioDataPack <- function(cancer_study_id, use_cache = TRUE,

     cancer_study_file <- downloadStudy(cancer_study_id, use_cache)

     exdir <- untarStudy(cancer_study_file)

-    loadStudy(exdir, names.field)

+    loadStudy(exdir, names.field, cleanup)

 }

@@ -9,6 +9,7 @@ cBioDataPack(

   cancer_study_id,

   use_cache = TRUE,

   names.field = c("Hugo_Symbol", "Entrez_Gene_Id", "Gene"),

+  cleanup = TRUE,

   ask = TRUE

 )

 }

@@ -23,6 +24,9 @@ not be re-downloaded. A path can also be provided to data cache location.}

 \item{names.field}{A character vector of possible column names for the column

 that is used to label ranges from a mutations or copy number file.}

+\item{cleanup}{logical(1) whether to delete the \code{untar}-red contents from

+the \code{exdir} folder (default TRUE)}

+

 \item{ask}{A logical vector of length one indicating whether to prompt the

 the user before downloading and loading study \code{MultiAssayExperiment}. If

 TRUE, the user will be prompted to continue for studies that are not

@@ -15,7 +15,11 @@ downloadStudy(

 untarStudy(cancer_study_file, exdir = tempdir())

-loadStudy(filepath, names.field = c("Hugo_Symbol", "Entrez_Gene_Id", "Gene"))

+loadStudy(

+  filepath,

+  names.field = c("Hugo_Symbol", "Entrez_Gene_Id", "Gene"),

+  cleanup = TRUE

+)

 }

 \arguments{

 \item{cancer_study_id}{character(1) The study identifier from cBioPortal as

@@ -25,8 +29,8 @@ in \url{https://cbioportal.org/webAPI}}

 and use it to track downloaded data. If data found in the cache, data will

 not be re-downloaded. A path can also be provided to data cache location.}

-\item{force}{logical(1) (default FALSE) whether to force re-download data from

-remote location}

+\item{force}{logical(1) (default FALSE) whether to force re-download data

+from remote location}

 \item{url_location}{character(1)

 (default "https://cbioportal-datahub.s3.amazonaws.com") the URL location for

@@ -42,8 +46,11 @@ the contents of the tarball (default \code{tempdir()}; see also \code{?untar})}

 \item{filepath}{character(1) indicates the folder location where

 the contents of the tarball are \emph{located} (usually the same as \code{exdir})}

-\item{names.field}{A character vector of possible column names for the column

-that is used to label ranges from a mutations or copy number file.}

+\item{names.field}{A character vector of possible column names for the

+column that is used to label ranges from a mutations or copy number file.}

+

+\item{cleanup}{logical(1) whether to delete the \code{untar}-red contents from

+the \code{exdir} folder (default TRUE)}

 }

 \value{

 \itemize{

@@ -56,9 +63,9 @@ that is used to label ranges from a mutations or copy number file.}

 \strong{Note} that these functions should be used when a particular

 study is \emph{not} currently available as a \code{MultiAssayExperiment}

 representation. Otherwise, use \code{cBioDataPack}. Provide a \code{cancer_study_id}

-from the \code{studiesTable} and retrieve the study tarball from cBioPortal.

-These functions are used by \code{cBioDataPack} under the hood to download,

-untar, and load the tarball datasets with caching. As stated in

+from the \code{studiesTable} and retrieve the study tarball from the cBio

+Genomics Portal.  These functions are used by \code{cBioDataPack} under the hood

+to download,untar, and load the tarball datasets with caching. As stated in

 \code{?cBioDataPack}, not all studies are currently working as

 \code{MultiAssayExperiment} objects. As of July 2020, about ~80\% of

 datasets can be successfully imported into the \code{MultiAssayExperiment} data

@@ -66,6 +73,14 @@ class. Please open an issue if you would like the team to prioritize a

 study. You may also check \code{studiesTable$pack_build} for a more current

 status.

 }

+\details{

+When attempting to load a dataset using \code{loadStudy}, note that

+the \code{cleanup} argument is set to \code{TRUE} by default. Change the argument

+to \code{FALSE} if you would like to keep the untarred data in the \code{exdir}

+location. \code{downloadStudy} and \code{untarStudy} are not affected by this change.

+The tarball of the downloaded data is cached via \code{BiocFileCache} when

+\code{use_cache} is \code{TRUE}.

+}

 \examples{

 (acc_file <- downloadStudy("acc_tcga"))