Comparer syntax and reasoning

Most of the arguments to plot_outcomes() are relatively straightforward, and control the basic look of the plot. A few, however, are unusual and permit important but quite complex behaviour. They are briefly outlined here, with links to where their use is demonstrated more fulsomely.

Colour/color

Despite being written primarily for Australian uses, the functions here use American ‘color’ spelling for arguments. Where functions (e.g. plot_data_prep(), as_colors()) return dataframes or other objects indicating colour, those also use American spelling. This is because colour handling and plotting has a number of external dependencies that use and expect American spelling.

outcome_col

A key difference between plot_outcomes() and more typical plotting functions, e.g. ggplot() is the use of the outcome_col argument. This treats the outcome of interest as a special value, which may need data processing to occur (baselining, scaling, etc), as it is fundamentally the value of interest, wherever it gets plotted. It allows that processing to occur consistently to that column whether it is plotted on the y-axis (e.g. bars or points and lines) or as colour in maps or heatmaps. The placement of this outcome_col is then controlled by plot_type, which is "2d" by default and puts it on x, but also might be heatmap or map, which makes it a colour.

Consistent limits

We often need to control limits for visual consistency across plots or to ensure things like midpoints of colour ramps are appropriate. The setLimits argument allows us to do all of those for the values in outcome_col. It behaves differently depending on length, making it worth for setting ranges but also e.g. midpoints of diverging axes. In addition, it is used internally when data is baselined to set appropriate breaks (especially for diverging colour ramps, see maps example).

List-arguments for complex plots

Maps in particular can have under- and overlays, and so we use the underlay_list and overlay_list lists to specify how this works, with much more detail and examples in the maps demonstration.

Smoothers and contours are both fitting functions, which may need additional arguments. These can be provided through the smooth_arglist and contour_arglist respectively, with demonstration in line plots and heatmaps.

The base_list argument takes a list of arguments that get passed to baseline_compare(), allowing baselining to happen internally to plot_outcomes() and so avoiding carrying around extra dataframes of compared data. See the hydrographs for examples.

Grouped colours

Sometimes we might want to specify different palettes for different groups, so that we can distinguish both large groupings and the subsidiary parts. we use the pal_list as a list for this, in conjunction with colorgroups. See the bar example and causal networks.