Advanced Data Visualisation with R

.info-box.w-60.bg-white[
These slides are viewed best by Chrome or Firefox and occasionally need to be refreshed if elements did not load properly. See <a href=day1-session1.pdf>here for the PDF <i class="fas fa-file-pdf"></i></a>. 
]

<br>

---

# .monash-blue[Advanced Data Visualisation with R]

<br>

<h2 style="font-weight:900!important;">R Graphics using `grid`</h2>

.bottom_abs.width100[

Instructor: *Emi Tanaka*

<i class="fas fa-envelope"></i>  emi.tanaka@monash.edu

<i class="fas fa-calendar-alt"></i> 8th Dec 2021 @ Statistical Society of Australia Canberra Branch | Zoom

<br>

]

---

# <i class="fab fa-r-project"></i> *Graphics*

---

# R graphics system

---

# Base graphics

---

# `ggplot` graphics

---

# Graphics model in R

* There are two main **graphics models** in R

## Base `graphics`
<br>`library(graphics)`<br> .f5[(typically already loaded)]<br><br>
<img src="images/painting.jpg" width="60%" class="ba">
]
.w-50.center[

{{content}}
]
]

## `grid` graphics

`library(grid)`

<img src="images/animator.jpg" width="240px" class="ba">  
{{content}}
--

<img src="images/printer.svg" width="86px"> 
{{content}}
--

---

# .monash-white[`grid`]

---

# `grid` R-package

* The `grid` package contains the low-level functions to create, manipulate and <br>draw **gr**aphical **ob**jects (grob).
--

* The `grid` package is a **base package** and so is included in standard R installations

```r
*packageDescription("grid")
```

```
Package: grid
Version: 4.1.2
Priority: base
Title: The Grid Graphics Package
Author: Paul Murrell <paul@stat.auckland.ac.nz>
Maintainer: R Core Team <do-use-Contact-address@r-project.org>
Contact: R-help mailing list <r-help@r-project.org>
Description: A rewrite of the graphics layout capabilities, plus some
        support for interaction.
Imports: grDevices, utils
License: Part of R 4.1.2
NeedsCompilation: yes
Built: R 4.1.2; x86_64-apple-darwin17.0; 2021-11-01 20:58:55 UTC; unix

-- File: /Library/Frameworks/R.framework/Versions/4.1/Resources/library/grid/Meta/package.rds 
```
]

---

# Graphical objects a.k.a. "Grobs"

* The base packages `stats`, `utils`, `datasets`, `methods`, `base`, `graphics` and **`grDevices`** are automatically loaded in a standard launch of R.

```r
library(grid)
```

.flex.mt3[
.w-50.pr2[

```r
grid.circle()
```

]
.w-50[
{{content}}
]
]

```r
circleGrob()
```

```
## circle[GRID.circle.94]
```
{{content}}

```r
grid.draw(circleGrob())
```

---

# Graphical primitives in `grid`

.flex.mt3[
.w-20.center.mr3[
.ba[
<img src="images/day1-session1/grid-primitives-1.png" class="primitive">  
`grid.lines()`  
`linesGrob()`
]]
.w-20.center.mr3[
.ba[
<img src="images/day1-session1/grid-primitives-2.png" class="primitive">  
`grid.polyline()`  
`polylineGrob()`
]]
.w-20.center.mr3[
.ba[
<img src="images/day1-session1/grid-primitives-3.png" class="primitive">  
`grid.segments()`
`segmentsGrob()` 
]]
.w-20.center.mr3[
.ba[
<img src="images/day1-session1/grid-primitives-4.png" class="primitive">  
`grid.xspline()`  
`xsplineGrob()`
]]
.w-20.center[
.ba[
<img src="images/day1-session1/grid-primitives-5.png" class="primitive">  
`grid.bezier()`  
`bezierGrob()`
]]
]
.flex.mt3[

.w-20.center.mr3[
.ba[
<img src="images/day1-session1/grid-primitives-11.png" class="primitive">  
`grid.text()`  
`textGrob()`
]]
.w-20.center.mr3[
.ba[
<img src="images/day1-session1/grid-primitives-12.png" class="primitive">  
`grid.raster()`  
`rasterGrob()`
]]
.w-20.center.mr3[
.ba[
<img src="images/day1-session1/grid-primitives-8.png" class="primitive">  
`grid.circle()`  
`circleGrob()`
]]
.w-20.center.mr3[
.ba[
<img src="images/day1-session1/grid-primitives-9.png" class="primitive">  
`grid.polygon()`  
`polygonGrob()`
]]
.w-20.center[
.ba[
<img src="images/day1-session1/grid-primitives-10.png" class="primitive">  
`grid.path()`  
`pathGrob()`
]]
]

