In Open-Systems-Pharmacology/TLF-Library: TLF Library

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  dpi = 300,
  fig.align = "center",
  out.width = "100%",
  fig.height = 6,
  fig.width = 8,
  fig.showtext = TRUE
)

require(tlf)

This vignette tackles about PlotConfiguration objects and their implementation within the tlf-library.

1. Introduction

PlotConfiguration objects are R6 class objects that define plot properties.

To create such an object, the method new() is required. Multiple arguments can be passed on the method in order to directly define the properties. The properties default values can be handled and managed using the concept of themes.

As the example below illustrates, the following plot properties are defined by the PlotConfiguration class. Each of these properties is managed by a different R6 class object detailed in the next sections:

• labels
• background
• xAxis/yAxis
• legend
• export
• points/lines/ribbons/errorbars

# Creates a PlotConfiguration with default properties
myConfiguration <- PlotConfiguration$new()

myConfiguration

# Creates a PlotConfiguration with title and watermark as user-defined properties
myConfiguration <- PlotConfiguration$new(
  title = "my title",
  watermark = "my watermark"
)

myConfiguration

When a ggplot object is initialized using the tlf method initializePlot, a plotConfiguration field is added to the plot object. This field corresponds to a PlotConfiguration object and defining the properties of the initialized plot.

PlotConfiguration objects can also be directly passed to the method initializePlot as shown below:

# Creates an empty plot with default PlotConfiguration properties
emptyPlot <- initializePlot()

emptyPlot$plotConfiguration

emptyPlot

Figure: empty plot with default PlotConfiguration properties

# Creates an empty plot with title and watermark as user-defined properties
myEmptyPlot <- initializePlot(myConfiguration)

myEmptyPlot$plotConfiguration

myEmptyPlot

Figure: empty plot with title and watermark as user-defined properties

2. Label configuration: labels

2.1. Label and Label configuration objects

The field labels from the PlotConfiguration object is a LabelConfiguration object. It defines the label properties of the following plot captions:

• title
• subtitle
• xlabel
• ylabel
• caption

Each field is a Label object that associate a text with font properties:

title <- Label$new(
  text = "This is a title text",
  font = Font$new(
    color = "red",
    size = 12
  )
)

knitr::kable(data.frame(
  "text" = title$text,
  "color" = title$font$color,
  "size" = title$font$size,
  "fontFace" = title$font$fontFace,
  "fontFamily" = title$font$fontFamily,
  "angle" = title$font$angle,
  "align" = title$font$align
))

When initializing a LabelConfiguration or PlotConfiguration object, Label and/or character objects can be passed on.

Character objects will be converted into Label objects internally using the current theme.

myRedPlotLabel <- LabelConfiguration$new(title = Label$new(
  text = "my title",
  color = "red"
))

Property <- c("text", "font$color", "font$size", "font$angle", "font$align", "font$fontFace", "font$fontFamily")
displayNullValue <- function(value) {
  if (is.null(value)) {
    return("*NULL*")
  }
  return(value)
}
labelProperties <- cbind.data.frame(
  Property = Property,
  sapply(
    c("title", "subtitle", "xlabel", "ylabel", "caption"),
    function(labelName) {
      #
      # Use an expression to get all the properties of the label in one line
      eval(parse(text = paste0(
        "c(", paste0("displayNullValue(myRedPlotLabel[[labelName]]$", Property, ")", collapse = ", "), ")"
      )))
    }
  )
)

knitr::kable(labelProperties)

[!CAUTION] Label elements leverage ggtext::element_textbox_simple() and use markdown/html formatting. As a consequence, their line breaks need to be defined using the html tag <br>.

2.2. Label configuration in plots

The effect of label configuration in plots is straightforward:

plotConfigurationLabel1 <- PlotConfiguration$new(
  title = "Title",
  subtitle = "Subtitle",
  xlabel = "x label",
  ylabel = "y label",
  caption = "Caption"
)

pLab1 <- initializePlot(plotConfigurationLabel1)

pLab1

Figure: Empty plot with labels defined as character using default label properties

