---
title: "imageTCGA: A Shiny application to explore the TCGA Diagnostic Images"
author:
- name: Ilaria Billato
  affiliation: [
    "Department of Biology, University of Padova"
  ]
- name: Marcel Ramos Pérez
  affiliation: >
    CUNY Graduate School of Public Health and Health Policy, New York, NY USA
- name: Sean Davis
  affiliation: > 
    Channing Lab, Brigham and Womens Hospital,
    Harvard University, Boston, MA USA
- name: Sehyun Oh
  affiliation: > 
    CUNY Graduate School of Public Health and Health Policy, New York, NY USA
- name: Levi Waldron
  affiliation: > 
    CUNY Graduate School of Public Health and Health Policy, New York, NY USA
- name: Davide Risso
  affiliation: > 
    Department of Statistical Sciences, University of Padova
- name: Chiara Romualdi
  affiliation: > 
    Department of Biology, University of Padova
package: imageTCGA
output:
  BiocStyle::html_document:
    toc: true
    number_sections: true
    toc_float: true
    toc_depth: 3
vignette: >
  %\VignetteIndexEntry{imageTCGA}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE,echo=FALSE}
knitr::opts_chunk$set(
    collapse = TRUE,
    comment = "#>",
    cache = TRUE,
    out.width = "100%"
)
imageTCGAimagePath <- function(name, branch = "devel") {
    if (curl::has_internet())
        glue::glue(
            "https://github.com/billila/imageTCGA/blob/{branch}",
            "/vignettes/figures/{name}?raw=true"
        )
    else
        glue::glue("figures/{name}")
}
```

# Introduction 

`imageTCGA` is an R package designed to provide an interactive Shiny 
application for exploring the TCGA Diagnostic Image Database. 
This application allows users to filter and visualize metadata, 
geographic distribution, and other relevant statistics 
related to TCGA diagnostic images.

This package is part of the Multi-omic Integration of Histopathology 
Image Analysis working group, which addresses the need for
standardized workflows to integrate histopathology image-derived 
features with genomic and transcriptomic analyses in R/Bioconductor. 
`imageTCGA` lays the foundation for a comprehensive platform where
pre-extracted image features from Python-based tools from TCGA 
will be made accessible within R/Bioconductor data structures, 
streamlining data integration and accelerating research in 
computational pathology and precision oncology.


# Installation

```{r,eval=FALSE}
if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")

BiocManager::install("imageTCGA")
```

## Setup

Load the package:

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

## Run the shiny app

After installing the package, you can run the Shiny application
by executing the following command in R:

```{r,eval=FALSE}
imageTCGA::imageTCGA()
```

This will open the application in your default web browser,
where you can explore 11,765 diagnostic images from 9,640 patients, 
filtering them based on various clinical and pathological parameters.

```{r,echo=FALSE, fig.wide = TRUE}
knitr::include_graphics(imageTCGAimagePath("imageTCGA_shiny.png"))
```


# Filtering

The application allows filtering by any of the available columns in the dataset.
For instance, you can filter for a specific tumor type, 
such as Ovarian Cancer (107 diagnostic images).


```{r,echo=FALSE,fig.wide = TRUE}
knitr::include_graphics(imageTCGAimagePath("imageTCGA_shiny_OV.png"))
```


# R Code 

You can generate R code to download the selected images to your
local machine by clicking the orange "Generate R Code" button. 
This utilizes the GenomicDataCommons package.

In the example below, Ovarian Cancer images have been selected:

```{r,echo=FALSE,fig.wide = TRUE}
knitr::include_graphics(imageTCGAimagePath("imageTCGA_shiny_OV_Rcode.png"))
```

# Visualization 

## Dotplot 

The dot plot visualization allows users to explore gynecological tumors 
(BRCA, OV, UCS, UCEC). On the left panel, 
you can select which variables to plot on the x-axis and y-axis.

```{r,echo=FALSE,fig.wide = TRUE}
knitr::include_graphics(imageTCGAimagePath("imageTCGA_shiny_dotplot.png"))
```

## Geographic Distribution

The application provides an interactive geographic visualization, 
displaying the origin of diagnostic images at
the center, country, and state level.

For example, in the image below, GBM tumors have been selected.
Additionally, summary statistics such as the number of cities and
states are reported alongside a bar plot of the state distribution.

```{r,echo=FALSE,fig.wide = TRUE}
knitr::include_graphics(imageTCGAimagePath("imageTCGA_shiny_worldmap_GBM.png"))
```


# Session Info

<details>
    <summary>Click here for Session Info</summary>
```{r}
sessionInfo()
```
</details>