.flex.mt3[

.w-20.center.mr3[
.ba[
<img src="images/day1-session1/grid-primitives-13.png" class="primitive">  
`grid.curve()`  
`curveGrob()`
]]
.w-20.center.mr3[
.ba[
<img src="images/day1-session1/grid-primitives-14.png" class="primitive">  
`grid.points()` 
`pointsGrob()`
]]
.w-20.center.mr3[
.ba[
<img src="images/day1-session1/grid-primitives-6.png" class="primitive">  
`grid.rect()`  
`rectGrob()`
]]
.w-20.center.mr3[
.ba[
<img src="images/day1-session1/grid-primitives-7.png" class="primitive">  
`grid.roundrect()`  
`roundrectGrob()`
]]
.w-20[
Convention of function names:

`grid.`.monash-red2[`primitive`]`()`  
.monash-red2[`primitive`]`Grob()`
]
]

---

# Higher-level functions

* Most functions in `grid` are low-level functions but *selected number of higher-level functions exist*
* The output of these functions combine multiple graphical primitives

```r
pushViewport(plotViewport())
pushViewport(viewport(xscale = c(0, 100)))
grid.xaxis()
```

---

# Making your own grobs from graphical primitive

```r
shape <- circleGrob(x = 0.5, y = 0.5, r = 0.5, name = "shape")
eyes <- circleGrob(x = c(0.25, 0.75), y = 0.5, r = 0.05, 
                   gp = gpar(fill = "black"), name = "eyes")
mouth <- circleGrob(x = 0.5, y = 0.2, r = 0.1, name = "mouth")
```
--

```r
face1 <- gList(shape, eyes, mouth)
face2 <- grobTree(shape, eyes, mouth, name = "face")
```

.flex.mt2[
.w-20.f4.pr3[

```r
grid.draw(face1)
```

]
.w-20.pr3.f4[

```r
grid.draw(face2)
```

]
.w-20.f4.pr3[

```r
grid.ls(face1)
```

```
## shape
## eyes
## mouth
```

```r
grid.ls(face2)
```

```
## face
##   shape
##   eyes
##   mouth
```

]
.w-40.f4[
{{content}}
]
]

```r
class(face1)
```

```
## [1] "gList"
```

```r
class(face2)
```

```
## [1] "gTree" "grob"  "gDesc"
```

---

# Basic creators of grobs

```r
g1 <- grob(x = unit(0.5, "npc"), 
           y = unit(0.5, "npc"), 
           r = unit(0.5, "npc"), 
           cl = "circle")
grid.draw(g1)
```

<img src="images/day1-session1/grob-1.png" width="144" style="display: block; margin: auto;" />
* You likely won't ever use this approach
]
.w-50[
{{content}}
]
]

* Creating a flexible tree structure with grobs

```r
g2 <- gTree(children = gList(shape, 
                             eyes, 
                             mouth))
grid.draw(g2)
```

* Note: `grobTree(x)` is essentially `gTree(children = x)`

---

# Working with graphical outputs

<br>

Work with output | Work with grobs | Description
--- | --- | ---
`grid.get()` | `getGrob()` | Return a copy of grobs
`grid.edit()` | `editGrob()` | Modifies grobs
`grid.add()` | `addGrob()` | Add a grob
`grid.remove()` | `removeGrob()` | Remove grobs
`grid.set()` | `setGrob()` | Replace grobs

Along with some other helpful functions like :

