Plotting with unigd

Plot rendering in base R

Rendering a plot in base R is done by (1) starting a graphics device, (2) calling some plot functions and subsequently (3) closing the device:

temp <- airquality$Temp                         # Fetch some data

png(file="my_plot1.png", width=600, height=400) # (1) Start the 'png' device
hist(temp, col="darkblue")                      # (2) Plot a histogram
dev.off()                                       # (3) Close the device

Note that this has some unfortunate constraints:

• Rendering information must be specified before the plot is created
  • File format (png(), pdf(), svg(), …)
  • Filepath (i.e.: file="my_plot1.png")
  • Dimensions (i.e.: width=600, height=400)
• There is no way (without re-running the plotting code) to render the plot…
  • …in multiple formats.
  • …in multiple dimensions.
• No easy way to access the plotting data without writing to a file first.
• Closing the device with dev.off() must be called every time.

unigd solves these issues by employing a different graphics device architecture.

Plot rendering with unigd

Let’s see how the same render can be created using unigd:

library(unigd)
temp <- airquality$Temp                              # Fetch some data

ugd()                                                # (1) Start the 'ugd' device
hist(temp, col="darkblue")                           # (2) Plot a histogram
ugd_save(file="my_plot1.png", width=600, height=400) # Render 600*400 PNG file
dev.off()                                            # (3) Close the device

Notice how rendering is an explicit instruction after plotting when using unigd. This way we can also render the same plot to multiple formats and/or dimensions:

# ...
hist(temp, col="darkblue")
ugd_save(file="my_plot1.png", width=600, height=400) # Render 600*400 PNG file
ugd_save(file="my_plot2.pdf", width=300, height=300) # Render 300*300 PDF file
# ...

Starting and closing a device can be cumbersome, especially if the plotting code aborts after an error and leaves the device open. For this reason unigd comes with a set of functions called ugd_*_inline:

library(unigd)
temp <- airquality$Temp # Fetch some data

ugd_save_inline({
  hist(temp, col="darkblue")
}, file="my_plot1.png", width=600, height=400)

Plotting this way keeps you from having to create and close a device manually. Depending on your personal preference this may also be considered as more ‘readable’ code.

You can obtain the full list of included renderers with ugd_renderers(). (It’s growing with every unigd update!)

The next section will illustrate how to access the render data directly without having to create a file.

In-memory render access

For some applications, you might want to access the rendered data directly. Example use-cases for this might be report generation, web services or interactive applications. While you can most likely think of workarounds for this issue, this unigd feature will certainly lower code complexity and increase performance.

Rendering in-memory is done by simply calling ugd_render(...) instead of ugd_save(...):

temp <- airquality$Temp

ugd()
hist(temp, col="darkblue")
my_svg <- ugd_render(as="svg")
dev.off()

cat(my_svg) # Print the SVG as a string

Of course there is also a inline function for this:

temp <- airquality$Temp

my_svg <- ugd_render_inline({
  hist(temp, col="darkblue")
}, as="svg")

cat(my_svg) # Print the SVG as a string

More unigd features

unigd offers a number of features which go beyond the base R graphics devices.

Zoom

All rendering function in unigd offer a zoom parameter. This parameter can be used to increase (or decrease) the size of objects inside a plot (independently of plot dimensions). For example zoom=2 will increase the size of all objects to 200%, zoom=0.5 will decrease them to 50%.

my_svg_1_0 <- ugd_render_inline({
  hist(temp, col="darkblue", main = "Zoom 1.0")
}, as="png-base64", width=300, height=300, zoom=1.0)

my_svg_1_5 <- ugd_render_inline({
  hist(temp, col="darkblue", main = "Zoom 1.5")
}, as="png-base64", width=300, height=300, zoom=1.5)

my_svg_0_5 <- ugd_render_inline({
  hist(temp, col="darkblue", main = "Zoom 0.5")
}, as="png-base64", width=300, height=300, zoom=0.5)

# (Output directly in this RMarkdown document)
knitr::raw_html(paste0(sprintf("<img src=\"%s\" />", c(my_svg_1_0, my_svg_1_5, my_svg_0_5))))

ugd()
for (i in 1:10) {
  plot(1, main=paste0("Plot #", i))
}

ugd_save(file="plot.png", page = 3)  # Plot #3
ugd_save(file="plot.png")            # Plot #10
ugd_save(file="plot.png", page = -1) # Plot #9

dev.off() 

# ...
ugd_remove()          # Remove last
ugd_remove(page = -1) # Remove second-to-last
ugd_clear()           # Remove all
# ...

ugd()

plot(rnorm(50))           # A

first_plot_id <- ugd_id() # Get last ID (A at this point)

hist(rnorm(50))           # B

plot(sin((1:100)/3))      # C

other_id <- ugd_id(-1)    # Get the second-to-last ID (B at this point)

hist(runif(100))          # D

ugd_remove(3)             # Remove 3rd plot (C)

first_again <- ugd_id(1)  # Get the first ID (A)

ugd_save(file="plot_1.png", page = first_plot_id)
ugd_save(file="plot_2.png", page = other_id)
ugd_save(file="plot_3.png", page = first_again)

dev.off() 

Performance considerations

While unigd aims to provide the best performance in any case, there are some considerations you can make when optimizing graphics rendering.

At this point it should be mentioned that for most user applications readability should be prioritized over performance and, unless graphics rendering is bottlenecking your R script, you can most likely ignore this section in good conscience.

When optimizing rendering code, it is fundamental to understand in what cases unigd needs to call into the R graphics engine to let a plot be re-drawn:

Rendering is done after drawing. The last drawn dimensions of a plot are cached. We can derive a few simple rules from this:

• Rendering the same plot in different formats: Fast.
• Rendering the same plot in different dimensions: Slow(er).

This means ordering the rendering calls will result in faster execution:

# SLOWER:
ugd_save(file="my_plot1.png", width=600, height=400)
ugd_save(file="my_plot2.pdf", width=300, height=300) # re-draw 1
ugd_save(file="my_plot3.pdf", width=600, height=400) # re-draw 2

# FASTER:
ugd_save(file="my_plot1.png", width=600, height=400)
ugd_save(file="my_plot3.pdf", width=600, height=400)
ugd_save(file="my_plot2.pdf", width=300, height=300) # re-draw 1

And, while unigd gives you the choice of specifying your render dimension after plotting, you can hint them at device creation time to achieve the best performance:

# SLOWER:
ugd() # default dimensions: 720 * 576
# ...
ugd_save(file="my_plot1.png", width=300, height=300) # re-draw

# FASTER:
ugd(width=300, height=300)
# ...
ugd_save(file="my_plot1.png", width=300, height=300)

If the dimensions are omitted when calling rendering functions, the last known dimensions will be used and rendering is guaranteed to be fast:

ugd_save(file="my_plot1.png")

Any use of ugd_*_inline functions is also guaranteed to be fast.

Note that width and height also interact with the zoom parameter. (i.e.: Cached width = width / zoom).