plotConfigurationLabel2 <- PlotConfiguration$new(
  title = Label$new(text = "Title", size = 12, color = "deepskyblue4"),
  subtitle = Label$new(text = "Subtitle", size = 11, color = "steelblue"),
  xlabel = Label$new(text = "x label", size = 10, color = "dodgerblue2"),
  ylabel = Label$new(text = "y label", color = "dodgerblue2", angle = 0),
  caption = Label$new(text = "Caption", size = 8, color = "steelblue", align = Alignments$left)
)

pLab2 <- initializePlot(plotConfigurationLabel2)

pLab2

Figure: Empty plot with labels defined as Label updating default label properties

2.3. Changing plot labels

After creating a plot, it is possible to change its label configuration using the tlf method setPlotLabels. The method requires the plot object and which label property to update.

Similar to the construction of the Label configuration, Label and/or character objects can be passed on.

Using the previous example, pLab2,

setPlotLabels(pLab2, title = "new title")

setPlotLabels(pLab2, title = Label$new(text = "new title", color = "red"))

2.4. Smart plot configurations

Smart plot labels are available for initializing PlotConfiguration objects. The principle is to provide in advance the data that will be used within the plot. As a consequence, three optional arguments can be passed on PlotConfiguration initialization: data, metaData and dataMapping.

If no label is specifically defined, the smart configuration will fetch x and y labels within data and metaData names based on the dataMapping. dataMapping also uses smart functions that will check the input data frame - if not specifically initialized - and will use variables named "x" and "y" as x and y.

The four examples below illustrate the smart configurations:

pSmart1 and pSmart2 will turn out the same, while pSmart3 will use the information from metaData to write the x and y labels. pSmart4 will overwrite the y label and title based on the input.

time <- seq(0, 20, 0.1)
myData <- data.frame(
  x = time,
  y = 2 * cos(time)
)
myMetaData <- list(
  x = list(
    dimension = "Time",
    unit = "min"
  ),
  y = list(
    dimension = "Amplitude",
    unit = "cm"
  )
)
myMapping <- XYGDataMapping$new(
  x = "x",
  y = "y"
)

smartConfig1 <- PlotConfiguration$new(data = myData)
smartConfig2 <- PlotConfiguration$new(
  data = myData,
  dataMapping = myMapping
)
smartConfig3 <- PlotConfiguration$new(
  data = myData,
  metaData = myMetaData
)
smartConfig4 <- PlotConfiguration$new(
  title = Label$new(text = "Cosinus", size = 14),
  ylabel = "Variations",
  data = myData,
  metaData = myMetaData
)

pSmart1 <- initializePlot(smartConfig1)
pSmart2 <- initializePlot(smartConfig2)
pSmart3 <- initializePlot(smartConfig3)
pSmart4 <- initializePlot(smartConfig4)

patchwork::wrap_plots(pSmart1, pSmart2, ncol = 2)

patchwork::wrap_plots(pSmart3, pSmart4, ncol = 2)

Since all of the tlf plots are internally using initializePlot, if a previous plot is not provided, the smart configurations can directly be used through the plot functions. Consequently, if scatter1 will provide simple x and y labels, scatter2 will name these labels after the metaData properties.

As for scatter3 and scatter4, they will use the plotConfiguration defined by smartConfig4 and lead to the exact same plot.

scatter1 <- addScatter(data = myData)
scatter2 <- addScatter(
  data = myData,
  metaData = myMetaData
)

scatter3 <- addScatter(
  data = myData,
  plotConfiguration = smartConfig4
)
scatter4 <- initializePlot(smartConfig4)
scatter4 <- addScatter(
  data = myData,
  plotObject = scatter4
)

patchwork::wrap_plots(scatter1, scatter2, ncol = 2)

patchwork::wrap_plots(scatter3, scatter4, ncol = 2)

3. Background configuration: background

3.1. Background configuration properties

Background configuration defines the configuration of the following Background elements: - plot - panel - xGrid - yGrid - xAxis - yAxis - legendPosition - watermark

Except for watermark and legendPosition, which are the text of the watermark and the position of the legend defined as an element of LegendPositions enum, background fields are LineElement and BackgroundElement objects, which define the properties of the background element.

