Author: Pamela Russell
Date: 2019-09-21

# Introduction to TCIApathfinder

#### Pamela Russell

#### 2019-09-21

# Installation

From within R:

    install.packages("TCIApathfinder")

From GitHub:

    # 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.

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:

    library(TCIApathfinder)

## Get the names of all TCIA collections:

    collections <- get_collection_names()
    head(collections$collection_names)

## Get the names of all imaging modalities

    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:

    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

    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

    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

    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.

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

## Get all imaging studies for a collection

    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

    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

    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

    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

    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