% Generated by roxygen2: do not edit by hand

 % Please edit documentation in R/cBioDataPack.R

 \name{downloadStudy}
 \alias{downloadStudy}

 \alias{untarStudy}
 \alias{loadStudy}
 \title{Manually download, untar, and load study tarballs}

 \usage{

 downloadStudy(
   cancer_study_id,
   use_cache = TRUE,
   force = FALSE,

   url_location = getOption("cBio_URL", .url_location),

   ask = interactive()

 )

 
 untarStudy(cancer_study_file, exdir = tempdir())
 

 loadStudy(
   filepath,

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

   cleanup = TRUE
 )

 }
 \arguments{

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

 seen in the dataset links at \url{https://www.cbioportal.org/datasets}.}

 \item{use_cache}{\code{logical(1)} (default TRUE) create the default cache
 location 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}{\code{logical(1)} (default FALSE) whether to force re-download data

 from remote location}

 \item{url_location}{\code{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
 \code{?cBioDataPack} for more details)}
 

 \item{ask}{\code{logical(1)} Whether to prompt the the user before downloading and

 loading study \code{MultiAssayExperiment} that is not currently building based
 on previous testing. Set to \code{interactive()} by default. In a
 non-interactive session, data download will be attempted; equivalent to
 \code{ask = FALSE}. The argument will also be used when a cache directory needs
 to be created when using \code{downloadStudy}.}
 

 \item{cancer_study_file}{\code{character(1)} indicates the on-disk location of the
 downloaded tarball}

 \item{exdir}{\code{character(1)} indicates the folder location to \emph{put} the
 contents of the tarball (default \code{tempdir()}; see also \code{?untar})}

 \item{filepath}{\code{character(1)} indicates the folder location where the
 contents of the tarball are \emph{located} (usually the same as \code{exdir})}

 \item{names.field}{\code{character()} Possible column names for the column that
 will used to label ranges for data such as mutations or copy number
 (defaults: "Hugo_Symbol", "Entrez_Gene_Id", "Gene", and
 "Composite.Element.REF"). Values are cycled through and eliminated when no
 data present, or duplicates are found. Values in the corresponding column
 must be unique in each row.}

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

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

 }

 \value{

 \itemize{

 \item downloadStudy - The file location of the data tarball
 \item untarStudy - The directory location of the contents
 \item loadStudy - A MultiAssayExperiment-class object

 }

 }

 \description{

 \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 \code{getStudies} 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 class. Please
 open an issue if you would like the team to prioritize a study. You may
 also check \code{getStudies(buildReport = TRUE)$pack_build} for the 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")
 acc_file

 file_dir <- untarStudy(acc_file, tempdir())
 file_dir

 loadStudy(file_dir)
 
 }
 \seealso{

 \link{cBioDataPack},
 \link[MultiAssayExperiment:MultiAssayExperiment-class]{MultiAssayExperiment}

 }