---
title: "Loon in RMarkdown"
author: "R.W. Oldford"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Loon in RMarkdown}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
  %\VignetteDepends{grid, gridExtra, png}
  
---


```{r setup, include=FALSE}
knitr::opts_chunk$set(
    echo = TRUE, 
    tidy.opts = list(width.cutoff = 65),
    tidy = TRUE)

set.seed(12314159)

imageDirectory <- "./images/loonRmarkdown"
dataDirectory <- "data"
path_concat <- function(path1, path2, sep="/") {paste(path1, path2, sep = sep)}
```
# Loon plots

Start by accessing `loon`

```{r loon, message = FALSE}
library(loon)
```

Plots in `loon` are dynamic and interactive.  Their display contents can be changed either through direct manipulation and the loon inspector, or programmatically.  To interact with them programmatically (including transferring them to `grid` graphics objects), it is best to assign them to a variable at creation.

For example,

```{r iris l_plot, message = FALSE}
p <- l_plot(x = iris$Sepal.Width, y = iris$Sepal.Length, 
            color = iris$Species, 
            xlabel = "sepal width", ylabel = "sepal length",
            title = "The famous Iris data", 
            showGuides = TRUE)
```


## Just `plot` the `loon` plot!

This can now be printed and embedded in the document at any time using the `plot()` function as in

```{r plot l_plot, out.width = "60%", fig.align = "center", fig.width = 6, fig.height = 5}
gp <- plot(p)
gp
```

In addition to displaying the plot as a `grid` graphic, the value of  `plot(p)` is saved by setting it to the variable `gp`.  The value is a very rich data structure (a `gtree`) which can now be used as any other `grid` graphics object (or `grob`).  Note that the display could have been suppressed at this time simply as follows:

```{r plot no draw l_plot, out.width = "60%", fig.align = "center", fig.width = 6, fig.height = 5}
gp <- plot(p, draw = FALSE)
gp
```

Either way, `gp` is a `grid` data structure that can be manipulated as any other `grob`.  Try `grid::grid.ls(gp)` or in RStudio `View(gp)` to examine the full data structure.

See `plot.loon`, `grid.loon`, and `loonGrob` for more details on transferring a `loon` plot to a `grid` graphics object.

## Exporting to an image file

Being a `grid` graphics object, `gp` could also be exported to an image file of some kind using any of a variety of graphics devices (e.g. see `?png`) or perhaps via RStudio's "Export" plot functionality (to a "png" or "pdf" format).

For example, we could save `gp` as a ".png" file by drawing it using the `png()` device and `grid.draw()` from the `grid` graphics package.

```{r gp png loon, eval = FALSE, message = FALSE, warning = FALSE, error = FALSE}
png(filename = "images/loonplot1.png", width = 600, height = 500)
grid::grid.draw(gp)
dev.off()
```

The plot is now saved as a "png" file "loonplot1.png" in the "images" sub-directory of the current directory "." (you could save it into any existing directory you choose and for which you have write privileges). 
Alternatively, if `gp` was not saved then `plot(p)` could have been used in place of the `grid::grid.draw(gp)` line above.

Once saved, this external image can be embedded in the document using `knitr::include_graphics()` as

```{r knitr png, eval = FALSE, out.width = "60%", fig.align = "center", fig.width = 6, fig.height = 5}
knitr::include_graphics("images/loonplot1.png")
```

```{r knitr png real, echo = FALSE, out.width = "60%", fig.align = "center", fig.width = 6, fig.height = 5}
knitr::include_graphics(path_concat(imageDirectory, "loonplot1.png"))
```

which will look slightly different because of the transfer of the grid graphic to "png"

Instead of `knitr`, the same result (at least for `pdf` output documents) could be produced using the command `\includegraphics` from the LaTeX package `graphicx`.
\begin{verbatim}
  \begin{center}
    \includegraphics[width = 0.6\textwidth]{images/loonplot1.png}
  \end{center}
\end{verbatim}

  \begin{center}
    \includegraphics[width = 0.6\textwidth]{images/loonRMarkdown/loonplot1.png}
  \end{center}

One advantage of LaTeX over `knitr` commands is the control it allows over the display, especially of multiple plots.  The disadvantage is that results might vary if the output is not a "pdf" file (e.g. an "html" file).

See also the `png` package.


## Multiple views of a loon plot

Sometimes, there will be changes made to a single loon plot which you would like to capture in your document.

This might have been done interactively through direct manipulation, or programmatically.

### Plots from programmatic manipulation

```{r multiple loon plots, eval = TRUE, out.width = "60%", fig.align = "center", fig.width = 6, fig.height = 5}
saveTitle <- p["title"]

p['title'] <- "1. Setosa selected"
p['selected'] <- iris$Species == "setosa"
gp_select <- plot(p, draw = FALSE)

p['title'] <- "2. Scale to the selected points"
l_scaleto_selected(p)
gp_select_zoom <- plot(p, draw = FALSE)

p['title'] <- "3. Turn off selection"
p['selected'] <- FALSE
gp_setosa_zoom <- plot(p, draw = FALSE)

# Put the plot back to how it was originally
p["title"] <- saveTitle 
l_scaleto_plot(p)
```

