---
title: "Introduction to TCIApathfinder"
author: "Pamela Russell"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to TCIApathfinder}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r echo = FALSE, message = FALSE}
api_key <- Sys.getenv("TCIA_API_KEY")
if (identical(api_key, "")) {
  knitr::opts_chunk$set(eval = FALSE)
  message("Note: code examples will not be evaluated because the system does not have a valid API key installed.")
}
```

# Installation

From within R:

```{r eval = FALSE}
install.packages("TCIApathfinder")
```

From GitHub:

```{r eval = FALSE}
# install.packages("devtools")
devtools::install_github("pamelarussell/TCIApathfinder")
```

# Authentication

An API key is required to access data from TCIA. To obtain and correctly store your API key:

1. Request a key from TCIA by following the instructions [here](https://wiki.cancerimagingarchive.net/display/Public/TCIA+Programmatic+Interface+%28REST+API%29+Usage+Guide).

2. Create a text file in your home directory (`~/`) called `.Renviron`. 

3. Create the contents of the `.Renviron` file like this, making sure the last line in the file is empty. Otherwise, R will silently fail to load the file.
  
    ```
    TCIA_API_KEY=xxx-xxx-xxx-xxx
    
    ```

4. Restart R. `.Renviron` is only processed at the beginning of an R session.


# Usage

## Load the package:

```{r}
library(TCIApathfinder)
```

## Get the names of all TCIA collections:

```{r}
collections <- get_collection_names()
head(collections$collection_names)
```

## Get the names of all imaging modalities

```{r}
modalities <- get_modality_names()
head(modalities$modalities)
```

Note: a collection or body part can be specified to narrow down results.

## Get the names of all body parts studied:

```{r}
body_parts <- get_body_part_names()
head(body_parts$body_parts)
```

Note: a collection or modality can be specified to narrow down results.

## Get information for all patients in a collection

```{r}
patients_tcga_brca <- get_patient_info(collection = "TCGA-BRCA")
head(patients_tcga_brca$patients)
```

Note: if no collection is passed, patients for all collections are returned.

## Get all image series based on criteria

```{r}
series <- get_series_info(patient_id = "TCGA-AR-A1AQ")
head(series$series)
```

Note: other ways to narrow down results include

- collection
- study instance UID
- series instance UID
- modality
- body part
- manufacturer
- manufacturer model name

## Get detailed information on all imaging studies for a patient

```{r}
studies <- get_patient_studies(patient_id = "TCGA-AR-A1AQ")
head(studies$patient_studies)
```

The variables in `studies$patient_studies` correspond to the fields of a PatientStudy object
as described in the [API documentation](https://wiki.cancerimagingarchive.net/display/Public/TCIA+API+Return+Values).

Note: other ways to narrow down results include a collection or a study instance UID.

## Get all imaging studies for a collection

```{r}
studies_tcga_brca <- get_studies_in_collection(collection = "TCGA-BRCA")
head(studies_tcga_brca$studies)
```

Note: a patient ID can be provided to further narrow down results.

## Get individual DICOM image IDs for an image series

```{r}
sop_uids <- get_sop_instance_uids(
  series_instance_uid = "1.3.6.1.4.1.14519.5.2.1.3344.4002.298037359751562809791703106256")
head(sop_uids$sop_instance_uids)
```

## Download a single DICOM image

```{r}
im <- save_single_image(series_instance_uid = "1.3.6.1.4.1.14519.5.2.1.3344.4002.298037359751562809791703106256",
                  sop_instance_uid = "1.3.6.1.4.1.14519.5.2.1.3344.4002.113224119964450170072494597907")
im$out_file
```

Note: a file name can be provided to override the original file name.

## Download an image series and extract it

```{r}
ser <- save_image_series(series_instance_uid = "1.3.6.1.4.1.14519.5.2.1.3344.4002.298037359751562809791703106256",
                         out_file_name = "series.zip")
zip <- ser$out_file
extracted <- extract_image_series(zip)
extracted$dirs
```

## Download, save and extract an image series, optionally to a temporary location

```{r}
ser <- save_extracted_image_series(series_instance_uid = "1.3.6.1.4.1.14519.5.2.1.5382.4002.806935685832642465081499816867")
ser$dirs
```

## Additional functions

See package documentation for further details:

- get_series_size
- get_manufacturer_names
- get_new_patients_in_collection
- get_new_studies_in_collection
- get_patients_by_modality