---
title: "Bioactivity APIs"
author: "Center for Computational Toxicology and Exposure"
output:
   prettydoc::html_pretty:
    theme: architect
    toc: yes
    toc_depth: 5
vignette: >
  %\VignetteIndexEntry{Bioactivity}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---
```{css, echo=FALSE}
.scroll-200 {
  max-height: 200px;
  overflow-y: auto;
}

.noticebox {
  padding: 1em;
  background: lightgray;
  color: blue;
  border: 2px solid black;
  border-radius: 10px;
}
```

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
library(httptest)
start_vignette("4")
```

```{r setup, echo=FALSE, message=FALSE, warning=FALSE}
if (!library(ccdR, logical.return = TRUE)){
  devtools::load_all()
}
```

```{r setup-print, echo = FALSE}
# Redefining the knit_print method to truncate character values to 25 characters
# in each column and to truncate the columns in the print call to prevent 
# wrapping tables with several columns.
#library(ccdR)
knit_print.data.table = function(x, ...) {
  y <- data.table::copy(x)
  y <- y[, lapply(.SD, function(t){
    if (is.character(t)){
      t <- strtrim(t, 25)
    }
    return(t)
  })]
  print(y, trunc.cols = TRUE)
}

registerS3method(
  "knit_print", "data.table", knit_print.data.table,
  envir = asNamespace("knitr")
)

