### Install ggrastr from GitHub

Source: https://github.com/vpetukhov/ggrastr/blob/main/README.md

Use this command to install the latest development version of the ggrastr package from GitHub. Ensure devtools is installed first.

```r
install.packages('devtools')
devtools::install_github('VPetukhov/ggrastr', build_vignettes = TRUE)
```

--------------------------------

### Install ggrastr from CRAN

Source: https://github.com/vpetukhov/ggrastr/blob/main/README.md

Use this command to install the stable version of the ggrastr package from CRAN.

```r
install.packages('ggrastr')
```

--------------------------------

### Test Cairo graphics device

Source: https://github.com/vpetukhov/ggrastr/blob/main/README.md

Run this command in R to test if the Cairo graphics device is functioning correctly. It attempts to create a raster device and then closes it. If this crashes your R session, it may indicate a Cairo installation issue.

```r
Cairo::Cairo(type='raster'); dev.off()
```

--------------------------------

### Check Cairo package details

Source: https://github.com/vpetukhov/ggrastr/blob/main/README.md

This R code snippet helps diagnose potential issues with the Cairo graphics library by displaying its installation path, version, and build information. Ensure the 'Built' version matches your R version.

```r
pkgs <- as.data.frame(installed.packages(), stringsAsFactors = FALSE, row.names = FALSE)
pkgs[pkgs$Package == 'Cairo', c("Package", "LibPath", "Version", "Built")]
```

--------------------------------

### Compare Raster vs. Vector Plot File Sizes

Source: https://github.com/vpetukhov/ggrastr/blob/main/doc/Legacy_functions.html

This example demonstrates the file size difference between a rasterized plot (gg_rast) and a vector plot (gg_vec) using the PrintFileSize function. Raster plots are generally smaller.

```r
PrintFileSize(gg_rast, 'Raster')
#> Raster: 310.2705 Kb.
PrintFileSize(gg_vec, 'Vector')
#> Vector: 556.585 Kb.
```

--------------------------------

### Select rendering device for rasterization

Source: https://github.com/vpetukhov/ggrastr/blob/main/vignettes/Raster_geoms.md

Choose between 'cairo', 'ragg', or 'ragg_png' rendering devices. 'ragg' can be faster with better anti-aliasing, while 'ragg_png' resolves alpha blending issues.

```R
# The default 'cairo' at dpi=5
plot + rasterise(geom_point(), dpi = 5, dev = "cairo")
```

```R
# Using 'ragg' gives better anti-aliasing but has unexpected alpha blending
plot + rasterise(geom_point(), dpi = 5, dev = "ragg")
```

```R
# Using 'ragg_png' solves the alpha blend, but requires writing a temporary file to disk
plot + rasterise(geom_point(), dpi = 5, dev = "ragg_png")
```

--------------------------------

### Rasterize jittered scatter plots with geom_jitter_rast()

Source: https://github.com/vpetukhov/ggrastr/blob/main/vignettes/Legacy_functions.md

Use geom_jitter_rast() for creating rasterized scatter plots with jitter. This legacy function is an alternative to using rasterise(geom_jitter()). Note the deprecated usage of `guide = FALSE` which should be replaced with `guide = "none"`.

```R
library(ggplot2)
library(ggrastr)
points_num <- 5000 
df <- data.frame(x=rnorm(points_num), y=rnorm(points_num), c=as.factor(1:points_num %% 2))
gg <- ggplot(df, aes(x=x, y=y, color=c)) + scale_color_discrete(guide="none")
gg_jitter_rast <- gg + rasterise(geom_jitter(), dpi = 300, scale = 1)
print(gg_jitter_rast)
```

```R
library(ggplot2)
library(ggrastr)

points_num <- 5000 
df <- data.frame(x=rnorm(points_num), y=rnorm(points_num), c=as.factor(1:points_num %% 2))
gg <- ggplot(df, aes(x=x, y=y, color=c)) + scale_color_discrete(guide=FALSE)

gg_jitter_rast <- gg + geom_jitter_rast(raster.dpi=600)
print(gg_jitter_rast)
#> Warning: It is deprecated to specify `guide = FALSE` to remove a guide. Please
#> use `guide = "none"` instead.
```

--------------------------------

### Rasterize geom_point with distorted aspect ratio

Source: https://github.com/vpetukhov/ggrastr/blob/main/doc/Raster_geoms.html

This example shows how points remain round even when the aspect ratio of the plot is distorted, by using `rasterise` with `geom_point`.

```R
plot <- ggplot(diamonds, aes(carat, price, colour = cut))
plot + rasterise(geom_point(), dpi = 72) + theme(aspect.ratio = 0.2)
```

