# Visualization functionalities

#### Laure Cougnaud

#### June 12, 2024

This vignette focuses on the visualization functionalities available within the `inTextSummaryTable` package.

If you need to see figures bigger, just click on a graphic, and it will pop up more readable.

Summary statistics can be visualized by:

1. extracting the summary statistics table with the `computeSummaryStatisticsTable` function (used for `getSummaryStatistics` function)
2. visualizing the summary statistics via the `subjectProfileSummaryPlot` function

By default the `subjectProfileSummaryPlot` plots the mean values with error bars based on standard errors.

Moreover, the `subjectProfileSummaryPlot` allows the possibility to add a table of counts of the number of subject for a specific combination of variables.

This vignette will guide the user to

- default visualizations for A4 and presentation documents
- customize palettes of colors, shape, linetypes
- visualization with and without table of counts and by facets
- general customizable input

However, in order to get a full overview of the functionalities the documentation is available in the console with `? subjectProfileSummaryPlot`.

We will first create example data sets to show how the exporting functionalities work. The data sets used here are available in the `clinUtils` package.

# 1 Load packages and data

    library(inTextSummaryTable)
    library(clinUtils)
    library(pander)
    # 'Tahoma' font should be registered upfront to create plots with: 'presentation' style
    library(extrafont)

    # load example data
    data(dataADaMCDISCP01)

    dataAll <- dataADaMCDISCP01
    labelVars <- attr(dataAll, "labelVars")

# 2 Compute summary statistics

Below we compute summary statistics for the laboratory data set.

    dataLB <- subset(dataAll$ADLBC, grepl("Baseline|Week", AVISIT))
    dataLB$AVISIT <- with(dataLB, reorder(trimws(AVISIT), AVISITN))
    dataLB$TRTA <- with(dataLB, reorder(TRTA, TRTAN))

    summaryTableDf <- computeSummaryStatisticsTable(
        data = dataLB,
        var = "AVAL",
        rowVar = c("PARCAT1", "PARAM"),
        colVar = c("TRTA", "AVISIT")
    )

# 3 Visualization for A4 document

The code below shows the default visualization, which plots the mean with standard errors suitable for an A4 document, e.g. Word/pdf.

Note that the table below the plot is based on the counts for treatment and visit variables, as specificed in the `colVar` argument of the code chuck above for `computeSummaryStatisticsTable`.

    # create the plot
    dataPlot <- subset(
        summaryTableDf,
        !isTotal &
         PARAM == "Alanine Aminotransferase (U/L)"
    )

    subjectProfileSummaryPlot(
        data = dataPlot,
        xVar = "AVISIT",
        colorVar = "TRTA",
        labelVars = labelVars,
        useLinetype = TRUE,
        tableText = "statN"
    )

# 4 Visualization for presentation

The code below shows the default visualization suitable for a presentation, either in Powerpoint or ioslides.

    subjectProfileSummaryPlot(
        data = dataPlot,
        xVar = "AVISIT",
        colorVar = "TRTA",
        labelVars = labelVars,
        useLinetype = TRUE,
        tableText = "statN",
        style = "presentation"
    )

Please note that the default font for presentation is Tahoma.

If you don’t have this default font available, the R package extrafont might be useful to register fonts with your R graphics device.

# 5 Palettes

The `inTextSummaryTable` uses default palettes available in the `clinUtils` package.

However, palettes are fully customizable. Currently, there are two alternative approaches to change the defaults:

- set the custom palettes as arguments in the `subjectProfileSummaryPlot` via the dedicated parameters `colorPalette`, `shapePalette`, `linetypePalette`
- set the global options into the R session.

Passing input arguments to the function might be convenient when creating one plot.

Instead, passing the global options is very handy when creating multiple graphics, so that the palettes have to be set only once at the beginning of the R script, without the need to copy-paste input arguments in the different visualizations.

If you want to know more about aesthetics options of the `inTextSummaryTable`, there is a dedicated vignette available here) or with

    vignette("inTextSummaryTable-aesthetics", "inTextSummaryTable")

If you want to know more about default options from the `clinUtils`, you may check out the vignette of the package:

    vignette("clinUtils-vignette", "clinUtils")

Sections below show below both alternative approaches for setting the palettes.

## 5.1 Custom palettes via arguments in the function

In this section we guide on how to set custom palettes via the `subjectProfileSummaryPlot` function.

### 5.1.1 Color palette