# Remove this once Bioactivity goes public
stg_bioactivity_server <- 'https://api-ccte-stg.epa.gov/bioactivity/data'
```

## Introduction

In this vignette, [CCTE Bioactivity APIs](https://api-ccte.epa.gov/docs/bioactivity.html) will be explored. 

::: {.noticebox data-latex=""}

**NOTE:** Please see the introductory vignette for an overview of the *ccdR* package and initial set up instruction with API key storage.

:::

Data for the Bioactivity APIs comes from ToxCast's invitrodb. 

US EPA's Toxicity Forecaster (ToxCast) program makes *in vitro* medium- and high-throughput screening assay data publicly available for prioritization and hazard characterization of thousands of chemicals.

The ToxCast pipeline ([tcpl](https://CRAN.R-project.org/package=tcpl)) is an R package that manages, curve-fits, plots, and stores ToxCast data to populate its linked MySQL database, InvitroDB. These assays comprise Tier 2-3 of the new Computational Toxicology Blueprint, and employ automated chemical screening technologies, to evaluate the effects of chemical exposure on living cells and biological macromolecules, such as proteins (Thomas et al., 2019). More information on the ToxCast program can be found at <https://www.epa.gov/comptox-tools/toxicity-forecasting-toxcast>.

This flexible analysis pipeline is capable of efficiently processing and storing large volumes of data. The diverse data, received in heterogeneous formats from numerous vendors, are transformed to a standard computable format and loaded into the <font face="CMTT10"> tcpl </font> database by vendor-specific R scripts. Once data is loaded into the database, ToxCast utilizes generalized processing functions provided in this package to process, normalize, model, qualify, and visualize the data.

<center>

![<font style="font-size:15px"><i>Figure 1: Conceptual overview of the ToxCast Pipeline functionality</i></font>](Pictures/Fig1_tcpl_overview.png)

</center>

## Functions

Several ccdR functions are used to access the CCTE Bioactivity API data.

### Bioactivity Assay Resource

Specific assays may be searched as well as all available assays that have data.

#### Get annotation by aeid

`get_annotation_by_aeid()` retrieves annotation for a specific assay endpoint id (aeid).

```{r ccdR annotation by aeid, message=FALSE, eval=FALSE}
res_dt <- get_annotation_by_aeid(AEID = "891", API_key = apikey, Server = url)
# optionally perform this unnest, apply names_repair = "unique" to give a unique column name
# note - the gene column may be an array of multiple genes rather than just one, meaning this step may not work
#res_dt <- res_dt |> tidyr::unnest_wider(col = c("citation", "gene", "assayList"), names_repair = "unique")
```

```{r, echo=FALSE, eval=FALSE}
printFormattedTable(head(res_dt), c(4, 18, 33, 51)) # printed using custom formatted table
```

#### Get all assay annotations

`get_all_assays()` retrieves all annotations for all assays available. Optionally, the user can unnest "citation", "gene", "assayList" wider so each element has its own column.

```{r ccdR all assays, message=FALSE, eval=FALSE}
res_dt <- get_all_assays(API_key = apikey, Server = url)
# optionally perform the following unnest, apply names_repair = "unique" to give a unique column name
# note - the gene column may be an array of multiple genes rather than just one, meaning this step may not work
#res_dt <- res_dt |> tidyr::unnest_wider(col = c("citation", "gene", "assayList"), names_repair = "unique")
```

```{r, echo=FALSE, eval=FALSE}
printFormattedTable(head(res_dt), c(4, 18, 19, 33, 51)) # printed using custom formatted table
```

### Bioactivity Data Resource

There are several resources for retrieving bioactivity data associated with a variety of identifier types (e.g., DTXSID, aeid) that are available to the user. 

#### Get summary data

`get_bioactivity_summary()` retrieves a summary of the number of active hits compared to the total number tested for both multiple and single concentration by aeid.

```{r ccdR summary by aeid, message=FALSE, eval=FALSE}
res_dt <- get_bioactivity_summary(AEID = "891", API_key = apikey, Server = url)
```

```{r, echo=FALSE, eval=FALSE}
printFormattedTable(head(res_dt), c()) # printed using custom formatted table
```

#### Get data

`get_bioactivity_details()` can retrieve all available multiple concentration data by assay endpoint id (aeid), sample id (spid), Level 4 ID (m4id), or chemical DTXSID. Examples for each are provided below:

##### By spid

```{r ccdR data by spid, message=FALSE, results = FALSE, eval=FALSE}
res_dt <- get_bioactivity_details(SPID = "TP0001055F12", API_key = apikey, Server = paste0(url, "/data"))
```

```{r, echo=FALSE, eval=FALSE}
printFormattedTable(head(res_dt), c(ncol(res_dt)-2)) # printed using custom formatted table
```

##### By m4id

```{r ccdR data by m4id, message=FALSE, results = FALSE, eval=FALSE}
res_dt <- get_bioactivity_details(m4id = 739695, API_key = apikey, Server = paste0(url, "/data"))
```

```{r, echo=FALSE, eval=FALSE}
printFormattedTable(head(res_dt), c(ncol(res_dt)-2)) # printed using custom formatted table
```

##### By DTXSID

```{r ccdR data by dtxsid, message=FALSE, results = FALSE, eval=FALSE}
res_dt <- get_bioactivity_details(DTXSID = "DTXSID7020182", API_key = apikey, Server = paste0(url, "/data"))
```

```{r, echo=FALSE, eval=FALSE}
printFormattedTable(head(res_dt), c(ncol(res_dt)-2)) # printed using custom formatted table
```

##### By aeid

```{r ccdR data by aeid, message=FALSE, results = FALSE, eval=FALSE}
res_dt <- get_bioactivity_details(AEID = "891", API_key = apikey, Server = paste0(url, "/data"))
```

```{r, echo=FALSE, eval=FALSE}
printFormattedTable(res_dt[205:210,], c(ncol(res_dt)-2)) # printed using custom formatted table
```


## Conclusion

In this vignette, a variety of functions that access different types of data found in the `Bioactivity` endpoints of the CCTE APIs were listed. We encourage the reader to explore the data accessible through these endpoints work with it to get a better understanding of what data is available. Additional endpoints and corresponding functions exist and we encourage the user to explore these.

```{r breakdown, echo = FALSE, results = 'hide'}
# This chunk will be hidden in the final product. It serves to undo defining the
# custom print function to prevent unexpected behavior after this module during
# the final knitting process

knit_print.data.table = knitr::normal_print
  
registerS3method(
  "knit_print", "data.table", knit_print.data.table,
  envir = asNamespace("knitr")
)
```

```{r, include=FALSE}
end_vignette()
```
