ggrastr: Rasterize ggplot2 Layers

ggrastr provides a modern, preferred way to rasterize specific layers in ggplot2 using the rasterise() function. This approach is superior to the legacy wrapper functions because it allows you to wrap any standard ggplot2 geom (like geom_point(), geom_tile(), or geom_beeswarm()) and control the rasterization parameters without needing a specific _rast version of that geom.

Using rasterise() ensures that only the specified layer is rasterized, while other elements like text, axes, and labels remain in vector format, preventing the loss of quality in text elements while significantly reducing file size for plots with many points.

```r
# Preferred modern approach
gg_rasterized <- gg + rasterise(geom_point(), dpi = 300, scale = 1)
```埋

You can install the stable version of ggrastr from CRAN or the latest development version from GitHub using devtools.

To install the stable version:

install.packages('ggrastr')

To install the latest version from GitHub:

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

The following table maps the legacy wrapper functions to their modern rasterise() equivalents. It is strongly encouraged to use the rasterise() pattern for all new development.

For ggrastr versions >=0.2.2, you can set a global default resolution for all rasterized layers using R's options() function. This avoids having to specify dpi in every function call.

# Set global DPI to 750
options(ggrastr.default.dpi=750)

# Subsequent calls will use 750 DPI
plot + rasterise(geom_point())

# Reset to default 300
options(ggrastr.default.dpi=300)

Instead of specifying dpi in every function call, you can set a global default for all ggrastr operations using R's options() function. This is available in ggrastr versions >=0.2.2.

Use options(ggrastr.default.dpi = N) to set the value, where N is the desired integer resolution.

# Set global DPI to 750
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)

# Reset to default 300
options(ggrastr.default.dpi=300)

If your R session crashes when rendering a rasterized plot, it is likely that your Cairo package was built for a different version of R.

1. Verify Cairo version: Run the following command to check if the Built version of the Cairo package matches your current R version:

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

2. Test Cairo functionality: Run this command to see if Cairo causes a crash:

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

When dealing with a massive number of points in a boxplot, outliers can become noninformative. geom_boxplot_jitter() allows you to jitter these outliers. You can also rasterize this specific layer using the raster.dpi argument within the function.

library(ggplot2)
library(ggrastr)

points_num <- 500000
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")

# Jitter outliers and rasterize the layer
gg_box_rast <- gg + geom_boxplot_jitter(
  outlier.size=0.1, 
  outlier.jitter.width=0.3, 
  outlier.alpha=0.5, 
  raster.dpi=200
)
print(gg_box_rast)

If you are using the ggbeeswarm package, you can rasterize its layers using ggrastr::rasterise(). This is the recommended way to handle beeswarm or quasirandom plots with large datasets to avoid overplotting and performance issues.

library(ggplot2)
library(ggrastr)
library(ggbeeswarm)

# Recommended: use rasterise() with ggbeeswarm geoms
ggplot(mtcars) + 
  rasterise(geom_beeswarm(aes(x = factor(cyl), y=mpg)))

# Alternatively, for quasirandom plots
ggplot(mtcars) + 
  rasterise(geom_quasirandom(aes(x = factor(cyl), y=mpg)))

Heatmaps with large grids (e.g., 500x500) can result in very large PDF file sizes. Use rasterise() with geom_tile() to reduce the output size.

library(ggplot2)
library(ggrastr)

coords <- expand.grid(1:500, 1:500)
coords$Value <- 1 / apply(as.matrix(coords), 1, function(x) sum((x - c(50, 50))^2)^0.01)

# Rasterized heatmap
gg_tile_rast <- ggplot(coords) + 
  rasterise(geom_tile(aes(x=Var1, y=Var2, fill=Value)), dpi = 300, scale = 1)

print(gg_tile_rast)

library(ggplot2)
library(ggrastr)
coords <- expand.grid(1:500, 1:500)
coords$Value <- 1 / apply(as.matrix(coords), 1, function(x) sum((x - c(50, 50))^2)^0.01)
gg_tile_vec <- ggplot(coords) + geom_tile(aes(x=Var1, y=Var2, fill=Value))
gg_tile_rast <- ggplot(coords) + rasterise(geom_tile(aes(x=Var1, y=Var2, fill=Value)), dpi = 300, scale = 1)
print(gg_tile_rast)

For heatmaps created with geom_tile(), use rasterise() to prevent extremely large vector files. This is particularly effective when dealing with large grids (e.g., 500x500).

library(ggplot2)
library(ggrastr)

coords <- expand.grid(1:500, 1:500)
coords$Value <- 1 / apply(as.matrix(coords), 1, function(x) sum((x - c(50, 50))^2)^0.01)

# Rasterize the tile layer
gg_tile_rast <- ggplot(coords) + 
  rasterise(geom_tile(aes(x=Var1, y=Var2, fill=Value)), dpi = 300, scale = 1)
print(gg_tile_rast)