[Implemented] Signatures for plotting functions

[IndrajeetPatil]

Related to #674

As noted in the relevant issue, all plotting functions should support the following optional arguments:

• Main title
• x limit
• y limit
• x lin/log
• y lin/log
• x-axis label
• y-axis label
• x unit
• y unit
• legend on/off
• legend position
• for each data set:
  • type (symbols, lines, both)
  • symbol type
  • line type
  • color

This means that the plotting function signatures will be bloated compared to other functions. Is this an issue?

Option-1

Bloated signature but simpler for the users since they won't need to know about the underlying R6 objects from tlf.

plotXYZ <- function(dataCombined,
                    xAxisScale = "lin",
                    yAxisScale = "lin",
                    xLimit = NULL,
                    yLimit = NULL,
                    xUnit = NULL,
                    yUnit = NULL,
                    title = NULL,
                    subtitle = NULL,
                    xLabel = NULL,
                    yLabel = NULL,
                    legendTitle = NULL,
                    legendPosition = NULL,
                    tlfTheme = NULL) {
                             ...
}

Option-2

An alternative would be to have a simpler signature. Here, we would expect the users to enter PlotConfiguration object that contains most of these needed details.

plotXYZ <- function(dataCombined,
                    plotConfiguration,
                    xUnit = NULL,
                    yUnit = NULL,
                    tlfTheme = NULL) {
                             ...
}

But this means that the users will need to know all about the following plot configuration classes:

BoxWhiskerPlotConfiguration, DDIRatioPlotConfiguration, HistogramPlotConfiguration, ObsVsPredPlotConfiguration, PKRatioPlotConfiguration, TimeProfilePlotConfiguration, TornadoPlotConfiguration

And also about the classes that constructors for these classes themselves rely upon:

BackgroundConfiguration, Scaling, xAxis, XAxisConfiguration, YAxisConfiguration, etc.

That's a big price to pay (for the users) just so that we can have a simpler signature!

In other words, there's no such thing as a free lunch.

What should we be doing here?

[PavelBal]

I favor a PlotConfiguration object, especially as it can be re-used for different plots.

I would propose a superclass of PlotConfiguration and sub-classes for the different functions, e.g. for predictedVsObserved it would have an additional parameter foldDistances, for plotPopulationTimeProfile it would have an additional paramter populationQuantiles etc. These parameters for example are not required for plotIndividualTimeProfile.

To create a PlotConfiguration, we could provide functions like defaultIndividualPlotConfiguration, defaultPopulationPlotConfiguration etc. Also the user does not have to provide a default configuration, only if he wants to change something.

I would e.g. create my default configuration and the use it every time I create a figure.

[IndrajeetPatil]

tlf already provides plot configuration objects specialized for each kind of plot:

I would argue that we should be adding additional parameters to the respective tlf objects rather than creating our own default* classes around them because these will become just pass-through classes/methods.

[IndrajeetPatil]

@Yuri05, @msevestre Any thoughts?

[IndrajeetPatil]

Mental model for me to work off of (thanks to MS):

[PavelBal]

List of parameters we want to expose to the users (might be extended):

All plots:

• Main title
• xLim
• yLim
• xlin/xlog
• xLabel
• yLabel
• showLegend TRUE/FALSE
• legend position
• pointsize
• Text size
• For each data set:
  • line
  • line type
  • symbol
  • color

IndividualTimeProfile:

• xUnit
• yUnit

PopulationTimeProfile:

• xUnit
• yUnit
• aggregationType
  • quantiles = c(0.05, 0.5, 0.95)? = min, mid, max

SimulatedVsObs:

xUnit = yUnit
foldDistance (more than one allowed)

ResidualsVsTime:

• xUnit

Multipannel combination (grid)

• Maybe a wrapper that allows to a) combine multiple plots to a multi-pannel plot and b) export to file?
• nrOfCols
• output - default device, png, pdf
• output file name (= main title?)
• output folder
• width
• height
• resolution

[IndrajeetPatil]

After discussing the current implementation with @pchelle, I have realized two important things:

• most of the parameters for the plot config constructor can already be handled by theme JSON
• some parameters (the ones to change properties of lines, points, ribbons, and error bars) won't actually work, so we can't have them as parameters

The only ones that can't be specified in the theme are the following:

    title = NULL,
    subtitle = NULL,
    xlabel = NULL,
    ylabel = NULL,
    legendTitle = NULL,
    xAxisTicks = NULL,
    xAxisTickLabels = NULL,
    yAxisTicks = NULL,
    yAxisTickLabels = NULL,