As for all the PlotConfiguration inputs, their default values are defined from the current Theme, however this default can be overwritten.

For instance:

background <- BackgroundConfiguration$new()

knitr::kable(
  data.frame(
    Property = c("color", "size", "linetype", "fill"),
    plot = c(background$plot$color, background$plot$size, background$plot$linetype, background$plot$fill),
    panel = c(background$panel$color, background$panel$size, background$panel$linetype, background$panel$fill),
    xGrid = c(background$xGrid$color, background$xGrid$size, background$xGrid$linetype, ""),
    yGrid = c(background$yGrid$color, background$yGrid$size, background$yGrid$linetype, ""),
    xAxis = c(background$xAxis$color, background$xAxis$size, background$xAxis$linetype, ""),
    yAxis = c(background$yAxis$color, background$yAxis$size, background$yAxis$linetype, "")
  )
)

3.2. Background configuration in plots

The effect of background configuration in plots is also quite straightforward:

plotConfigurationBackground1 <- PlotConfiguration$new(watermark = "My Watermark")

pBack1 <- initializePlot(plotConfigurationBackground1)

plotConfigurationBackground1$background$watermark <- Label$new(text = "Hello world", color = "goldenrod4", size = 8)
plotConfigurationBackground1$background$plot <- BackgroundElement$new(fill = "lemonchiffon", color = "goldenrod3", linetype = "solid")
plotConfigurationBackground1$background$panel <- BackgroundElement$new(fill = "grey", color = "black", linetype = "solid")
pBack2 <- initializePlot(plotConfigurationBackground1)

patchwork::wrap_plots(pBack1, pBack2, ncol = 2)

3.3. Changing background properties

After creating a plot, it is possible to change its background configuration using the following tlf methods:

• setBackground, setBackgroundPanelArea, and setBackgroundPlotArea
• setGrid, setXGrid and setYGrid
• setWatermark

3.3.1. Set Background

The methods setBackground, setBackgroundPanelArea, and setBackgroundPlotArea require the plot object and which properties to update.

Using the previous example, scatter1,

setBackground(scatter1, fill = "lemonchiffon", color = "darkgreen", linetype = "solid")

setBackgroundPanelArea(scatter1, fill = "lemonchiffon", color = "darkgreen", linetype = "solid")

3.3.2. Set Grid

The methods setGrid, setXGrid, and setYGrid are very similar and require the plot object and the grid properties to be updated.

Using the previous example scatter1:

setGrid(scatter1, linetype = "blank")

setXGrid(scatter1, linetype = "blank")

setYGrid(scatter1, linetype = "blank")

3.3.3. Set Watermark

The setWatermark method requires the plot object, the watermark, and its properties to update.

Among its properties, the following are the few important ones:

• The property alpha is a value between 0 and 1 managing transparency of the watermark. The closer to 0, the more transparent the watermark will be. The closer to 1, the more opaque the watermark will be.
• The property angle, is the angle of the watermark in degrees.

Using the previous example scatter1:

setWatermark(scatter1, watermark = "Hello watermark !!")

setWatermark(scatter1, watermark = "Confidential", angle = 45, size = 6, color = "firebrick")

4. X/Y axes configurations: xAxis/yAxis

The fields xAxis and yAxis from the PlotConfiguration object are a XAxisConfiguration and YAxisConfiguration R6 class objects. They define the following plot properties:

• scale
• limits
• ticks
• ticklabels
• font

The property scale is a character string corresponding the axis scale. Available scales are r paste0(c('"', paste0(Scaling, collapse = '", "'), '"'), collapse="") and can be accessed using the enum Scaling. The property limits is a vector defining the range of the axis.

Regarding ticks and ticklabels, their values are directly be passed on and managed by ggplot2. The value "default" will leave the management of the limits to R. The properties ticks and ticklabels are vectors defining the plot ticks and their labels. These vectors are required to have the same length. The value "default" will leave the management of the limits to R.

When initializing a XAxisConfiguration, YAxisConfiguration, or PlotConfiguration objects, the axis properties can be passed on.