* `grid.newpage()` to erase current device or move to a new page
* `grid.grep()` to find all matching grobs

---

# Working with graphical outputs in action

```r
grid.ls(face2)
```

```
## face
##   shape
##   eyes
##   mouth
```

```r
grid.draw(removeGrob(face2, "mouth"))
```

<img src="images/day1-session1/face-with-no-mouth-1.png" width="216" style="display: block; margin: auto;" />
]
.w-50[
{{content}}
]
]

```r
xaxis <- xaxisGrob()
```

```r
grid.ls(xaxis)
```

```
## GRID.xaxis.99
```

* This should include primitives?

* The `xaxis` contains no children 
* This is because the tick marks are only drawn when signalled to draw

```r
xaxisf <- grid.force(xaxis)
grid.ls(xaxisf)
```

```
## GRID.xaxis.99
##   major
##   ticks
##   labels
```

---

# Graphical parameters in `grid`

.flex.mt2[
.w-20.center.mr2[
.ba[
<img src="images/day1-session1/gpars-1.png" class="primitive">  
`col`  
color
]]
.w-20.center.mr2[
.ba[
<img src="images/day1-session1/gpars-2.png" class="primitive">  
`fill`  
fill
]]
.w-20.center.mr2[
.ba[
<img src="images/day1-session1/gpars-3.png" class="primitive">  
`alpha`  
opacity
]]
.w-20.center.mr2[
.ba[
<img src="images/day1-session1/gpars-4.png" class="primitive">  
`lwd`  
line width
]]
.w-20.center[
.ba[
<img src="images/day1-session1/gpars-5.png" class="primitive">  
`lex`  
line width expansion
]]

]

.flex.mt2[
.w-20.center.mr2[
.ba[
<img src="images/day1-session1/gpars-6.png" class="primitive">  
`lty`  
line type
]]
.w-20.center.mr2[
.ba[
<img src="images/day1-session1/gpars-7.png" class="primitive">  
`lineend`  
line end style
]]
.w-20.center.mr2[
.ba[
<img src="images/day1-session1/gpars-8.png" class="primitive">  
`linejoin`  
line join style
]]
.w-20.center.mr2[
.ba[
<img src="images/day1-session1/gpars-9.png" class="primitive">  
`linemitre`  
line mitre limit
]]
.w-20[
All graphical primitives have a `gp` argument to parse with `grid::gpar()`

]]

.flex.mt2[
.w-20.center.mr2[
.ba[
<img src="images/day1-session1/gpars-10.png" class="primitive">  
`cex`  
character expansion
]]
.w-20.center.mr2[
.ba[
<img src="images/day1-session1/gpars-11.png" class="primitive">  
`fontsize`  
font size
]]
.w-20.center.mr2[
.ba[
<img src="images/day1-session1/gpars-12.png" class="primitive">  
`fontface`  
font face
]]
.w-20.center.mr2[
.ba[
<img src="images/day1-session1/gpars-13.png" class="primitive">  
`fontfamily`  
font family
]]
.w-20.center[
.ba[
<img src="images/day1-session1/gpars-14.png" class="primitive">  
`lineheight`  
line height
]]

]

---

# Coodinate systems

---

# The canvas

---

# Coordinate systems

<table class=" lightable-classic" style='font-family: "Arial Narrow", "Source Sans Pro", sans-serif; width: auto !important; margin-left: auto; margin-right: auto;'>
 <thead>
  <tr>
   <th style="text-align:left;"> Coordinate system </th>
   <th style="text-align:left;"> Description </th>
  </tr>
 </thead>