We now have three more "snapshots" of our interaction with the `loon` plot  `p`.

We can now use the `gridExtra` package to arrange these in a single display.

```{r gridExtra multiple loon plots, message = FALSE, out.width = "100%", fig.align = "center", fig.width = 12, fig.height = 10}
library(gridExtra)
# which can now be arranged in sequence
grid.arrange(gp, gp_select, gp_select_zoom, gp_setosa_zoom)
```

### Plots from saved exported images

Alternatively, all plots might have been developed through direct manipulation.  
Any time a snapshot of the current plot is desired, it is simply turned to a `grid` object via `plot(p)` and saved as an external images (e.g. say as a `png` file) through the `png()` device, or the perhaps via RStudio's export as "png" files.  (N.B. Here we do it programmatically only to save the files.)

```{r save many pngs, eval = FALSE, echo=TRUE, message = FALSE, warning = FALSE, error = FALSE}
png(filename = "images/loonplot2.png", width = 600, height = 500)
grid::grid.draw(gp_select)
dev.off()
png(filename = "images/loonplot3.png", width = 600, height = 500)
grid::grid.draw(gp_select_zoom)
dev.off()
png(filename = "images/loonplot4.png", width = 600, height = 500)
grid::grid.draw(gp_setosa_zoom)
dev.off()
```


For example, had the previous plots been saved as `"loonplot2.png"`, `"loonplot3.png"`, and `"loonplot4.png"` then `knitr` could produce them in sequence as before but now using `fig.show = "hold"` in the header for the following `R` segment:

```{r knitr several,  eval = FALSE, out.width = "60%", fig.align = "center", fig.width = 6, fig.height = 5, fig.show = "hold"}
knitr::include_graphics(path = "images/loonplot1.png")
knitr::include_graphics(path = "images/loonplot2.png")
knitr::include_graphics(path = "images/loonplot3.png")
knitr::include_graphics(path = "images/loonplot4.png")
```

```{r real knitr several,  echo = TRUE, out.width = "60%", fig.align = "center", fig.width = 6, fig.height = 5, fig.show = "hold"}
knitr::include_graphics(path = path_concat(imageDirectory, "loonplot1.png"))
knitr::include_graphics(path = path_concat(imageDirectory, "loonplot2.png"))
knitr::include_graphics(path = path_concat(imageDirectory, "loonplot3.png"))
knitr::include_graphics(path = path_concat(imageDirectory, "loonplot4.png"))
```

More layout control is available using `grid` graphics functions `as.raster()` and `rasterGrob()`, the function `grid.arrange()` from the `gridExtra` package, and `readPNG()` from the `png` package.

```{r grid raster funs and png package, eval = FALSE, message = FALSE, warning = FALSE, error = FALSE, out.width = "100%", fig.align = "center", fig.width = 12, fig.height = 10}
library(grid)
library(gridExtra)
library(png)

img <- as.raster(readPNG(source = "images/loonplot1.png"))
gp <- rasterGrob(img)

img <- as.raster(readPNG(source = "images/loonplot2.png"))
gp_select <- rasterGrob(img)

img <- as.raster(readPNG(source = "images/loonplot3.png"))
gp_select_zoom <- rasterGrob(img)

img <- as.raster(readPNG(source = "images/loonplot4.png"))
gp_setosa_zoom <- rasterGrob(img)

grid.arrange(gp, gp_select, gp_select_zoom, gp_setosa_zoom)
```


```{r real grid raster funs and png package, echo = FALSE, message = FALSE, warning = FALSE, error = FALSE, out.width = "100%", fig.align = "center", fig.width = 12, fig.height = 10}
library(grid)
library(gridExtra)
library(png)

img <- as.raster(readPNG(source = path_concat(imageDirectory, "loonplot1.png")))
gp <- rasterGrob(img)

img <- as.raster(readPNG(source = path_concat(imageDirectory, "loonplot2.png")))
gp_select <- rasterGrob(img)

img <- as.raster(readPNG(source = path_concat(imageDirectory, "loonplot3.png")))
gp_select_zoom <- rasterGrob(img)

img <- as.raster(readPNG(source = path_concat(imageDirectory, "loonplot4.png")))
gp_setosa_zoom <- rasterGrob(img)

grid.arrange(gp, gp_select, gp_select_zoom, gp_setosa_zoom)
```
Alternatively,  LaTeX commands (like `tabular` layouts) could be used lay out the images.

See also `ggsave` in `grid`.

```{r, echo = FALSE)
rm(p)
```}
