# Plotting with unigd

The following guide walks through the basic features of `unigd` and compares them with the plot rendering methods in base R.

## 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))))

### Paging (by index)

The `page` parameter lets you select which plot should from the history should be rendered. By default this is set to `0` which will use the last created plot. Set this to any number ≥ 1 to select a plot by it’s index (oldest first). Use numbers ≤ 0 to select plots newest-first:

    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()

Note that plots can be deleted from the history the same way:

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

Instead of keeping track of the plot index, which might change when plots are added and removed, static plot IDs can be obtained.

### Plot IDs

If you want to render a plot at a later point without having to keep track of its index, you can obtain its ID at any point after it’s creation.

The following example extensively demonstrates how this can be used:

    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()

Note that a typical use-case would be much simpler, and just be getting the last ID after each plot by calling `ugd_id()` subsequently.

### (Special) renderers

`unigd` also ships with a number of ‘special’ renderers. This guide will not go into too much detail about this topic but here are some noteworthy mentions:

- `"strings"`-renderer
  - All text elements inside a plot
  - Linebreak separated plain text format
  - Could be used to e.g. ‘search’ through plots
- `"meta"`-renderer
  - Meta information about the plot
  - Guaranteed to have a render time of O(1) regardless of number of objects
  - Includes complexity (number of draw calls and clipping planes)
  - JSON format
- `"json"`-renderer
  - Contains all information `unigd` has about one plot
  - JSON format

## 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).