<tbody>
  <tr>
   <td style="text-align:left;"> <code class="monash-black f4">"native"</code> </td>
   <td style="text-align:left;"> Relative to the scales of the current viewport </td>
  </tr>
  <tr>
   <td style="text-align:left;"> <code class="monash-black f4">"npc"</code> </td>
   <td style="text-align:left;"> Normalised parent coordinates </td>
  </tr>
  <tr>
   <td style="text-align:left;"> <code class="monash-black f4">"snpc"</code> </td>
   <td style="text-align:left;"> Square normalised parent coordinates </td>
  </tr>
  <tr>
   <td style="text-align:left;"> <code class="monash-black f4">"in"</code>, <code class="monash-black f4">"cm"</code>, <code class="monash-black f4">"mm"</code> </td>
   <td style="text-align:left;"> Physical inches, centimeters, millimeters </td>
  </tr>
  <tr>
   <td style="text-align:left;"> <code class="monash-black f4">"pt"</code>, <code class="monash-black f4">"bigpts"</code>, <code class="monash-black f4">"picas"</code>,<br> <code class="monash-black f4">"dida"</code>, <code class="monash-black f4">"cicero"</code>, <code class="monash-black f4">"scaledpts"</code> </td>
   <td style="text-align:left;"> 72.27 points = 1 inch, 72 big points = 1 inch, 12 points = 1 pica,<br> 1157 dida = 1248 points, 1 cicero = 12 dida, 65536 scaled points = 1 point </td>
  </tr>
  <tr>
   <td style="text-align:left;"> <code class="monash-black f4">"char"</code> </td>
   <td style="text-align:left;"> Multiples of the current font size <span class="f5">(<code class="monash-black f4">fontsize</code> and <code class="monash-black f4">cex</code>)</span> </td>
  </tr>
  <tr>
   <td style="text-align:left;"> <code class="monash-black f4">"line"</code> </td>
   <td style="text-align:left;"> Multiples of the height of a text line <span class="f5">(<code class="monash-black f4">fontsize</code>, <code class="monash-black f4">cex</code> and <code class="monash-black f4">lineheight</code>)</span> </td>
  </tr>
  <tr>
   <td style="text-align:left;"> <code class="monash-black f4">"strwidth"</code>, <code class="monash-black f4">"strheight"</code> </td>
   <td style="text-align:left;"> Multiples of the width/height of a given string <span class="f5">(<code class="monash-black f4">fontsize</code>, <code class="monash-black f4">cex</code>, <code class="monash-black f4">fontfamily</code>, and <code class="monash-black f4">fontface</code>)</span> </td>
  </tr>
  <tr>
   <td style="text-align:left;"> <code class="monash-black f4">"grobx"</code>, <code class="monash-black f4">"groby"</code> </td>
   <td style="text-align:left;"> Multiples of the x- and y-location on the boundary of a given grob </td>
  </tr>
  <tr>
   <td style="text-align:left;"> <code class="monash-black f4">"grobwidth"</code>, <code class="monash-black f4">"grobheight"</code> </td>
   <td style="text-align:left;"> Multiples of the width/height of a given grob </td>
  </tr>
</tbody>
</table>

---

# Drawing with `grid` .circle.monash-bg-white.monash-blue[1]

```r
grid.rect(x = 0, 
          y = 0, 
          width = 0.25, 
          height = 0.25, 
          default.units = "npc",
          just = c("left", "bottom"), 
          gp = gpar(fill = "pink"),
          vp = NULL)
```

]
.w-50[
<img src="images/day1-session1/vp-rect1-1.png" width="504" class='ba' style="display: block; margin: auto;" />
.f4[
* The grid lines are drawn for your convenience
]

]
]

---

# Drawing with `grid` .circle.monash-bg-white.monash-blue[2]

```r
*grid.rect(x = 0.5,
*         y = 0.5,
          width = 0.25, 
          height = 0.25, 
          default.units = "npc",
          just = c("left", "bottom"), 
          gp = gpar(fill = "pink"),
          vp = NULL)
```

]
.w-50[
<img src="images/day1-session1/vp-rect2-1.png" width="504" class='ba' style="display: block; margin: auto;" />

]
]

---

# Drawing with `grid` .circle.monash-bg-white.monash-blue[3]

```r
grid.rect(x = 0.5, 
          y = 0.5, 
          width = 0.25, 
          height = 0.25, 
          default.units = "npc",
*         just = c("center", "center"),
          gp = gpar(fill = "pink"),
          vp = NULL)
```
]
.w-50[
<img src="images/day1-session1/vp-rect3-1.png" width="504" class='ba' style="display: block; margin: auto;" />

]
]