--------------------------------

### Select Rendering Device: Cairo vs. ragg

Source: https://github.com/vpetukhov/ggrastr/blob/main/doc/Raster_geoms.html

Demonstrates selecting between 'cairo' and 'ragg' devices for plot rasterization. Use 'ragg_png' to work around potential alpha blending issues with the default ragg device.

```R
# The default 'cairo' at dpi=5
plot + rasterise(geom_point(), dpi = 5, dev = "cairo")
```

```R
# The 'ragg' device at dpi=5
plot + rasterise(geom_point(), dpi = 5, dev = "ragg")
```

```R
# The 'ragg_png' device at dpi=5
plot + rasterise(geom_point(), dpi = 5, dev = "ragg_png")
```

--------------------------------

### Decrease raster object size with scale < 1

Source: https://github.com/vpetukhov/ggrastr/blob/main/doc/Raster_geoms.html

Use `scale` less than 1 within `rasterise` to shrink raster objects. This example shows points becoming half the size of those in the original plot.

```R
# smaller objects, scale < 1
plot <- ggplot(diamonds, aes(carat, price, colour = cut))
plot + rasterise(geom_point(), dpi = 300, scale = 0.5)
```

--------------------------------

### Select Rendering Device for Rasterization

Source: https://github.com/vpetukhov/ggrastr/blob/main/doc/Raster_geoms.html

Use 'ragg_png' as the device to solve alpha blending issues when rasterizing geoms. This method requires writing a temporary file to disk.

```R
plot + rasterise(geom_point(), dpi = 5, dev = "ragg_png")
```

--------------------------------

### Compare File Sizes of Rasterized vs. Vectorized Plots

Source: https://github.com/vpetukhov/ggrastr/blob/main/vignettes/Legacy_functions.md

Demonstrates the file size difference between rasterized and vectorized plots. This utility function helps in assessing the benefits of rasterization for large datasets.

```R
PrintFileSize(gg_tile_rast, 'Raster')
#> Raster: 46.77637 Kb.
PrintFileSize(gg_tile_vec, 'Vector')
#> Vector: 817.8398 Kb.
```

```R
PrintFileSize(gg_box_rast, 'Raster')
#> Raster: 116.998 Kb.
PrintFileSize(gg_box_vec, 'Vector')
#> Vector: 221.9131 Kb.
```

--------------------------------

### Unchanged Scaling with scale=1

Source: https://github.com/vpetukhov/ggrastr/blob/main/doc/Raster_geoms.html

Demonstrates how to use `rasterise` with `scale=1` to maintain the original size of raster objects. This is useful when no scaling is desired.

```R
plot <- ggplot(diamonds, aes(carat, price, colour = cut))
plot + rasterise(geom_point(), dpi = 300, scale = 1)
```

--------------------------------

### Create Box Plot with Jittered Outliers in ggplot2

Source: https://github.com/vpetukhov/ggrastr/blob/main/doc/Legacy_functions.html

This code snippet generates a basic box plot using ggplot2. It prepares data with a large number of points and then creates a box plot. Use this as a starting point before applying ggrastr for optimization.

```R
library(ggplot2)
library(ggrastr)
points_num <- 5000
df <- data.frame(x=as.factor(1:points_num %% 2), y=log(abs(rcauchy(points_num))))
gg <- ggplot(df, aes(x=x, y=y)) + scale_color_discrete(guide="none")
boxplot <- gg + geom_boxplot()
print(boxplot)
```

--------------------------------

### Basic HTML Body Styling

Source: https://github.com/vpetukhov/ggrastr/blob/main/doc/Raster_geoms.html

Sets default background color, margins, max-width, overflow, and font properties for the HTML body, providing a clean and readable page layout.

```css
body { background-color: #fff; margin: 1em auto; max-width: 700px; overflow: visible; padding-left: 2em; padding-right: 2em; font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif; font-size: 14px; line-height: 1.35; }
```

--------------------------------

### CSS for Code Styling

Source: https://github.com/vpetukhov/ggrastr/blob/main/doc/Raster_geoms.html

Provides CSS rules for styling code blocks, including pre-formatted text, source code spans, and specific syntax highlighting elements.

```css
code{white-space: pre-wrap;} span.smallcaps{font-variant: small-caps;} span.underline{text-decoration: underline;} div.column{display: inline-block; vertical-align: top; width: 50%;} div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;} ul.task-list{list-style: none;} code { white-space: pre; } .sourceCode { overflow: visible; } pre > code.sourceCode { white-space: pre; position: relative; } pre > code.sourceCode > span { display: inline-block; line-height: 1.25; } pre > code.sourceCode > span:empty { height: 1.2em; } .sourceCode { overflow: visible; } code.sourceCode > span { color: inherit; text-decoration: inherit; } div.sourceCode { margin: 1em 0; } pre.sourceCode { margin: 0; } @media screen { div.sourceCode { overflow: auto; } } @media print { pre > code.sourceCode { white-space: pre-wrap; } pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; } }
```