This section focuses on the possibility to set the `colorPalette` argument.

    # custom color palette by setting a named vector of colors
    customColorPalette <- c(
        `Xanomeline Low Dose` = "green",
        `Xanomeline High Dose` = "red",
        `Placebo` = "blue"
    )
    subjectProfileSummaryPlot(
        data = dataPlot,
        xVar = "AVISIT",
        colorVar = "TRTA",
        colorPalette = customColorPalette,
        labelVars = labelVars,
        useLinetype = TRUE,
        tableText = "statN"
    )

### 5.1.2 Shape and linetype palettes

This section focuses on the possibility to set the `shapePalette` and `linetypePalette` arguments.

    # custom shape palette
    customShapePalette <- c(15, 17, 19)
    subjectProfileSummaryPlot(
        data = dataPlot,
        xVar = "AVISIT",
        colorVar = "TRTA",
        shapePalette = customShapePalette,
        labelVars = labelVars,
        useLinetype = TRUE,
        tableText = "statN"
    )

    # custom linetype palette
    customLinetypePalette <- c("twodash", "dotted", "longdash")
    subjectProfileSummaryPlot(
        data = dataPlot,
        xVar = "AVISIT",
        colorVar = "TRTA",
        linetypePalette = customLinetypePalette,
        labelVars = labelVars,
        useLinetype = TRUE,
        tableText = "statN"
    )

## 5.2 Custom palettes via setting global options

The `inTextSummaryTable` package allows the user to define global options in the R session.

As mentioned above, setting the global options is convenient because the palettes have to be set only once in the R script or Rmd document.

Please note that the global options have to be set after loading the package. This because when loading the package, the default global options for palettes will overwrite the custom palettes.

Here in practice:

    # this is OK
    library(inTextSummaryTable)
    options(inTextSummaryTable.colors.plot = customColorPalette)

    # this does NOT set your custom palette
    options(inTextSummaryTable.colors.plot = customColorPalette)
    library(inTextSummaryTable)

### 5.2.1 Coloring palettes

Color palettes can be set up with the `inTextSummaryTable.colors.plot` option.

    # custom color palette by setting a simple vector of colors
    customColorPalette <- c("blue", "green", "orange")
    options(inTextSummaryTable.colors.plot = customColorPalette)

    subjectProfileSummaryPlot(
        data = dataPlot,
        xVar = "AVISIT",
        colorVar = "TRTA",
        labelVars = labelVars,
        useLinetype = TRUE,
        tableText = "statN"
    )

    # custom color palette by setting a named vector of colors
    customColorPalette <- c(
        `Xanomeline Low Dose` = "green",
        `Xanomeline High Dose` = "red",
        `Placebo` = "purple"
    )
    options(inTextSummaryTable.colors.plot = customColorPalette)

    subjectProfileSummaryPlot(
        data = dataPlot,
        xVar = "AVISIT",
        colorVar = "TRTA",
        labelVars = labelVars,
        useLinetype = TRUE,
        tableText = "statN"
    )

### 5.2.2 Shape and linetype palettes

What shown for the color palette is consistent for shape and linetypes palettes. In this case, the global options are called `inTextSummaryTable.shapes.plot` and `inTextSummaryTable.linetypes.plot`.

    # custom shape palette
    customShapePalette <- c(17, 19, 22)
    options(inTextSummaryTable.shapes.plot = customShapePalette)

    subjectProfileSummaryPlot(
        data = dataPlot,
        xVar = "AVISIT",
        colorVar = "TRTA",
        labelVars = labelVars,
        useLinetype = TRUE,
        tableText = "statN"
    )

    # custom linetype palette
    customLinetypePalette <- c("dotted", "longdash", "solid")
    options(inTextSummaryTable.linetypes.plot = customLinetypePalette)

    subjectProfileSummaryPlot(
        data = dataPlot,
        xVar = "AVISIT",
        colorVar = "TRTA",
        labelVars = labelVars,
        useLinetype = TRUE,
        tableText = "statN"
    )

## 5.3 Set back default palettes

There is always to possibility to switch back to the default palettes of the package:

    options(inTextSummaryTable.colors.plot = clinColors)
    options(inTextSummaryTable.shapes.plot = clinShapes)
    options(inTextSummaryTable.linetypes.plot = clinLinetypes)

# 6 Visualization without count table

The user can decide to remove the table of counts by setting the parameter `tableText` to `NULL`, as the code below shows.

    subjectProfileSummaryPlot(
        data = dataPlot,
        xVar = "AVISIT",
        colorVar = "TRTA",
        labelVars = labelVars,
        useLinetype = TRUE,
        tableText = NULL
    )

# 7 Visualization by facets

It is possible to directly plot multiple parameters with the `facetVar` argument.