---

# Drawing with `grid` .circle.monash-bg-white.monash-blue[4]

```r
grid.rect(x = 0.5, 
          y = 0.5, 
*         width = 0.5,
*         height = 0.5,
          default.units = "npc",
          just = c("center", "center"), 
          gp = gpar(fill = "pink"),
          vp = NULL)
```
]
.w-50[
<img src="images/day1-session1/vp-rect4-1.png" width="504" class='ba' style="display: block; margin: auto;" />

]
]

---

# Drawing with `grid` .circle.monash-bg-white.monash-blue[5]

```r
grid.rect(x = 0.5, 
          y = 0.5, 
          width = 0.5, 
          height = 0.5, 
*         default.units = "in",
          just = c("left", "bottom"), 
          gp = gpar(fill = "pink"),
          vp = NULL)
```
]
.w-50[
<img src="images/day1-session1/vp-rect5-1.png" width="504" class='ba' style="display: block; margin: auto;" />
.center[
This canvas is 5 inches high and 7 inches wide

]

]
]

---

# Drawing with `grid` .circle.monash-bg-white.monash-blue[6]

```r
*grid.rect(x = unit(0.5, "npc"),
*         y = unit(0.5, "npc"),
          width = 0.5, 
          height = 0.5, 
          default.units = "in", 
          just = c("left", "bottom"), 
          gp = gpar(fill = "pink"),
          vp = NULL)
```
]
.w-50[
<img src="images/day1-session1/vp-rect6-1.png" width="504" class='ba' style="display: block; margin: auto;" />
]]

---

# Drawing with `grid` .circle.monash-bg-white.monash-blue[7]

```r
grid.circle(
  x = 1:6,
  y = 3,
  r = 1:6/6,
  default.units = "in", 
  gp = gpar(fill = sample(colors(), 6)),
  vp = NULL)
```
]
.w-50[
<img src="images/day1-session1/vp-rect7-1.png" width="504" class='ba' style="display: block; margin: auto;" />

* Arguments can be vectorised
* The Z-order is determined by the order of the input

]]

---

# Viewport

---

# The root viewport

* A **viewport** is a polygon (often rectangular) viewing region in computer graphics.
* When `vp = NULL`, this refers to the root viewport, i.e. the canvas

---

# Viewport in `grid` .circle.monash-bg-white.monash-blue[1]

```r
grid.circle(x = c(0.1, 0.9),
            y = c(0.1, 0.9),
            r = 0.2,
            default.units = "npc", 
            gp = gpar(fill = "pink"),
            vp = NULL)
```
]
.w-50[
<img src="images/day1-session1/vp1-1.png" width="504" class='ba' style="display: block; margin: auto;" />

Graphical output outside of the root Viewport are not visible.

]]

---

# Viewport in `grid` .circle.monash-bg-white.monash-blue[2]

```r
*vp1 <- viewport(x = 0.1, y = 0.1,
*       width = 0.5,
*       height = 0.5,
*       just = c("left", "bottom"))

grid.circle(x = c(0.1, 0.9),
            y = c(0.1, 0.9),
            r = 0.2,
            default.units = "npc", 
            gp = gpar(fill = "pink"),
*           vp = vp1)
```
]
.w-50[
<img src="images/day1-session1/vp2-1.png" width="504" class='ba' style="display: block; margin: auto;" />

Graphical object is drawn relative to Viewport `vp1`.

]]

---

# Viewport in `grid` .circle.monash-bg-white.monash-blue[2]

```r
*vp1 <- viewport(x = 0.1, y = 0.1,
*       width = 0.5,
*       height = 0.5,
*       just = c("left", "bottom"))

grid.circle(x = c(0.1, 0.9),
            y = c(0.1, 0.9),
            r = 0.2,
            default.units = "npc", 
            gp = gpar(fill = "pink"),
*           vp = vp1)
```
]
.w-50[
<img src="images/day1-session1/vp3-1.png" width="504" class='ba' style="display: block; margin: auto;" />

Graphical object is drawn relative to Viewport `vp1`.

]]

---