```css
pre.numberSource code { counter-reset: source-line 0; } pre.numberSource code > span { position: relative; left: -4em; counter-increment: source-line; } pre.numberSource code > span > a:first-child::before { content: counter(source-line); position: relative; left: -1em; text-align: right; vertical-align: baseline; border: none; display: inline-block; -webkit-touch-callout: none; -webkit-user-select: none; -khtml-user-select: none; -moz-user-select: none; -ms-user-select: none; user-select: none; padding: 0 4px; width: 4em; color: #aaaaaa; } pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; } div.sourceCode { } @media screen { pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; } }
```

```css
code span.al { color: #ff0000; font-weight: bold; } /* Alert */ code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */ code span.at { color: #7d9029; } /* Attribute */ code span.bn { color: #40a070; } /* BaseN */ code span.bu { } /* BuiltIn */ code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */ code span.ch { color: #4070a0; } /* Char */ code span.cn { color: #880000; } /* Constant */ code span.co { color: #60a0b0; font-style: italic; } /* Comment */ code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */ code span.do { color: #ba2121; font-style: italic; } /* Documentation */ code span.dt { color: #902000; } /* DataType */ code span.dv { color: #40a070; } /* DecVal */ code span.er { color: #ff0000; font-weight: bold; } /* Error */ code span.ex { } /* Extension */ code span.fl { color: #40a070; } /* Float */ code span.fu { color: #06287e; } /* Function */ code span.im { } /* Import */ code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */ code span.kw { color: #007020; font-weight: bold; } /* Keyword */ code span.op { color: #666666; } /* Operator */ code span.ot { color: #007020; } /* Other */ code span.pp { color: #bc7a00; } /* Preprocessor */ code span.sc { color: #4070a0; } /* SpecialChar */ code span.ss { color: #bb6688; } /* SpecialString */ code span.st { color: #4070a0; } /* String */ code span.va { color: #19177c; } /* Variable */ code span.vs { color: #4070a0; } /* VerbatimString */ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
```

--------------------------------

### Apply Pandoc Styles to Pre.sourceCode

Source: https://github.com/vpetukhov/ggrastr/blob/main/doc/Legacy_functions.html

This JavaScript code iterates through style sheets to find Pandoc-specific rules for 'div.sourceCode' and applies them to 'pre.sourceCode' elements. This ensures consistent styling for code blocks across different Pandoc versions and rendering contexts.

```javascript
(function() {
  var sheets = document.styleSheets;
  for (var i = 0; i < sheets.length; i++) {
    if (sheets[i].ownerNode.dataset["origin"] !== "pandoc") continue;
    try {
      var rules = sheets[i].cssRules;
    } catch (e) {
      continue;
    }
    for (var j = 0; j < rules.length; j++) {
      var rule = rules[j];
      // check if there is a div.sourceCode rule
      if (rule.type !== rule.STYLE_RULE || rule.selectorText !== "div.sourceCode") continue;
      var style = rule.style.cssText;
      // check if color or background-color is set
      if (rule.style.color === '' && rule.style.backgroundColor === '') continue;
      // replace div.sourceCode by a pre.sourceCode rule
      sheets[i].deleteRule(j);
      sheets[i].insertRule('pre.sourceCode{' + style + '}', j);
    }
  }
})();
```

--------------------------------

### Using 'ragg' for better anti-aliasing

Source: https://github.com/vpetukhov/ggrastr/blob/main/doc/Raster_geoms.html

When using the 'ragg' device, you can achieve better anti-aliasing for rasterized geometries. Be aware that 'ragg' may produce unexpected alpha blending results.

```r
plot + rasterise(geom_point(), dpi = 5, dev = "ragg")
```

--------------------------------

### Set default DPI globally with options()

Source: https://github.com/vpetukhov/ggrastr/blob/main/vignettes/Raster_geoms.md

Set the default DPI for all rasterized plots globally using `options(ggrastr.default.dpi=N)`. This affects subsequent plots until the option is changed.

```R
## set ggrastr.default.dpi with options()
options(ggrastr.default.dpi=750)

plot <- ggplot(diamonds, aes(carat, price, colour = cut))
new_plot = plot + rasterise(geom_point()) + theme(aspect.ratio = 1)
print(new_plot)
```

```R
## set back to default 300
options(ggrastr.default.dpi=300)
```