boxly.Rmd

---
title: "Interactive Box Plot"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Interactive Box Plot}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include=FALSE}
knitr::opts_chunk$set(
  echo = TRUE,
  collapse = TRUE,
  eval = TRUE,
  comment = "#>",
  warning = FALSE,
  message = FALSE
)
```

```{r}
library(boxly)
```

# Overview

Interactive box plots refers to the graphical representations that allow users to explore and 
analyze data through an interactive interface. They provide a way to visualize the distribution, 
central tendency, and variability of a dataset using a box-and-whisker plot, while also 
providing additional interactivity for deeper exploration.

Some common interactive features of the box plots include: 

 - Hovering: When the user hovers the mouse cursor over a specific part of the plot, additional information 
   related to that specific data point or summary statistic is displayed. This includes the descriptive 
   statistics (N, Mean, Median, Q1, Q3, Min and Max), Subject ID and Change from Baseline 
   
 - Filtering: It is possible to apply filters to the data, enabling users to select specific Parameter 
   from a domain (Labs, Vitals, ECG)
  
# Mental model

Creating the box plot using this package involves the below steps:

  - Create a list of metadata (Ex: meta) using `meta_boxly()`
  - Call `prepare_boxly()` function to prepare the metadata as required by the user 
  - Call `boxly()` function to create the interactive plot


## Example 1: Interactive Box Plot Using Labs Data

Step1: Create a list of metadata (Ex: meta) using `meta_boxly()`

```{r}
meta <- meta_boxly(
  boxly_adsl,
  boxly_adlb,
  population_term = "apat",
  observation_term = "wk12",
  observation_subset = AVISITN <= 12 & !is.na(CHG)
)
```

Step2: Call `prepare_boxly()` function to prepare the metadata as required by the user

```{r}
outdata <- prepare_boxly(meta)
outdata
```

Step 3: Call `boxly()` function to create the interactive plot

```{r}
boxly(outdata)
```

## Example 2: Interactive Box Plot Using Vital Signs Data

```{r}
meta_boxly(
  boxly_adsl,
  boxly_advs,
  population_term = "apat",
  observation_term = "wk12",
  observation_subset = AVISITN <= 12 & !is.na(CHG)
) |>
  prepare_boxly() |>
  boxly()
```

## Example 3: Interactive Box Plot Using ECG Data

```{r}
meta_boxly(
  boxly_adsl,
  boxly_adeg,
  population_term = "apat",
  observation_term = "wk12",
  observation_subset = AVISITN <= 12 & !is.na(CHG)
) |>
  prepare_boxly() |>
  boxly()
```


## Example 4: Format Mean Values in Summary Statistics

### Overview

When displaying summary statistics in the interactive box plot hover labels, you may want to control 
the precision (number of decimal places) of the mean value. The `mean_decimal` parameter in 
`prepare_boxly()` allows you to format the mean values to a specific number of decimal places.

This is particularly useful when you need to:

- Match a specific reporting format required by your analysis plan or regulatory submission
- Improve readability by reducing unnecessary decimal places
- Ensure consistency with other statistics displayed in your report
- Control the level of precision shown to stakeholders

### Basic Usage

Use the `mean_decimal` parameter to specify the number of decimal places for rounding the mean value:

```{r}
meta <- meta_boxly(
  boxly_adsl,
  boxly_adlb,
  population_term = "apat",
  observation_term = "wk12",
  observation_subset = AVISITN <= 12 & !is.na(CHG)
)

# Format mean values to 2 decimal places
outdata <- prepare_boxly(meta, mean_decimal = 2)
boxly(outdata)
```

### Example with Different Decimal Places

```{r}
# Format mean values to 1 decimal place
meta_boxly(
  boxly_adsl,
  boxly_adlb,
  population_term = "apat",
  observation_term = "wk12",
  observation_subset = AVISITN <= 12 & !is.na(CHG)
) |>
  prepare_boxly(mean_decimal = 1) |>
  boxly()
```

### Notes

- When `mean_decimal` is `NULL` (default), the mean values are displayed with full precision (not rounded)
- The mean values are rounded using base R's `round()` function
- Other summary statistics (Min, Q1, Median, Q3, Max) are not affected by this parameter
- The formatted mean values will appear in the hover label when you move your cursor over the box plot