grImport2

The grImport2 package is an R package for importing vector images to be drawn within an R plot. It was developed as part of the 2013 Google Summer of Code. It improves upon some of the limitations of the grImport package and more comprehensively reproduces vector images in R.

It can import any SVG image that has been generated by the Cairo graphics library. To ensure that this has been performed, it is often necessary to use the grConvert package to convert from popular vector image formats (PostScript, PDF and SVG) into an SVG image that has been generated by Cairo.

An example of what can be achieved is shown below, where I import the Flag of New Zealand (from Wikimedia) into a basic plot.

> library(grImport2)
> flag <- readPicture("nzflag.svg")
> xs <- runif(10)
> ys <- runif(10)
> grid.symbols(flag,
+              x = xs, y = ys, size = 0.3, default.units = "npc",
+              ext = "clipbbox")

Installation

grImport2 requires a few packages in order to run. To install them, run the following command:

> install.packages(c("XML", "png", "jpeg", "base64enc"))

If you have the devtools package installed, you can easily install grImport2 using the install_github() function.

> devtools::install_github("sjp/grImport2")

If you do not have devtools installed, you will have to install using Subversion from the canonical source.

$ svn checkout svn://r-forge.r-project.org/svnroot/grimport/pkg/grImport2

Now we can build and install grImport2.

$ cd grImport2
$ R CMD build .
$ R CMD INSTALL grImport2*.tar.gz

Usage

We will demonstrate basic usage of the grImport2 package using the example shown earlier. It should be noted however that knowledge of the grid package is considered a pre-requisite to proper usage of the grImport2 package.

The first thing we need to do is load the package.

> library(grImport2)

Now we can begin to load a picture that has been converted by grConvert to an SVG image format. We will store the definition of the picture in a variable called flag.

> flag <- readPicture("nzflag.svg")

Now in order to plot the image we have two options. We can either use the grid.picture(), which will plot a single image or we can use grid.symbols() which will plot multiple copies of an image. First, let us see the effect of grid.picture().

> grid.picture(flag, ext = "clipbbox")

We can see that the image has been reproduced reasonably faithfully, but there are some parts of the image that are not correct. To correct this requires the use of the gridSVG package and will not be discussed in this brief overview. For more information consult the package documentation on the ext argument in grid.picture().

Another function that is provided by grImport2 is grid.symbols(). Rather than having to call grid.picture() multiple times, we can (if desired), call grid.symbols() just once instead.

> xs <- runif(10)
> ys <- runif(10)
> grid.symbols(flag,
+              x = xs, y = ys, size = 0.3, default.units = "npc",
+              ext = "clipbbox")

This shows how we can import a vector image and use it as a custom plotting character for use in grid plots.

Documentation

As with all R packages, documentation is provided with the package. Help is available for the grImport2 functions by typing the commands listed below:

• ?readPicture
• ?grid.picture
• ?grid.symbols

Further information demonstrating its usage is available in the following locations:

• Enhanced Vector Image Import: The grConvert and grImport2 packages. A draft article submitted to the R Journal.
• Improved Importing of Vector Graphics in R. A technical report published on the University of Auckland’s Department of Statistics Technical Report Blog.
• Plotting SVG State Flags in R. A demonstration of the ability to import various vector images using USA state flags as a test case. It shows the capabilities (and limitations) of grConvert, grImport and grImport2 as it imports vector images into R.