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:

extracting the summary statistics table with the computeSummaryStatisticsTable function (used for getSummaryStatistics function)
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)

Visualization functionalities

Laure Cougnaud

June 12, 2024