---
title: "Getting started with teal.goshawk"
author: "NEST CoreDev Team"
date: "10.11.2022"
output:
  rmarkdown::html_document:
    theme: "spacelab"
    highlight: "kate"
    toc: true
    toc_float: true
vignette: >
  %\VignetteIndexEntry{Getting started}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

### Introduction

`teal.goshawk` is a package implementing a number of `teal` modules helpful for exploring clinical
trials data, specifically targeted at data following the [`ADaM`](https://www.cdisc.org/standards/foundational/adam) 
standards. `teal.goshawk` modules can be used with data other than `ADaM` standard clinical data but some 
features of the package will likely not be applicable.

The concepts presented here require knowledge about the core features of `teal`, specifically on how to launch a `teal`
application and how to pass data into it. Therefore, it is highly recommended to refer to the [`README`](https://insightsengineering.github.io/teal/latest-tag/) file and the introductory [`vignette`](https://insightsengineering.github.io/teal/latest-tag/articles/index.html) of the `teal` package.

### Main features

The package provides ready-to-use `teal` modules you can embed in your `teal` application. The modules
generate highly customizable plots and outputs often used in exploratory data analysis, e.g.:

- box plots - `tm_g_gh_boxplot()`
- correlation and scatter plots - `tm_g_gh_correlationplot()` and `tm_g_gh_scatterplot()`
- density distribution plots - `tm_g_gh_density_distribution_plot()`
- line plots - `tm_g_gh_lineplot()`
- spaghetti plots - `tm_g_spaghettiplot()`

See [`package functions / modules`](https://insightsengineering.github.io/teal.goshawk/latest-tag/reference/).


### A simple application

A `teal.goshawk` module needs to be embedded inside a `shiny` / `teal` application to interact with it. 

There is no need to load `teal` as `teal.goshawk` already depends on it.
`nestcolor` is an optional package that can be loaded in to apply the standardized NEST color palette to all module plots.

A simple application including the box plot module could look like this:

```r
library(teal.goshawk)
library(nestcolor)

data <- teal_data()
data <- within(data, {
  ADSL <- goshawk::rADSL %>% 
    mutate(TRTORD = case_when(
      TRT01P == "A: Drug X" ~ 1,
      TRT01P == "C: Combination" ~ 2,
      TRT01P == "B: Placebo" ~ 3,
      TRUE ~ as.numeric(NA)
    )
    )
  
  ADLB <- goshawk::rADLB %>% 
    mutate(AVISITCD = AVISIT,
           TRTORD = case_when(
             TRT01P == "A: Drug X" ~ 1,
             TRT01P == "C: Combination" ~ 2,
             TRT01P == "B: Placebo" ~ 3,
             TRUE ~ as.numeric(NA)
           )
    )
})

datanames <- c("ADSL", "ADLB")
datanames(data)<- datanames
join_keys(data) <- default_cdisc_join_keys[datanames]

app <- teal::init(
  data = data,
  modules = list(
    tm_g_gh_boxplot(
      label = "Longitudinal Analysis",
      dataname = "ADLB",
      param_var = "PARAMCD",
      param = teal.transform::choices_selected(
        choices = c("ALT", "CRP", "IGA"),
        selected = c("ALT")
      ),
      trt_group = teal.transform::choices_selected(
        choices = c("TRT01P", "TRT01A"),
        selected = c("TRT01P")
      ),
      facet_var = teal.transform::choices_selected(
        choices = c("TRT01P", "TRT01A"),
        selected = c("TRT01P")
      ),
      rotate_xlab = TRUE
    )
  )
)

if (interactive()) shiny::shinyApp(app$ui, app$server)
```

Refer to the [Get Started](https://insightsengineering.github.io/teal.modules.clinical/latest-tag/articles/teal-modules-clinical.html)
section of the teal.modules.clinical package that provides additional detail on `teal` concepts as applied in another simple app
example.

Please see additional information under [Articles](https://insightsengineering.github.io/teal.goshawk/latest-tag/articles/index.html) for data expectations, requirements and pre/post-processing rationale