Please note that setting the `facetVar` is not compatible with adding a table of counts underneath the plot.

    # create the plot
    dataPlotFacets <- subset(
        summaryTableDf,
        !isTotal &
            PARAM %in% c(
                "Alanine Aminotransferase (U/L)",
                "Albumin (g/L)",
                "Bilirubin (umol/L)",
                "Calcium (mmol/L)"
            )
    )

    subjectProfileSummaryPlot(
        data = dataPlotFacets,
        xVar = "AVISIT",
        colorVar = "TRTA",
        labelVars = labelVars,
        facetVar = c("PARCAT1", "PARAM"),
        useLinetype = TRUE
    )

# 8 Customize your visualization

The `subjectProfileSummaryPlot` has many options! A non-exaustive demonstration is presented below.

    # plot the median instead of mean
    # no error bars
    subjectProfileSummaryPlot(
        data = dataPlot,
        xVar = "AVISIT",
        meanVar = "statMedian",
        seVar = NULL,
        colorVar = "TRTA",
        labelVars = labelVars,
        useLinetype = TRUE,
        tableText = "statN"
    )

    # plot the mean with standard deviation
    subjectProfileSummaryPlot(
        data = dataPlot,
        xVar = "AVISIT",
        seVar = "statSD",
        colorVar = "TRTA",
        labelVars = labelVars,
        useLinetype = TRUE,
        tableText = "statN"
    )

    # change labels
    subjectProfileSummaryPlot(
        data = dataPlot,
        xVar = "AVISIT",
        xLab = "Time points",
        yLab = "Mean and Standard Errors",
        title = "Title of the plot",
        colorVar = "TRTA",
        labelVars = labelVars,
        useLinetype = TRUE,
        tableText = "statN"
    )

# 9 Appendix

## 9.1 Session information

R version 4.4.0 (2024-04-24)

Platform: x86_64-pc-linux-gnu

locale: C

attached base packages: tools, stats, graphics, grDevices, utils, datasets, methods and base

other attached packages: extrafont(v.0.19), plyr(v.1.8.9), pander(v.0.6.5), clinUtils(v.0.2.0), inTextSummaryTable(v.3.3.3) and knitr(v.1.47)

loaded via a namespace (and not attached): gtable(v.0.3.5), xfun(v.0.44), bslib(v.0.7.0), ggplot2(v.3.5.1), htmlwidgets(v.1.6.4), ggrepel(v.0.9.5), vctrs(v.0.6.5), crosstalk(v.1.2.1), generics(v.0.1.3), curl(v.5.2.1), tibble(v.3.2.1), fansi(v.1.0.6), highr(v.0.11), pkgconfig(v.2.0.3), data.table(v.1.15.4), uuid(v.1.2-0), lifecycle(v.1.0.4), flextable(v.0.9.6), farver(v.2.1.2), stringr(v.1.5.1), compiler(v.4.4.0), textshaping(v.0.4.0), munsell(v.0.5.1), httpuv(v.1.6.15), fontquiver(v.0.2.1), fontLiberation(v.0.1.0), htmltools(v.0.5.8.1), sass(v.0.4.9), yaml(v.2.3.8), Rttf2pt1(v.1.3.12), extrafontdb(v.1.0), later(v.1.3.2), pillar(v.1.9.0), crayon(v.1.5.2), jquerylib(v.0.1.4), gfonts(v.0.2.0), openssl(v.2.2.0), DT(v.0.33), cachem(v.1.1.0), mime(v.0.12), fontBitstreamVera(v.0.1.1), tidyselect(v.1.2.1), zip(v.2.3.1), digest(v.0.6.35), stringi(v.1.8.4), reshape2(v.1.4.4), dplyr(v.1.1.4), labeling(v.0.4.3), forcats(v.1.0.0), cowplot(v.1.1.3), fastmap(v.1.2.0), grid(v.4.4.0), colorspace(v.2.1-0), cli(v.3.6.2), magrittr(v.2.0.3), crul(v.1.4.2), utf8(v.1.2.4), withr(v.3.0.0), gdtools(v.0.3.7), scales(v.1.3.0), promises(v.1.3.0), rmarkdown(v.2.27), officer(v.0.6.6), askpass(v.1.2.0), ragg(v.1.3.2), hms(v.1.1.3), shiny(v.1.8.1.1), evaluate(v.0.24.0), haven(v.2.5.4), viridisLite(v.0.4.2), rlang(v.1.1.4), Rcpp(v.1.0.12), xtable(v.1.8-4), glue(v.1.7.0), httpcode(v.0.3.0), xml2(v.1.3.6), jsonlite(v.1.8.8), R6(v.2.5.1) and systemfonts(v.1.1.0)