---
title: "cBioPortalData: User Start Guide"
author: "Marcel Ramos"
date: "`r format(Sys.time(), '%B %d, %Y')`"
vignette: >
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteIndexEntry{cBioPortal User Guide}
  %\VignetteEncoding{UTF-8}
output:
  BiocStyle::html_document:
    number_sections: no
    toc: yes
    toc_depth: 4
---

```{r, setup, include=FALSE}
knitr::opts_chunk$set(cache = TRUE)
```

# Installation

```{r,include=TRUE,results="hide",message=FALSE,warning=FALSE}
library(cBioPortalData)
library(AnVIL)
```

# Introduction

This vignette lays out the two main user-facing functions for downloading
and representing data from the cBioPortal API. `cBioDataPack`
makes use of the legacy distribution data method in `cBioPortal` (via
tarballs). `cBioPortalData` allows for a more flexibile approach to obtaining
data based on several available parameters including available molecular
profiles.

## Two main interfaces

### cBioDataPack: Obtain Study Data as Zipped Tarballs

This function will access the packaged data from \url{cBioPortal.org/datasets}
and return an integrative MultiAssayExperiment representation.

```{r,message=FALSE,warning=FALSE}
## Use ask=FALSE for non-interactive use
cBioDataPack("laml_tcga", ask = FALSE)
```

### cBioPortalData: Obtain data from the cBioPortal API

This function provides a more flexible and granular way to request a
MultiAssayExperiment object from a study ID, molecular profile, gene panel,
sample list.

```{r,warning=FALSE}
cbio <- cBioPortal()
acc <- cBioPortalData(api = cbio, by = "hugoGeneSymbol", studyId = "acc_tcga",
    genePanelId = "IMPACT341",
    molecularProfileIds = c("acc_tcga_rppa", "acc_tcga_linear_CNA")
)
acc
```

## Clearing the cache

### cBioDataPack

In cases where a download is interrupted, the user may experience a corrupt
cache. The user can clear the cache for a particular study by using the
`removeCache` function. Note that this function only works for data downloaded
through the `cBioDataPack` function.

```{r,eval=FALSE}
removeCache("laml_tcga")
```

### cBioPortalData

For users who wish to clear the entire `cBioPortalData` cache, it is
recommended that they use:

```{r,eval=FALSE}
unlink("~/.cache/cBioPortalData/")
```

# sessionInfo

```{r}
sessionInfo()
```