Out of these, I would argue that it's not necessary for users to have the ability to change the number of ticks on the axes and their labels. So, if we discount them, we are just left with the following:

    title = NULL,
    subtitle = NULL,
    xlabel = NULL,
    ylabel = NULL,
    legendTitle = NULL,

So now we go back to the original question: Which of these is better?

Option-1

Most of the other parameters are specified by the theme:

plotXYZ <- function(dataCombined,
                    title = NULL,
                    subtitle = NULL,
                    xLabel = NULL,
                    yLabel = NULL,
                    legendTitle = NULL,
                    xUnit = NULL,
                    yUnit = NULL,
                    plotSpecificParameter = NULL,
                    tlfTheme = NULL) {
                             ...
}

Option-2

Most of the other parameters are specified by the theme, and the ones that aren't specified by the theme are specified in plotConfiguration. But users need to learn about this new class, in addition to learning about how to change tlf themes.

plotXYZ <- function(dataCombined,
                    plotConfiguration,
                    xUnit = NULL,
                    yUnit = NULL,
                    plotSpecificParameter = NULL,
                    tlfTheme = NULL) {
                             ...
}

Option-3

Most of the parameters are specified by the plotConfiguration, and we no longer use theme. This is not ideal since changing aesthetic properties of the points, ribbons, errors bars, and lines can't be specified in the plot config class, so users lose access to a lot of modifications. Plus, tlf already has existing, user-friendly infrastructure to create theme objects, which we can rely on.

plotXYZ <- function(dataCombined,
                    plotConfiguration,
                    xUnit = NULL,
                    yUnit = NULL,
                    plotSpecificParameter = NULL) {
                             ...
}

In my view, the Option 1 now becomes the most appealing because users don't need to learn - and we don't need to create and maintain - a whole new class just to specify the plot labels. But they will need to learn how to change the theme, if they want to change the look of the plot.

What do you think, @msevestre, @Yuri05, @PavelBal, @StephanSchaller?

[PavelBal]

I would stick to implementing PlotConfiguration as a separate class, without exposure to tlf themes. For me it is a matter of re-usability - I create one object of the PlotConfiguration and re-use it.

I don't see a problem to "learn" about this new class (as it is actually very simple for the user).

[Yuri05]