myAxisConfiguration <- XAxisConfiguration$new()

myAxisConfiguration$scale
myAxisConfiguration$ticklabels

4.1. Axis configuration in plots

Changing axis properties

The methods setXAxis and setYAxis require the plot object, and the axis properties to update. Using the previous example, scatter1:

setXAxis(scatter1, axisLimits = c(0.5, 20), scale = Scaling$sqrt)

setXAxis(scatter1,
  axisLimits = c(0, 6 * pi),
  ticks = seq(0, 6 * pi, pi),
  ticklabels = TickLabelTransforms$pi,
  font = Font$new(color = "dodgerblue")
)

5. Legend configuration: legend

The field legend from the PlotConfiguration object is a LegendConfiguration R6 class object. It defines the following plot properties:

• title
• position
• caption

The property title is a character string corresponding the legend title. The property position is a character string corresponding the legend position. Available legend positions are r paste0(c('"', paste0(LegendPositions, collapse = '", "'), '"'), collapse="") and can be accessed using the enum LegendPositions. The property caption is a data.frame defining the caption properties of the legend.

myLegend <- LegendConfiguration$new(position = LegendPositions$insideTopRight)

5.1. Legend configuration in plots

Legend position can be modified using the function setLegendPosition The methods setLegendPosition requires the plot object, and the position as defined by the elements of the enum LegendPositions Using the previous example, scatter1:

setLegendPosition(scatter1, LegendPositions$insideTopLeft)

6. Default plot configuration: Theme objects

The class Theme allows a user-friendly way to set many default plot settings. To allow a smooth way to set and update themes, themes snapshots can be saved to json files using the function saveThemeToJson(theme) and can be loaded from json files using the function loadThemeFromJson(jsonFile). In order to define a theme as the current default, the function useTheme(theme) needs to be called.

A shiny app has been created to tune Theme objects live and save them as json files. With this app, it becomes quite easy to create one's own theme with a few clicks. To call for the shiny app, users only needed to run the function runThemeMaker().

Additionally, a few predefined themes are available :

list.files(system.file("themes", package = "tlf"))

These predefined themes can be directly loaded and used through functions named use<ThemeName>Theme(). For instance, the function useMatlabTheme() will set default plot configurations for creating plots looking like Matlab figures.

7. Exporting/Saving a plot

The function exportPlot is a wrapper around the function ggsave that uses the properties of the field export in PlotConfiguration objects when saving a plot as a file.

Since ggsave uses the full plot area as the plot dimensions to save, big legends can shrink the size of the panel. To prevent such shrinkage, plot dimensions can be updated before using exportPlot with the function updateExportDimensionsForLegend as illustrated below.

scatterLegend <- setLegendPosition(scatter1, LegendPositions$outsideTop)
# Print properties of plot export
scatterLegend$plotConfiguration$export

updatedScatterLegend <- updateExportDimensionsForLegend(scatterLegend)
# Print properties of plot export
updatedScatterLegend$plotConfiguration$export

Export code to re-create a PlotConfiguration object

The function exportPlotConfigurationCode(plotConfiguration, name) creates character strings corresponding to commented R code that allows you to re-create a PlotConfiguration object.

# Create and export a plot confiugration
plotConfigurationToExport1 <- PlotConfiguration$new()
exportPlotConfigurationCode(plotConfigurationToExport1)

# Create, update and export a more advanced plot confiugration
plotConfigurationToExport2 <- TornadoPlotConfiguration$new(bar = FALSE)
exportPlotConfigurationCode(plotConfigurationToExport2, name = "tornado")

Since exportPlotConfigurationCode returns character strings, they can either be saved as a .R script or copied/pasted to be used as is or within a function. It is also possible to turn the strings into and expression to eval using parse(text = exportPlotConfigurationCode(plotConfiguration)).

eval(parse(text = exportPlotConfigurationCode(plotConfigurationToExport2, name = "tornado")))
tornado

Open-Systems-Pharmacology/TLF-Library documentation built on Feb. 8, 2025, 11:22 a.m.