% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pull_data_synapse.R
\name{pull_data_synapse}
\alias{pull_data_synapse}
\title{Obtain clinical & genomic data files for GENIE BPC Project}
\usage{
pull_data_synapse(
  cohort = NULL,
  version = NULL,
  download_location = NULL,
  pat = NULL
)
}
\arguments{
\item{cohort}{Vector or list specifying the cohort(s) of interest. Must be
one of "NSCLC" (Non-Small Cell Lung Cancer), "CRC" (Colorectal Cancer), or
"BrCa" (Breast Cancer), "PANC" (Pancreatic Cancer), "Prostate" (Prostate Cancer),
"BLADDER" (Bladder Cancer), and "RENAL" (Renal Cancer). This is not case sensitive.}

\item{version}{Vector specifying the version of the cohort. Must match one of the
release versions available for the specified `cohort` (see `synapse_version()` for available cohort versions).
When entering multiple cohorts, it is inferred that the order of the version
numbers passed corresponds to the order of the cohorts passed.
Therefore, `cohort` and `version` must be in the same
order to ensure the correct data versions are pulled. See examples below for details.}

\item{download_location}{if `NULL` (default), data will be returned as a list
of dataframes with requested data as list items. Otherwise, specify a
folder path to have data automatically downloaded there. When a path is
specified, data are not read into the R environment.}

\item{pat}{'Synapse' personal access token}
}
\value{
Returns a nested list of clinical and genomic data corresponding to
the specified cohort(s).
}
\description{
Function to access specified
 versions of clinical and genomic GENIE BPC data from
 \href{https://www.synapse.org/#!Synapse:syn21226493/wiki/599164}{Synapse}
 and read them into the R environment. See the \href{https://genie-bpc.github.io/genieBPC/articles/pull_data_synapse_vignette.html}{pull_data_synapse vignette}
for further documentation and examples.
}
\section{Authentication}{

To access data, users must have a valid 'Synapse' account with permission to
access the data set and they must have accepted any necessary 'Terms of Use'.
Users must always authenticate themselves in their current R session.
(see \href{https://genie-bpc.github.io/genieBPC/articles/pull_data_synapse_vignette.html}{README: Data Access and Authentication}

for details).
To set your 'Synapse' Personal Access Token (PAT) during each session, call:
 `set_synapse_credentials(pat = "your_pat")`.

If your credentials are stored as an environmental variable, you do not need to
call `set_synapse_credentials()` explicitly each session. To store
authentication information in your environmental variables, add the following
to your .Renviron file, then restart your R session ' (tip: you can use
`usethis::edit_r_environ()` to easily open/edit this file):

\itemize{
   \item `SYNAPSE_PAT = <your-pat>`
   }
Alternatively, you can pass your PAT to each individual
data pull function if preferred, although it is recommended that you manage
your PATs outside of your scripts for security purposes.
}

\section{Analytic Data Guides}{

  Documentation corresponding to the clinical data files
  can be found on 'Synapse' in the Analytic Data Guides:
\itemize{
  \item \href{https://www.synapse.org/#!Synapse:syn23002641}{NSCLC v1.1-Consortium Analytic Data Guide}
  \item \href{https://www.synapse.org/#!Synapse:syn53463493}{NSCLC v2.2-Consortium Analytic Data Guide}
  \item \href{https://www.synapse.org/#!Synapse:syn30557304}{NSCLC v2.0-Public Analytic Data Guide}
  \item \href{https://www.synapse.org/#!Synapse:syn58597690}{NSCLC v3.1-Consortium Analytic Data Guide}
  \item \href{https://www.synapse.org/#!Synapse:syn53463650}{CRC v1.3-Consortium Analytic Data Guide}
  \item \href{https://www.synapse.org/#!Synapse:syn31751466}{CRC v2.0-Public Analytic Data Guide}
  \item \href{https://www.synapse.org/#!Synapse:syn64425776}{CRC v3.1-Consortium Analytic Data Guide}
  \item \href{https://www.synapse.org/#!Synapse:syn26077313}{BrCa v1.1-Consortium Analytic Data Guide}
  \item \href{https://www.synapse.org/#!Synapse:syn32330194}{BrCa v1.2-Consortium Analytic Data Guide}
  \item \href{https://www.synapse.org/#!Synapse:syn71825209}{BrCa v1.0-Public Analytic Data Guide}
  \item \href{https://www.synapse.org/#!Synapse:syn30787692}{BLADDER v1.1-Consortium Analytic Data Guide}
  \item \href{https://www.synapse.org/#!Synapse:syn53018714}{BLADDER v1.2-Consortium Analytic Data Guide}
  \item \href{https://www.synapse.org/#!Synapse:syn29787285}{PANC v1.1-Consortium Analytic Data Guide}
  \item \href{https://www.synapse.org/#!Synapse:syn50612821}{PANC v1.2-Consortium Analytic Data Guide}
  \item \href{https://www.synapse.org/Synapse:syn72666511}{PANC v1.0-Public Analytic Data Guide}
  \item \href{https://www.synapse.org/#!Synapse:syn30148714}{Prostate v1.1-Consortium Analytic Data Guide}
  \item \href{https://www.synapse.org/#!Synapse:syn50612204}{Prostate v1.2-Consortium Analytic Data Guide}
  \item \href{https://www.synapse.org/Synapse:syn73963128}{Prostate v1.0-Public Analytic Data Guide}
  \item \href{https://www.synapse.org/#!Synapse:syn69750457}{RENAL v1.1-Consortium Analytic Data Guide}
}
}

\examples{
\dontshow{if (genieBPC::.is_connected_to_genie(pat = Sys.getenv("SYNAPSE_PAT"))) withAutoprint(\{ # examplesIf}
# Example 1 ----------------------------------
# Set up 'Synapse' credentials
set_synapse_credentials()

# Print available versions of the data
synapse_version(most_recent = TRUE)

# Pull version 2.0-public for non-small cell lung cancer
# and version 2.0-public for colorectal cancer data

 ex1 <- pull_data_synapse(
   cohort = c("NSCLC", "CRC"),
   version = c("v2.0-public", "v2.0-public")
 )

 names(ex1)
\dontshow{\}) # examplesIf}
}
\author{
Karissa Whiting, Michael Curry
}