I agree with Pavel, would also prefer having the PlotConfig as parameter rather than the tlfTheme.
What I would not use in any case is Option 2 (having both plotConfig and tlfTheme at the same time is highly confusing - both describe plot configurations and it's not clear how they interact)
So I would go with the Option 3.

Additionally, we could provide a possibility to create a plot Configuration from a theme
(e.g. plotConfig = createPlotConfigurationFromTheme(pathToTlfThemeFile))

And maybe even something like CreateDefaultPlotConfiguration() - which internally would just call createPlotConfigurationFromTheme(system.file("themes", "ospsuiteTLFTheme.json", package="ospsuite"))

P.S. what does the argument plotSpecificParameter mean?

[IndrajeetPatil]

I have already reverted all of these changes and the implementation now relies on the tlf theme.

having both plotConfig and tlfTheme at the same time is highly confusing

Yes, agreed. The solution now is to call plotConfig something like plotLabelConfiguration, becuase it is being used only to set plot labels.

So:

• tlfTheme: sets up plot configuration
• plotLabelConfiguration: sets up plot labels

Shouldn't cause any confusion.

[IndrajeetPatil]

In other words, we would be going for Option 2:

plotXYZ <- function(dataCombined,
                    tlfTheme = NULL,
                    plotLabelConfiguration = NULL,
                    plotSpecificParameter = NULL,
                    xUnit = NULL,
                    yUnit = NULL) {
                             ...
}

[IndrajeetPatil]

P.S. what does the argument plotSpecificParameter mean?

Will vary from plot to plot.

For example, for observed versus predicted plots, this can be smoother = NULL.

[Yuri05]

Will vary from plot to plot.

Ah, ok, thx. I thought that every plot function would becaome an argument named "plotSpecificParameter" and was wondering what that means - but now I understand

[PavelBal]

In other words, we would be going for Option 2:

No, as discussed, we want to have a PlotConfiguration that exposes the parameters we want to have without having to deal with TLF.

Units are also definitely a part of PlotConfiguration.

[Yuri05]

I have already reverted all of these changes and the implementation now relies on the tlf theme.

Hmm, that was not what I have in mind. For me, a theme is a set of defaults.
With a good set of defaults, most of them can be kept AS IS, but if the user wants to change any of them - it should be possible to do it programmatically, without a need to create a new theme for this.

So I would prefer to

• keep all the properties of lines, symbols, legends, ... in the PlotConfig object
• provide additional possibility to create/initialize a PlotConfig object from a theme
• provide the default plot configuration as described above (=create PlotConfig from the default theme)
• and then define plot functions e.g. as

plotXYZ <- function(dataCombined,
                    plotConfiguration = DefaultPlotConfiguration(),
                    xUnit = NULL,
                    yUnit = NULL,
                    plotSpecificParameter = NULL)

Then the easiest way to call the plot function would be to use ALL the defaults, e.g.
plotTimeProfile(dataCombined, xUnit="h", yUnit="mg/ml")

If I need some plot config settings different from the default:

plotConfig = DefaultPlotConfiguration() # or: plotConfig = CreatePlotConfiguration("C:/myTheme.json")
plotConfig$legendCaptionSize = 10
plotConfig$watermark = "DRAFT"
...
plotTimeProfile(dataCombined, plotConfiguration = plotConfig, xUnit="h", yUnit="mg/ml")

[IndrajeetPatil]

keep all the properties of lines, symbols, legends, ... in the PlotConfig object

We should have a meeting to discuss this further when @pchelle is also present because I have no idea how to get OSP plot configuration object to set these plot properties. This is what I have been doing so far, and the plots looked completely mangled, and Pierre told me that this is to be expected.

For example, if I use ospPlotConfiguration object fields to create a new TLF object internally

linesConfiguration <- tlf::ThemeAestheticSelections$new(
    color = ospPlotConfiguration$linesColor,
    fill = ospPlotConfiguration$linesFill,
    shape = ospPlotConfiguration$linesShape,
    size = ospPlotConfiguration$linesSize,
    linetype = ospPlotConfiguration$linesLinetype,
    alpha = ospPlotConfiguration$linesAlpha
  )

and then assign it to the respective plot configuration object needed by the given plot

individualTimeProfilePlotConfiguration <- tlf::TimeProfilePlotConfiguration$new()
individualTimeProfilePlotConfiguration$lines <- ospInternalPlotConfiguration$lines

It does NOT work.

Or that's my understanding based on my conversation with Pierre, and based on what I saw using this set up to create a concentration profile plot. All the default aesthetic properties set by tlf are completely removed.

provide additional possibility to create/initialize a PlotConfig object from a theme

More and more, I agree with Juri that this functionality should live in tlf and be re-exported from ospsuite.

[IndrajeetPatil]

In #871, I have restored the old plot configuration with all the parameters, here is what the concentration profile plot looks like with the plot config defaults (doesn't matter whether a theme is specified or not):

What it is supposed to look like with TLF defaults (ignore watermark):

[msevestre]

some parameters (the ones to change properties of lines, points, ribbons, and error bars) won't actually work, so we can't have them as parameters

I don't understand this. Why do we have parameters that we cannot set ? Or where those parameters that you thought existed in tlf but are not directly accessible?

[msevestre]

beautiful

[IndrajeetPatil]

Alright, as can be seen in #871, the new function signature is

plotIndividualTimeProfile(dataCombined, defaultPlotConfiguration = DefaultPlotConfiguration$new())

So the only required argument is dataCombined, everything else will be initialized to have the chosen defaults.

I've also chosen the defaults, and plots now do look as expected, but there are still a few wrinkles left to be ironed out.

[msevestre]

plotIndividualTimeProfile(dataCombined, defaultPlotConfiguration = DefaultPlotConfiguration$new())

Wouldn't it be more consistent with the rest of the code to default to defaultPlotConfiguration =NULL and create in the code if NULL?
This is what we do everywhere else and seems to be also more consistent with what I see from other signatures in general

[IndrajeetPatil]

Done!

It's now:

plotIndividualTimeProfile(dataCombined, defaultPlotConfiguration = NULL)

[IndrajeetPatil]

Output with the defaults look good now (cf. #871 (comment)):

plotIndividualTimeProfile(myDataCombinedObject)

h/t @pchelle for chaperoning this.

[msevestre]

Axis captions (Time, Fraction) are very black and bold. Can we soften that a bit?

[StephanSchaller]

I like it as is, but would not object to Michaels suggestion (but really only a bit lighter)