[med-svn] [r-cran-gridbase] 05/07: New upstream version 0.4-7
Andreas Tille
tille at debian.org
Fri Sep 29 12:51:59 UTC 2017
This is an automated email from the git hooks/post-receive script.
tille pushed a commit to branch master
in repository r-cran-gridbase.
commit b125a52ed314f50e6f848d32081451acf6dfe19b
Author: Andreas Tille <tille at debian.org>
Date: Fri Sep 29 14:46:13 2017 +0200
New upstream version 0.4-7
---
DESCRIPTION | 14 ++
MD5 | 17 ++
NAMESPACE | 10 +
R/base.R | 36 +++
R/grid.R | 121 ++++++++++
R/zzz.R | 4 +
build/vignette.rds | Bin 0 -> 191 bytes
debian/README.test | 8 -
debian/changelog | 11 -
debian/compat | 1 -
debian/control | 19 --
debian/copyright | 28 ---
debian/docs | 2 -
debian/examples | 1 -
debian/rules | 3 -
debian/source/format | 1 -
debian/tests/control | 3 -
debian/tests/run-unit-test | 19 --
debian/watch | 2 -
demo/00Index | 1 +
demo/gridBase.R | 32 +++
inst/doc/changes.txt | 25 ++
inst/doc/chinasea.txt | 26 ++
inst/doc/gridBase.R | 432 +++++++++++++++++++++++++++++++++
inst/doc/gridBase.Rnw | 591 +++++++++++++++++++++++++++++++++++++++++++++
inst/doc/gridBase.pdf | Bin 0 -> 144280 bytes
man/baseViewports.Rd | 46 ++++
man/gridOMI.Rd | 107 ++++++++
vignettes/gridBase.Rnw | 591 +++++++++++++++++++++++++++++++++++++++++++++
vignettes/gridBase.bib | 23 ++
30 files changed, 2076 insertions(+), 98 deletions(-)
diff --git a/DESCRIPTION b/DESCRIPTION
new file mode 100644
index 0000000..429989b
--- /dev/null
+++ b/DESCRIPTION
@@ -0,0 +1,14 @@
+Package: gridBase
+Title: Integration of base and grid graphics
+Version: 0.4-7
+Author: Paul Murrell
+Depends: R (>= 2.3.0)
+Imports: graphics, grid
+Suggests: lattice
+Description: Integration of base and grid graphics
+Maintainer: Paul Murrell <paul at stat.auckland.ac.nz>
+License: GPL
+Packaged: 2014-02-24 01:35:23 UTC; EC\pmur002
+NeedsCompilation: no
+Repository: CRAN
+Date/Publication: 2014-02-24 07:20:37
diff --git a/MD5 b/MD5
new file mode 100644
index 0000000..f24541e
--- /dev/null
+++ b/MD5
@@ -0,0 +1,17 @@
+6357f2ece12d167c6edfc70a9efe76d7 *DESCRIPTION
+c23517ab9923f0ec0d87802ff359413a *NAMESPACE
+519be1dbab635db1db865c24cc09dfba *R/base.R
+921e99fcb1c256cd1f6ad6475d7dc737 *R/grid.R
+0433ce02f1d7d8db515c259aabb64f1b *R/zzz.R
+f4d0a523b792fe11d3d89aa1ed8dc50e *build/vignette.rds
+97c6d4a0460b64a8e6ac40a24cddb33c *demo/00Index
+b0f31e33f859785fb0058f30dd3bcbb6 *demo/gridBase.R
+bc3aecdea068b8689e959dc5464b2ecb *inst/doc/changes.txt
+444f2b1f2d8472ae45c05d9f86321e46 *inst/doc/chinasea.txt
+04bf5e05f35567c9233a8874af544daf *inst/doc/gridBase.R
+7d84d0cdabfa9877c817064d35ca47b6 *inst/doc/gridBase.Rnw
+df58ed5b9c51efa05f0de0f6ad12a429 *inst/doc/gridBase.pdf
+1cb988e34f020de26f286dc9684e2ebc *man/baseViewports.Rd
+dd062f90a9221e7f2a1241cb9fbbddc1 *man/gridOMI.Rd
+7d84d0cdabfa9877c817064d35ca47b6 *vignettes/gridBase.Rnw
+6506cce9c6756dc2b0e4f061542f2404 *vignettes/gridBase.bib
diff --git a/NAMESPACE b/NAMESPACE
new file mode 100644
index 0000000..e17aaf0
--- /dev/null
+++ b/NAMESPACE
@@ -0,0 +1,10 @@
+
+importFrom(graphics,
+ par)
+
+importFrom(grid,
+ unit, viewport,
+ convertHeight, convertWidth, current.transform, get.gpar)
+
+export("baseViewports",
+ "gridOMI", "gridFIG", "gridPLT", "gridPAR")
diff --git a/R/base.R b/R/base.R
new file mode 100644
index 0000000..577de50
--- /dev/null
+++ b/R/base.R
@@ -0,0 +1,36 @@
+
+# Generate a list of viewports that correspond to the current base
+# inner region, figure region, and plot region
+baseViewports <- function() {
+ omi <- par("omi")
+ innervp <- viewport(x=unit(omi[2], "inches"),
+ y=unit(omi[1], "inches"),
+ width=unit(1, "npc") -
+ unit(omi[1], "inches") -
+ unit(omi[3], "inches"),
+ height=unit(1, "npc") -
+ unit(omi[2], "inches") -
+ unit(omi[4], "inches"),
+ just=c("left", "bottom"))
+ fig <- par("fig")
+ figurevp <- viewport(x=unit(fig[1], "npc"),
+ y=unit(fig[3], "npc"),
+ width=unit(fig[2] - fig[1], "npc"),
+ height=unit(fig[4] - fig[3], "npc"),
+ just=c("left", "bottom"))
+ plt <- par("plt")
+ usr <- par("usr")
+ logscale <- FALSE
+ if (par("xlog") || par("ylog")) {
+ warning("viewport scales NOT set to user coordinates")
+ logscales <- TRUE
+ }
+ plotvp <- viewport(x=unit(plt[1], "npc"),
+ y=unit(plt[3], "npc"),
+ width=unit(plt[2] - plt[1], "npc"),
+ height=unit(plt[4] - plt[3], "npc"),
+ just=c("left", "bottom"),
+ xscale=c(usr[1], usr[2]),
+ yscale=c(usr[3], usr[4]))
+ list(inner=innervp, figure=figurevp, plot=plotvp)
+}
diff --git a/R/grid.R b/R/grid.R
new file mode 100644
index 0000000..567019c
--- /dev/null
+++ b/R/grid.R
@@ -0,0 +1,121 @@
+
+# Get the location/size of the current viewport in inches on the device
+currentViewportLoc <- function() {
+ # Get the current viewport transformation
+ # This transforms from inches in the current viewport to
+ # inches on the device
+ transform <- current.transform()
+ # Convert the current viewport's location to inches ...
+ width <- convertWidth(unit(1, "npc"), "inches", valueOnly=TRUE)
+ height <- convertHeight(unit(1, "npc"), "inches", valueOnly=TRUE)
+ # ... then to inches on the device
+ bottomleft <- c(0, 0, 1) %*% transform
+ left <- bottomleft[1]/bottomleft[3]
+ bottom <- bottomleft[2]/bottomleft[3]
+ topright <- c(width, height, 1) %*% transform
+ right <- topright[1]/topright[3]
+ top <- topright[2]/topright[3]
+ list(left=left, bottom=bottom, right=right, top=top)
+}
+
+# Prolific use of round(..., digits=4) because lots of the time
+# calculated values will be intended to be the same, but will
+# differ by tiny amounts due to rounding error. In particular,
+# we are keen to avoid getting tiny negative values for par()
+# settings. digits=4 because with the values we are dealing with
+# two decimal places is plenty of precision.
+
+# Check that a viewport location is within base outer margin setting
+badOMI <- function(cvp, omi, din) {
+ round(cvp$left - omi[2], digits=4) < 0 ||
+ round(cvp$bottom - omi[1], digits=4) < 0 ||
+ round(cvp$right - (din[1] - omi[4]), digits=4) > 0 ||
+ round(cvp$top - (din[2] - omi[3]), digits=4) > 0
+}
+
+# Check that a viewport location is within base figure region setting
+badFIG <- function(cvp, fig, omi, din) {
+ width <- din[1] - omi[2] - omi[4]
+ height <- din[2] - omi[1] - omi[3]
+ round(cvp$left - (omi[2] + fig[1]*width), digits=4) < 0 ||
+ round(cvp$bottom - (omi[1] + fig[3]*height), digits=4) < 0||
+ round(cvp$right - (omi[2] + fig[2]*width), digits=4) > 0 ||
+ round(cvp$top - (omi[1] + fig[4]*height), digits=4) > 0
+}
+
+# Return par(omi) settings that correspond to the current
+# grid viewport
+gridOMI <- function() {
+ # First get the current viewport locn/size
+ cvp <- currentViewportLoc()
+ # return outer margin values
+ din <- par("din")
+ # Do a round to avoid rounding error
+ omi <- round(c(cvp$bottom, cvp$left,
+ din[2] - cvp$top, din[1] - cvp$right), digits=4)
+ omi
+}
+
+# Return par(fig) settings that correspond to the current
+# grid viewport
+gridFIG <- function() {
+ # First get the current viewport locn/size
+ cvp <- currentViewportLoc()
+ # Get the current base outer margins (in inches)
+ din <- par("din")
+ omi <- par("omi")
+ # Throw an error if the curent viewport is outside the
+ # current outer margins (implies fig values outside [0, 1] range)
+ if (badOMI(cvp, omi, din))
+ stop("Outer margins too large and/or viewport too large")
+ # par(fig) is proportions within the inner region
+ # par(fig) is c(x1, x2, y1, y2)
+ width <- din[1] - omi[2] - omi[4]
+ height <- din[2] - omi[1] - omi[3]
+ # Do a round to avoid rounding error
+ fig <- round(c((cvp$left - omi[1])/width,
+ (cvp$right - omi[1])/width,
+ (cvp$bottom - omi[2])/height,
+ (cvp$top - omi[2])/height), digits=4)
+ fig
+}
+
+# Return par(plt) settings that correspond to the current
+# grid viewport
+gridPLT <- function() {
+ # First get the current viewport locn/size
+ cvp <- currentViewportLoc()
+ # Get the current base outer margins (in inches)
+ # and the current base figure region (as a proportion of the inner region)
+ din <- par("din")
+ omi <- par("omi")
+ fig <- par("fig")
+ # Throw an error if the curent viewport is outside the
+ # current figure region (implies plt values outside [0, 1] range)
+ if (badFIG(cvp, fig, omi, din))
+ stop("Figure region too small and/or viewport too large")
+ # par(plt) is proportions within the figure region
+ # par(plt) is c(x1, x2, y1, y2)
+ innerwidth <- din[1] - omi[2] - omi[4]
+ innerheight <- din[2] - omi[1] - omi[3]
+ width <- innerwidth*(fig[2] - fig[1])
+ height <- innerheight*(fig[4] - fig[3])
+ left <- omi[2] + innerwidth*fig[1]
+ bottom <- omi[1] + innerheight*fig[3]
+ # Do a round to avoid rounding error
+ plt <- round(c((cvp$left - left)/width,
+ (cvp$right - left)/width,
+ (cvp$bottom - bottom)/height,
+ (cvp$top - bottom)/height), digits=4)
+ plt
+}
+
+# Return some gpar settings that can be used to set par() graphical
+# parameters
+gridPAR <- function() {
+ gpars <- get.gpar()
+ # FIXME: Need to add font specifications too
+ gpars <- list(col=gpars$col,
+ lwd=gpars$lwd,
+ lty=gpars$lty)
+}
diff --git a/R/zzz.R b/R/zzz.R
new file mode 100644
index 0000000..ebf9a23
--- /dev/null
+++ b/R/zzz.R
@@ -0,0 +1,4 @@
+
+.onLoad <- function(lib, pkg)
+{
+}
diff --git a/build/vignette.rds b/build/vignette.rds
new file mode 100644
index 0000000..7ad1f26
Binary files /dev/null and b/build/vignette.rds differ
diff --git a/debian/README.test b/debian/README.test
deleted file mode 100644
index 55a9142..0000000
--- a/debian/README.test
+++ /dev/null
@@ -1,8 +0,0 @@
-Notes on how this package can be tested.
-────────────────────────────────────────
-
-To run the unit tests provided by the package you can do
-
- sh run-unit-test
-
-in this directory.
diff --git a/debian/changelog b/debian/changelog
deleted file mode 100644
index bf168d0..0000000
--- a/debian/changelog
+++ /dev/null
@@ -1,11 +0,0 @@
-r-cran-gridbase (0.4-7-2) unstable; urgency=medium
-
- * added CI test deps (thanks to Gordon Ball)
-
- -- Andreas Tille <tille at debian.org> Sat, 30 Jul 2016 22:32:26 +0200
-
-r-cran-gridbase (0.4-7-1) unstable; urgency=low
-
- * Initial release (closes: #830197)
-
- -- Andreas Tille <tille at debian.org> Thu, 07 Jul 2016 12:48:41 +0200
diff --git a/debian/compat b/debian/compat
deleted file mode 100644
index ec63514..0000000
--- a/debian/compat
+++ /dev/null
@@ -1 +0,0 @@
-9
diff --git a/debian/control b/debian/control
deleted file mode 100644
index dcd45a4..0000000
--- a/debian/control
+++ /dev/null
@@ -1,19 +0,0 @@
-Source: r-cran-gridbase
-Maintainer: Debian Med Packaging Team <debian-med-packaging at lists.alioth.debian.org>
-Uploaders: Andreas Tille <tille at debian.org>
-Section: gnu-r
-Priority: optional
-Build-Depends: debhelper (>= 9),
- cdbs,
- r-base-dev,
-Standards-Version: 3.9.8
-Vcs-Browser: https://anonscm.debian.org/viewvc/debian-med/trunk/packages/R/r-cran-gridbase/trunk/
-Vcs-Svn: svn://anonscm.debian.org/debian-med/trunk/packages/R/r-cran-gridbase/trunk/
-Homepage: https://cran.r-project.org/web/packages/gridBase
-
-Package: r-cran-gridbase
-Architecture: all
-Depends: ${misc:Depends},
- ${R:Depends},
-Description: GNU R Integration of base and grid graphics
- This GNU R package enables integration of base and grid graphics.
diff --git a/debian/copyright b/debian/copyright
deleted file mode 100644
index e715f94..0000000
--- a/debian/copyright
+++ /dev/null
@@ -1,28 +0,0 @@
-Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
-Upstream-Name: gridBase
-Upstream-Contact: Paul Murrell <paul at stat.auckland.ac.nz>
-Source: https://cran.r-project.org/web/packages/gridBase
-
-Files: *
-Copyright: 2012-2014 Paul Murrell <paul at stat.auckland.ac.nz>
-License: GPL-2+
-Comment: The download page specifies
- GPL-2 | GPL-3 [expanded from: GPL] and links to a GPL-2+ text
-
-Files: debian/*
-Copyright: 2016 Andreas Tille <tille at debian.org>
-License: GPL-2+
-
-License: GPL-2+
- This program is free software; you can redistribute it and/or modify
- it under the terms of the GNU General Public License as published by
- the Free Software Foundation; either version 2 of the License, or
- (at your option) any later version.
- .
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU General Public License for more details.
- .
- On Debian systems, the complete text of the GNU General Public
- License can be found in `/usr/share/common-licenses/GPL-2'.
diff --git a/debian/docs b/debian/docs
deleted file mode 100644
index 9a4f4f8..0000000
--- a/debian/docs
+++ /dev/null
@@ -1,2 +0,0 @@
-debian/README.test
-debian/tests/run-unit-test
diff --git a/debian/examples b/debian/examples
deleted file mode 100644
index 18244c8..0000000
--- a/debian/examples
+++ /dev/null
@@ -1 +0,0 @@
-vignettes
diff --git a/debian/rules b/debian/rules
deleted file mode 100755
index 2fbba2d..0000000
--- a/debian/rules
+++ /dev/null
@@ -1,3 +0,0 @@
-#!/usr/bin/make -f
-
-include /usr/share/R/debian/r-cran.mk
diff --git a/debian/source/format b/debian/source/format
deleted file mode 100644
index 163aaf8..0000000
--- a/debian/source/format
+++ /dev/null
@@ -1 +0,0 @@
-3.0 (quilt)
diff --git a/debian/tests/control b/debian/tests/control
deleted file mode 100644
index 83a107d..0000000
--- a/debian/tests/control
+++ /dev/null
@@ -1,3 +0,0 @@
-Tests: run-unit-test
-Depends: @, r-cran-lattice
-Restrictions: allow-stderr
diff --git a/debian/tests/run-unit-test b/debian/tests/run-unit-test
deleted file mode 100644
index 43deedf..0000000
--- a/debian/tests/run-unit-test
+++ /dev/null
@@ -1,19 +0,0 @@
-#!/bin/sh -e
-oname=gridBase
-pkg=r-cran-`echo $oname | tr '[A-Z]' '[a-z]'`
-
-if [ "$ADTTMP" = "" ] ; then
- ADTTMP=`mktemp -d /tmp/${pkg}-test.XXXXXX`
-# trap "rm -rf $ADTTMP" 0 INT QUIT ABRT PIPE TERM
-fi
-cd $ADTTMP
-cp /usr/share/doc/$pkg/examples/vignettes/* $ADTTMP
-find . -name "*.gz" -exec gunzip \{\} \;
-for rnw in `ls *.[rRS]nw` ; do
-rfile=`echo $rnw | sed 's/\.[rRS]nw/.R/'`
-R --no-save <<EOT
- Stangle("$rnw")
- source("$rfile", echo=TRUE)
-EOT
- echo "$rnw passed"
-done
diff --git a/debian/watch b/debian/watch
deleted file mode 100644
index 1d5b2f3..0000000
--- a/debian/watch
+++ /dev/null
@@ -1,2 +0,0 @@
-version=3
-http://cran.r-project.org/src/contrib/gridBase_([-\d.]*)\.tar\.gz
diff --git a/demo/00Index b/demo/00Index
new file mode 100644
index 0000000..b181dd0
--- /dev/null
+++ b/demo/00Index
@@ -0,0 +1 @@
+gridBase Demo of integrating grid and base graphics
diff --git a/demo/gridBase.R b/demo/gridBase.R
new file mode 100644
index 0000000..de0e2b7
--- /dev/null
+++ b/demo/gridBase.R
@@ -0,0 +1,32 @@
+
+# A base plot with grid viewports synchronised then
+# further grid viewports pushed to contain pie charts
+
+x <- runif(4)
+y <- runif(4)
+z <- matrix(runif(4*2), ncol=2)
+
+maxpiesize <- unit(1, "inches")
+totals <- apply(z, 1, sum)
+sizemult <- totals/max(totals)
+
+oldomi <- par("omi")
+plot(x, y, xlim=c(-0.2, 1.2), ylim=c(-0.2, 1.2), type="n")
+vps <- baseViewports()
+# First grid action will trigger a new page unless we do this
+# Should be able to avoid this yuckiness in the future
+par(new=TRUE)
+pushViewport(vps$inner, vps$figure, vps$plot)
+grid.grill(h=y, v=x, default.units="native")
+for (i in 1:4) {
+ pushViewport(viewport(x=unit(x[i], "native"),
+ y=unit(y[i], "native"),
+ width=sizemult[i]*maxpiesize,
+ height=sizemult[i]*maxpiesize))
+ grid.rect(gp=gpar(col="grey", fill="white", lty="dashed"))
+ par(mar=rep(0, 4), omi=gridOMI(), new=TRUE)
+ pie(z[i,], radius=1, labels=rep("", 2))
+ popViewport()
+}
+popViewport(3)
+par(omi=rep(0, 4), mar=c(5.1, 5.1, 4.1, 2.1))
diff --git a/inst/doc/changes.txt b/inst/doc/changes.txt
new file mode 100644
index 0000000..8118719
--- /dev/null
+++ b/inst/doc/changes.txt
@@ -0,0 +1,25 @@
+
+FROM gridBase_0.4-6 TO gridBase_0.4-7
+-------------------------------------
+
+1. Changed to ONLY using Imports for 'grid' and 'graphics'
+ (no longer Depends on these)
+ (to satisfy stricter R CMD check)
+
+
+FROM gridBase_0.4-5 TO gridBase_0.4-6
+-------------------------------------
+
+1. Changed to using Imports from 'grid' in NAMESPACE rather than
+ just Depending on 'grid'. Ditto for 'graphics'.
+ This allows other packages to Import 'gridBase' without
+ having to attach 'gridBase' to the search path.
+ (Thanks to Martin Maechler for the suggestion and patches)
+
+
+FROM gridBase_0.4 TO gridBase_0.4-1
+-----------------------------------
+
+1. Updated demo(gridBase)
+ Was using very old gridOMI() behaviour which actually set par(omi)
+ rather than just returning a value to use in a call to par()
diff --git a/inst/doc/chinasea.txt b/inst/doc/chinasea.txt
new file mode 100644
index 0000000..0a50121
--- /dev/null
+++ b/inst/doc/chinasea.txt
@@ -0,0 +1,26 @@
+Date Time Date2 Time2 CSEId name id lat long elev press temp dew rhum shum speed dir u v rain snow sflux lflux isr osr ilr olr rad skin co2 inpar outpar
+2001/07/01 00:00 2001/07/01 00:00 CAMP 46759 Hengchun 22.00000 120.74000 22.10 1006.80 28.90 25.40 81.00 20.29 4.70 90.00 -4.70 0.00 0.00 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99
+2001/07/01 00:00 2001/07/01 00:00 CAMP 46762 Lanyu 22.04000 121.55000 324.00 974.10 27.10 25.50 91.00 21.10 7.60 90.00 -7.60 0.00 0.00 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99
+2001/07/01 00:00 2001/07/01 00:00 CAMP 46754 Tawu 22.36000 120.90000 8.10 1009.80 27.90 25.40 86.00 20.23 0.90 30.00 -0.45 -0.78 0.60 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99
+2001/07/01 00:00 2001/07/01 00:00 CAMP 46744 Kaohsiung 22.57000 120.31000 2.30 1007.50 31.20 24.00 66.00 18.63 4.60 160.00 -1.57 4.32 0.00 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99
+2001/07/01 00:00 2001/07/01 00:00 CAMP 46766 Taitung 22.75000 121.15000 9.00 1009.90 30.80 21.80 59.00 16.24 0.50 320.00 0.32 -0.38 0.00 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99
+2001/07/01 00:00 2001/07/01 00:00 CAMP 46741 Tainan 23.00000 120.20000 13.80 1006.50 30.50 26.20 78.00 21.29 0.10 0.00 0.00 -0.10 0.00 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99
+2001/07/01 00:00 2001/07/01 00:00 CAMP 46761 Chengkung 23.10000 121.37000 33.50 1006.10 30.60 24.30 69.00 19.00 1.30 200.00 0.44 1.22 0.00 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99
+2001/07/01 00:00 2001/07/01 00:00 CAMP 46730 Tungchitao 23.26000 119.66000 45.00 1003.20 30.10 23.90 69.00 18.60 3.20 80.00 -3.15 -0.56 0.00 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99
+2001/07/01 00:00 2001/07/01 00:00 CAMP 46755 Yushan 23.49000 120.95000 3845.00 644.80 8.60 -2.70 45.00 4.84 14.00 130.00 -10.72 9.00 0.00 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99
+2001/07/01 00:00 2001/07/01 00:00 CAMP 46748 Chiayi 23.50000 120.42000 26.90 1004.50 29.30 24.40 75.00 19.14 0.70 40.00 -0.45 -0.54 0.00 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99
+2001/07/01 00:00 2001/07/01 00:00 CAMP 46753 Alishan 23.51000 120.80000 2413.00 764.30 18.40 9.50 56.00 9.72 0.90 10.00 -0.16 -0.89 0.00 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99
+2001/07/01 00:00 2001/07/01 00:00 CAMP 46735 Penghu 23.57000 119.56000 10.70 1007.00 31.20 26.40 76.00 21.54 1.30 100.00 -1.28 0.23 0.00 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99
+2001/07/01 00:00 2001/07/01 00:00 CAMP 46765 Jiyuehtan 23.88000 120.90000 1015.00 899.60 24.70 20.00 75.00 16.33 0.10 0.00 0.00 -0.10 0.00 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99
+2001/07/01 00:00 2001/07/01 00:00 CAMP 46699 Hualien 23.98000 121.60000 16.10 1007.90 29.70 22.40 65.00 16.89 5.80 230.00 4.44 3.73 0.00 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99
+2001/07/01 00:00 2001/07/01 00:00 CAMP 46749 Taichung 24.15000 120.68000 84.00 998.40 29.30 24.50 75.00 19.38 0.50 190.00 0.09 0.49 0.00 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99
+2001/07/01 00:00 2001/07/01 00:00 CAMP 46777 Wuchi 24.26000 120.52000 7.20 1005.50 29.50 24.20 73.00 18.89 1.70 40.00 -1.09 -1.30 0.00 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99
+2001/07/01 00:00 2001/07/01 00:00 CAMP 46706 Suao 24.60000 121.86000 24.90 1006.10 31.30 21.50 56.00 16.01 5.10 170.00 -0.89 5.02 0.00 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99
+2001/07/01 00:00 2001/07/01 00:00 CAMP 46708 Ilan 24.77000 121.75000 7.20 1007.60 30.50 24.30 70.00 18.97 1.50 50.00 -1.15 -0.96 0.00 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99
+2001/07/01 00:00 2001/07/01 00:00 CAMP 46757 Hsinchu 24.83000 121.01000 26.90 1005.20 29.20 25.10 79.00 19.96 0.30 90.00 -0.30 0.00 0.00 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99
+2001/07/01 00:00 2001/07/01 00:00 CAMP 46692 Taipei 25.03000 121.52000 8.00 1007.60 29.80 22.90 67.00 17.42 0.30 240.00 0.26 0.15 0.00 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99
+2001/07/01 00:00 2001/07/01 00:00 CAMP 46694 Keelung 25.13000 121.73000 26.70 1005.20 30.30 24.80 72.00 19.60 2.20 40.00 -1.41 -1.69 0.00 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99
+2001/07/01 00:00 2001/07/01 00:00 CAMP 46693 Chutzehu 25.16000 121.54000 607.00 941.80 25.00 22.10 84.00 17.76 0.60 340.00 0.21 -0.56 0.00 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99
+2001/07/01 00:00 2001/07/01 00:00 CAMP 46690 Tanshui 25.17000 121.43000 19.00 1006.00 29.30 25.80 81.00 20.80 0.70 280.00 0.69 -0.12 0.00 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99
+2001/07/01 00:00 2001/07/01 00:00 CAMP 46691 Anpu 25.18000 121.52000 837.60 918.20 24.10 22.30 90.00 18.44 2.90 350.00 0.50 -2.86 0.00 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99
+2001/07/01 00:00 2001/07/01 00:00 CAMP 46695 Pengchiayu 25.63000 122.07000 99.00 997.20 28.20 24.80 82.00 19.76 13.10 150.00 -6.55 11.34 0.00 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99 -999.99
diff --git a/inst/doc/gridBase.R b/inst/doc/gridBase.R
new file mode 100644
index 0000000..90a3aa0
--- /dev/null
+++ b/inst/doc/gridBase.R
@@ -0,0 +1,432 @@
+### R code from vignette source 'gridBase.Rnw'
+
+###################################################
+### code chunk number 1: gridBase.Rnw:81-84
+###################################################
+library(grid)
+library(gridBase)
+
+
+
+###################################################
+### code chunk number 2: basesetup (eval = FALSE)
+###################################################
+## midpts <- barplot(1:10, axes=FALSE)
+## axis(2)
+## axis(1, at=midpts, labels=FALSE)
+##
+
+
+###################################################
+### code chunk number 3: baseviewport (eval = FALSE)
+###################################################
+## vps <- baseViewports()
+## pushViewport(vps$inner, vps$figure, vps$plot)
+##
+
+
+###################################################
+### code chunk number 4: gridtext (eval = FALSE)
+###################################################
+## grid.text(c("one", "two", "three", "four", "five",
+## "six", "seven", "eight", "nine", "ten"),
+## x=unit(midpts, "native"), y=unit(-1, "lines"),
+## just="right", rot=60)
+## popViewport(3)
+##
+
+
+###################################################
+### code chunk number 5: gridBase.Rnw:110-114
+###################################################
+midpts <- barplot(1:10, axes=FALSE)
+axis(2)
+axis(1, at=midpts, labels=FALSE)
+
+vps <- baseViewports()
+pushViewport(vps$inner, vps$figure, vps$plot)
+
+grid.text(c("one", "two", "three", "four", "five",
+ "six", "seven", "eight", "nine", "ten"),
+ x=unit(midpts, "native"), y=unit(-1, "lines"),
+ just="right", rot=60)
+popViewport(3)
+
+
+
+
+###################################################
+### code chunk number 6: plotsymbol (eval = FALSE)
+###################################################
+## novelsym <- function(speed, temp,
+## width=unit(3, "mm"),
+## length=unit(0.5, "inches")) {
+## grid.rect(height=length, y=0.5,
+## just="top", width=width,
+## gp=gpar(fill="white"))
+## grid.rect(height=temp*length,
+## y=unit(0.5, "npc") - length,
+## width=width,
+## just="bottom", gp=gpar(fill="grey"))
+## grid.lines(x=0.5,
+## y=unit.c(unit(0.5, "npc"), unit(0.5, "npc") + speed*length),
+## arrow=arrow(length=unit(3, "mm"), type="closed"),
+## gp=gpar(fill="black"))
+## grid.points(unit(0.5, "npc"), unit(0.5, "npc"), size=unit(2, "mm"),
+## pch=16)
+## }
+##
+
+
+###################################################
+### code chunk number 7: baseplot (eval = FALSE)
+###################################################
+## chinasea <- read.table(system.file("doc", "chinasea.txt",
+## package="gridBase"),
+## header=TRUE)
+## plot(chinasea$lat, chinasea$long, type="n",
+## xlab="latitude", ylab="longitude",
+## main="China Sea Wind Speed/Direction and Temperature")
+##
+
+
+###################################################
+### code chunk number 8: gridsym (eval = FALSE)
+###################################################
+## speed <- 0.8*chinasea$speed/14 + 0.2
+## temp <- chinasea$temp/40
+## vps <- baseViewports()
+## pushViewport(vps$inner, vps$figure, vps$plot)
+## for (i in 1:25) {
+## pushViewport(viewport(x=unit(chinasea$lat[i], "native"),
+## y=unit(chinasea$long[i], "native"),
+## angle=chinasea$dir[i]))
+## novelsym(speed[i], temp[i])
+## popViewport()
+## }
+## popViewport(3)
+##
+
+
+###################################################
+### code chunk number 9: gridBase.Rnw:184-188
+###################################################
+novelsym <- function(speed, temp,
+ width=unit(3, "mm"),
+ length=unit(0.5, "inches")) {
+ grid.rect(height=length, y=0.5,
+ just="top", width=width,
+ gp=gpar(fill="white"))
+ grid.rect(height=temp*length,
+ y=unit(0.5, "npc") - length,
+ width=width,
+ just="bottom", gp=gpar(fill="grey"))
+ grid.lines(x=0.5,
+ y=unit.c(unit(0.5, "npc"), unit(0.5, "npc") + speed*length),
+ arrow=arrow(length=unit(3, "mm"), type="closed"),
+ gp=gpar(fill="black"))
+ grid.points(unit(0.5, "npc"), unit(0.5, "npc"), size=unit(2, "mm"),
+ pch=16)
+}
+
+chinasea <- read.table(system.file("doc", "chinasea.txt",
+ package="gridBase"),
+ header=TRUE)
+plot(chinasea$lat, chinasea$long, type="n",
+ xlab="latitude", ylab="longitude",
+ main="China Sea Wind Speed/Direction and Temperature")
+
+speed <- 0.8*chinasea$speed/14 + 0.2
+temp <- chinasea$temp/40
+vps <- baseViewports()
+pushViewport(vps$inner, vps$figure, vps$plot)
+for (i in 1:25) {
+ pushViewport(viewport(x=unit(chinasea$lat[i], "native"),
+ y=unit(chinasea$long[i], "native"),
+ angle=chinasea$dir[i]))
+ novelsym(speed[i], temp[i])
+ popViewport()
+}
+popViewport(3)
+
+
+
+
+###################################################
+### code chunk number 10: gridBase.Rnw:220-225
+###################################################
+ data(USArrests)
+ hc <- hclust(dist(USArrests), "ave")
+ dend1 <- as.dendrogram(hc)
+ dend2 <- cut(dend1, h=70)
+
+
+
+###################################################
+### code chunk number 11: gridBase.Rnw:229-233
+###################################################
+x <- 1:4
+y <- 1:4
+height <- factor(round(unlist(lapply(dend2$lower, attr, "height"))))
+
+
+
+###################################################
+### code chunk number 12: gridBase.Rnw:248-260
+###################################################
+space <- max(unit(rep(1, 50), "strwidth",
+ as.list(rownames(USArrests))))
+dendpanel <- function(x, y, subscripts, ...) {
+ pushViewport(viewport(y=space, width=0.9,
+ height=unit(0.9, "npc") - space,
+ just="bottom"))
+ grid.rect(gp=gpar(col="grey", lwd=5))
+ par(plt=gridPLT(), new=TRUE, ps=10)
+ plot(dend2$lower[[subscripts]], axes=FALSE)
+ popViewport()
+}
+
+
+
+###################################################
+### code chunk number 13: gridBase.Rnw:266-273
+###################################################
+library(lattice)
+plot.new()
+print(xyplot(y ~ x | height, subscripts=TRUE, xlab="", ylab="",
+ strip=function(...) { strip.default(style=4, ...) },
+ scales=list(draw=FALSE), panel=dendpanel),
+ newpage=FALSE)
+
+
+
+###################################################
+### code chunk number 14: gridBase.Rnw:290-294
+###################################################
+ counts <- c(18,17,15,20,10,20,25,13,12)
+ outcome <- gl(3,1,9)
+ treatment <- gl(3,3)
+
+
+
+###################################################
+### code chunk number 15: gridBase.Rnw:302-304
+###################################################
+oldpar <- par(no.readonly=TRUE)
+
+
+
+###################################################
+### code chunk number 16: regions (eval = FALSE)
+###################################################
+## pushViewport(viewport(layout=grid.layout(1, 3,
+## widths=unit(rep(1, 3), c("null", "cm", "null")))))
+##
+
+
+###################################################
+### code chunk number 17: lattice (eval = FALSE)
+###################################################
+## pushViewport(viewport(layout.pos.col=1))
+## library(lattice)
+## bwplot <- bwplot(counts ~ outcome | treatment)
+## print(bwplot, newpage=FALSE)
+## popViewport()
+##
+
+
+###################################################
+### code chunk number 18: diagnostic (eval = FALSE)
+###################################################
+## pushViewport(viewport(layout.pos.col=3))
+## glm.D93 <- glm(counts ~ outcome + treatment, family=poisson())
+## par(omi=gridOMI(), mfrow=c(2, 2), new=TRUE)
+## par(cex=0.5, mar=c(5, 4, 1, 2))
+## par(mfg=c(1, 1))
+## plot(glm.D93, caption="", ask=FALSE)
+## popViewport(2)
+##
+
+
+###################################################
+### code chunk number 19: multiplot
+###################################################
+pushViewport(viewport(layout=grid.layout(1, 3,
+ widths=unit(rep(1, 3), c("null", "cm", "null")))))
+
+pushViewport(viewport(layout.pos.col=1))
+library(lattice)
+bwplot <- bwplot(counts ~ outcome | treatment)
+print(bwplot, newpage=FALSE)
+popViewport()
+
+pushViewport(viewport(layout.pos.col=3))
+ glm.D93 <- glm(counts ~ outcome + treatment, family=poisson())
+ par(omi=gridOMI(), mfrow=c(2, 2), new=TRUE)
+ par(cex=0.5, mar=c(5, 4, 1, 2))
+ par(mfg=c(1, 1))
+ plot(glm.D93, caption="", ask=FALSE)
+popViewport(2)
+
+
+
+
+###################################################
+### code chunk number 20: gridBase.Rnw:346-348
+###################################################
+par(oldpar)
+
+
+
+###################################################
+### code chunk number 21: gridBase.Rnw:375-379
+###################################################
+x <- c(0.88, 1.00, 0.67, 0.34)
+y <- c(0.87, 0.43, 0.04, 0.94)
+z <- matrix(runif(4*2), ncol=2)
+
+
+
+###################################################
+### code chunk number 22: gridBase.Rnw:386-388
+###################################################
+oldpar <- par(no.readonly=TRUE)
+
+
+
+###################################################
+### code chunk number 23: plot1 (eval = FALSE)
+###################################################
+## plot(x, y, xlim=c(-0.2, 1.2), ylim=c(-0.2, 1.2), type="n")
+##
+
+
+###################################################
+### code chunk number 24: plot2 (eval = FALSE)
+###################################################
+## vps <- baseViewports()
+## pushViewport(vps$inner, vps$figure, vps$plot)
+## grid.segments(x0=unit(c(rep(0, 4), x),
+## rep(c("npc", "native"), each=4)),
+## x1=unit(c(x, x), rep("native", 8)),
+## y0=unit(c(y, rep(0, 4)),
+## rep(c("native", "npc"), each=4)),
+## y1=unit(c(y, y), rep("native", 8)),
+## gp=gpar(lty="dashed", col="grey"))
+##
+
+
+###################################################
+### code chunk number 25: gridBase.Rnw:427-431
+###################################################
+maxpiesize <- unit(1, "inches")
+totals <- apply(z, 1, sum)
+sizemult <- totals/max(totals)
+
+
+
+###################################################
+### code chunk number 26: plot3 (eval = FALSE)
+###################################################
+## for (i in 1:4) {
+## pushViewport(viewport(x=unit(x[i], "native"),
+## y=unit(y[i], "native"),
+## width=sizemult[i]*maxpiesize,
+## height=sizemult[i]*maxpiesize))
+## grid.rect(gp=gpar(col="grey", fill="white", lty="dashed"))
+## par(plt=gridPLT(), new=TRUE)
+## pie(z[i,], radius=1, labels=rep("", 2))
+## popViewport()
+## }
+##
+
+
+###################################################
+### code chunk number 27: plot4 (eval = FALSE)
+###################################################
+## popViewport(3)
+## par(oldpar)
+##
+
+
+###################################################
+### code chunk number 28: complex
+###################################################
+plot(x, y, xlim=c(-0.2, 1.2), ylim=c(-0.2, 1.2), type="n")
+
+vps <- baseViewports()
+pushViewport(vps$inner, vps$figure, vps$plot)
+grid.segments(x0=unit(c(rep(0, 4), x),
+ rep(c("npc", "native"), each=4)),
+ x1=unit(c(x, x), rep("native", 8)),
+ y0=unit(c(y, rep(0, 4)),
+ rep(c("native", "npc"), each=4)),
+ y1=unit(c(y, y), rep("native", 8)),
+ gp=gpar(lty="dashed", col="grey"))
+
+for (i in 1:4) {
+ pushViewport(viewport(x=unit(x[i], "native"),
+ y=unit(y[i], "native"),
+ width=sizemult[i]*maxpiesize,
+ height=sizemult[i]*maxpiesize))
+ grid.rect(gp=gpar(col="grey", fill="white", lty="dashed"))
+ par(plt=gridPLT(), new=TRUE)
+ pie(z[i,], radius=1, labels=rep("", 2))
+ popViewport()
+}
+
+popViewport(3)
+par(oldpar)
+
+
+
+
+###################################################
+### code chunk number 29: gridBase.Rnw:544-549
+###################################################
+ ctl <- c(4.17,5.58,5.18,6.11,4.50,4.61,5.17,4.53,5.33,5.14)
+ trt <- c(4.81,4.17,4.41,3.59,5.87,3.83,6.03,4.89,4.32,4.69)
+ group <- gl(2,10,20, labels=c("Ctl","Trt"))
+ weight <- c(ctl, trt)
+
+
+
+###################################################
+### code chunk number 30: gridBase.Rnw:557-559
+###################################################
+oldpar <- par(no.readonly=TRUE)
+
+
+
+###################################################
+### code chunk number 31: regions (eval = FALSE)
+###################################################
+## pushViewport(viewport(layout=grid.layout(1, 3,
+## widths=unit(rep(1, 3), c("null", "cm", "null")))))
+##
+
+
+###################################################
+### code chunk number 32: lattice (eval = FALSE)
+###################################################
+## pushViewport(viewport(layout.pos.col=1))
+## library(lattice)
+## bwplot <- bwplot(weight ~ group)
+## print(bwplot, newpage=FALSE)
+## popViewport()
+##
+
+
+###################################################
+### code chunk number 33: diagnostic (eval = FALSE)
+###################################################
+## pushViewport(viewport(layout.pos.col=3))
+## lm.D9 <- lm(weight ~ group)
+## par(omi=gridOMI(), mfrow=c(2, 2), new=TRUE)
+## par(cex=0.5)
+## par(mfg=c(1, 1))
+## plot(lm.D9, caption="", ask=FALSE)
+## popViewport(2)
+##
+
+
diff --git a/inst/doc/gridBase.Rnw b/inst/doc/gridBase.Rnw
new file mode 100644
index 0000000..79ce1f6
--- /dev/null
+++ b/inst/doc/gridBase.Rnw
@@ -0,0 +1,591 @@
+\documentclass[a4paper]{article}
+%\VignetteIndexEntry{gridBase}
+\newcommand{\grid}{{\tt grid}}
+\newcommand{\gridBase}{{\tt gridBase}}
+\newcommand{\lattice}{{\tt lattice}}
+\newcommand{\R}{{\tt R}}
+\setlength{\parindent}{0in}
+\setlength{\parskip}{.1in}
+
+\newcommand{\aside}[1]{\begin{list}{}
+ {\setlength{\leftmargin}{1in}
+ \setlength{\rightmargin}{1in}
+ \setlength{\itemindent}{0in}}
+ \item {\sc Aside:} {\it #1}
+ \end{list}}
+
+\title{Integrating Grid Graphics Output \\ with Base Graphics Output}
+\author{Paul Murrell}
+
+\begin{document}
+\maketitle
+
+@
+The \grid{} graphics package\cite{Rnews:Murrell:2002}
+ is much more powerful than the standard \R{} graphics system
+(hereafter ``base
+graphics'') when it comes to combining and arranging graphical elements.
+It is possible to create a greater variety of graphs more easily with
+\grid{} (see, for example, Deepayan Sarkar's \lattice{}
+package\cite{Rnews:Sarkar:2002}).
+However, there are very many plots based on base graphics (e.g.,
+biplots), that have not been implemented in \grid{}, and the
+task of reimplementing these in \grid{} is extremely daunting.
+It would be nice to be able to combine the
+ready-made base plots with the sophisticated arrangement features
+of grid.
+
+This document describes the \gridBase{} package which provides
+ some support for combining grid and base
+graphics output.
+
+\section*{Annotating base graphics using \grid{}}
+
+The \gridBase{} package has one function, \verb|baseViewports()|,
+that supports
+adding \grid{} output to a base graphics plot.
+This function creates a set of \grid{}
+viewports that correspond to the current
+base plot.
+This allows simple annotations such as adding lines and text using \grid{}'s
+units to locate them relative to
+a wide variety of coordinate systems, or something
+more complex involving
+pushing further \grid{} viewports.
+
+{\tt baseViewports()} returns a list of three grid viewports. The first
+corresponds to the base ``inner'' region. This viewport is relative to
+ the entire device; it only makes sense to push this viewport
+from the ``top level'' (i.e., only when no other viewports have been
+pushed).
+The second viewport corresponds to the base ``figure'' region
+and is relative to the inner region; it only makes sense to push it
+after the ``inner'' viewport has been pushed. The third
+viewport corresponds to the
+base ``plot'' region and is relative to the figure region; it only
+makes sense to push it after the other two viewports have been pushed in the
+correct order.
+
+A simple application of this facility involves adding text to
+the margins of a base plot at an arbitrary orientation. The base
+function \verb|mtext()| allows text to be located in terms of a number
+of lines away from the plot region, but only at rotations of 0 or
+90 degrees. The base \verb|text()| function allows arbitrary rotations,
+but only locates text relative to the user coordinate system in effect
+in the plot region (which is inconvenient for locating text in the
+margins of the plot). By contrast, the \grid{} function
+\verb|grid.text()| allows arbitrary rotations and can be used in
+any \grid{} viewport. In the following code we first create a base plot,
+leaving off the tick labels.
+
+<<echo=FALSE, results=hide>>=
+library(grid)
+library(gridBase)
+
+<<basesetup, eval=FALSE>>=
+midpts <- barplot(1:10, axes=FALSE)
+axis(2)
+axis(1, at=midpts, labels=FALSE)
+
+@
+Next we use \verb|baseViewports()| to
+create grid viewports that correspond to the base plot and we push
+those viewports.
+
+<<baseviewport, eval=FALSE>>=
+vps <- baseViewports()
+pushViewport(vps$inner, vps$figure, vps$plot)
+
+@
+Finally, we draw rotated labels using
+\verb|grid.text()| (and pop the viewports to clean up after ourselves).
+
+<<gridtext, eval=FALSE>>=
+grid.text(c("one", "two", "three", "four", "five",
+ "six", "seven", "eight", "nine", "ten"),
+ x=unit(midpts, "native"), y=unit(-1, "lines"),
+ just="right", rot=60)
+popViewport(3)
+
+<<fig=TRUE, echo=FALSE, results=hide>>=
+<<basesetup>>
+<<baseviewport>>
+<<gridtext>>
+
+@
+
+The next example is a bit more complicated because it involves
+embedding \grid{} viewports within a base graphics plot.
+The dataset is a snapshot of wind speed, wind direction, and temperature
+at several weather stations in the South China Sea, south west of
+Japan\footnote{Obtained from the CODIAC web site:
+{\tt http://www.joss.ucar.edu/codiac/codiac-www.html}. The file
+{\tt chinasea.txt} is in the {\tt gridBase/doc} directory.}.
+\grid{} is used to produce novel plotting symbols for a standard
+base plot.
+
+First of all, we need to define the novel plotting symbol. This consists
+of a dot at the data location, with a thermometer extending ``below''
+and an arrow extending ``above''. The thermometer is used to encode
+temperature
+and the arrow is used to indicate wind speed
+(both scaled to [0, 1]).
+
+<<plotsymbol, eval=FALSE>>=
+novelsym <- function(speed, temp,
+ width=unit(3, "mm"),
+ length=unit(0.5, "inches")) {
+ grid.rect(height=length, y=0.5,
+ just="top", width=width,
+ gp=gpar(fill="white"))
+ grid.rect(height=temp*length,
+ y=unit(0.5, "npc") - length,
+ width=width,
+ just="bottom", gp=gpar(fill="grey"))
+ grid.lines(x=0.5,
+ y=unit.c(unit(0.5, "npc"), unit(0.5, "npc") + speed*length),
+ arrow=arrow(length=unit(3, "mm"), type="closed"),
+ gp=gpar(fill="black"))
+ grid.points(unit(0.5, "npc"), unit(0.5, "npc"), size=unit(2, "mm"),
+ pch=16)
+}
+
+@
+Now we read in the data and generate a base plot, but plot no points.
+
+<<baseplot, eval=FALSE>>=
+chinasea <- read.table(system.file("doc", "chinasea.txt",
+ package="gridBase"),
+ header=TRUE)
+plot(chinasea$lat, chinasea$long, type="n",
+ xlab="latitude", ylab="longitude",
+ main="China Sea Wind Speed/Direction and Temperature")
+
+@
+Now we use \verb|baseViewports()| to align a \grid{} viewport
+with the plot region, and draw the symbols by creating a
+\grid{} viewport per $(x, y)$ location (we rotate the viewport to
+represent the wind direction).
+
+<<gridsym, eval=FALSE>>=
+speed <- 0.8*chinasea$speed/14 + 0.2
+temp <- chinasea$temp/40
+vps <- baseViewports()
+pushViewport(vps$inner, vps$figure, vps$plot)
+for (i in 1:25) {
+ pushViewport(viewport(x=unit(chinasea$lat[i], "native"),
+ y=unit(chinasea$long[i], "native"),
+ angle=chinasea$dir[i]))
+ novelsym(speed[i], temp[i])
+ popViewport()
+}
+popViewport(3)
+
+<<echo=FALSE, fig=TRUE, results=hide>>=
+<<plotsymbol>>
+<<baseplot>>
+<<gridsym>>
+
+@
+\section*{Embedding base graphics plots in \grid{} viewports}
+
+\gridBase{} provides several functions for adding base graphics
+output to \grid{} output. There are three functions that allow
+base plotting regions to be aligned with the current \grid{}
+viewport; this makes it possible to draw one or more base graphics plots
+within
+a \grid{} viewport. The fourth function provides a set of
+graphical parameter settings so that base {\tt par()} settings
+can be made to correspond to some of\footnote{Only {\tt lwd},
+{\tt lty}, {\tt col} are available yet. More should be available in
+future versions.} the current \grid{} graphical parameter settings.
+
+The first three functions are \verb|gridOMI()|, \verb|gridFIG()|,
+and \verb|gridPLT()|. They return the appropriate
+\verb|par()| values for setting the base ``inner'', ``figure'',
+and ``plot'' regions, respectively.
+
+The main usefulness of these functions is to allow you to create a
+complex layout using \grid{} and then draw a base plot within
+relevant elements of that layout. The following example
+uses this idea to create a \lattice{} plot where the panels contain
+dendrograms drawn using base graphics functions\footnote{Recall
+that \lattice{} is built on \grid{} so the panel region in
+a \lattice{} plot is a \grid{} viewport.}.
+
+First of all, we create a dendrogram and cut it into four
+subtrees\footnote{the data and cluster analysis are copied from the example
+in {\tt help(plot.dendrogram)}.}.
+
+<<eval=TRUE>>=
+ data(USArrests)
+ hc <- hclust(dist(USArrests), "ave")
+ dend1 <- as.dendrogram(hc)
+ dend2 <- cut(dend1, h=70)
+
+@
+Now we create some dummy variables which correspond to the four subtrees.
+
+<<>>=
+x <- 1:4
+y <- 1:4
+height <- factor(round(unlist(lapply(dend2$lower, attr, "height"))))
+
+@
+Next we define a \lattice{} panel function to draw the dendrograms.
+The first thing this panel function does is push a viewport
+that is smaller than the viewport \lattice{} creates for the panel;
+the purpose is to ensure there is enough room for the labels on
+the dendrogram. The \verb|space| variable contains a measure
+of the length of the longest label.
+The panel function then calls \verb|gridPLT()|
+and makes the base plot region correspond to the
+viewport we have just pushed. Finally, we
+call the base \verb|plot()| function to draw the
+dendrogram (and pop the viewport we pushed)\footnote{The {\tt grid.rect()}
+call is just to show the extent of the extra viewport we pushed.}.
+
+<<>>=
+space <- max(unit(rep(1, 50), "strwidth",
+ as.list(rownames(USArrests))))
+dendpanel <- function(x, y, subscripts, ...) {
+ pushViewport(viewport(y=space, width=0.9,
+ height=unit(0.9, "npc") - space,
+ just="bottom"))
+ grid.rect(gp=gpar(col="grey", lwd=5))
+ par(plt=gridPLT(), new=TRUE, ps=10)
+ plot(dend2$lower[[subscripts]], axes=FALSE)
+ popViewport()
+}
+
+@
+Finally, we draw a \lattice{} xyplot, using \lattice{} to set up the
+arrangement of panels and strips and our panel function to draw
+a base dendrogram in each panel.
+
+<<echo=FALSE, results=hide, fig=TRUE>>=
+library(lattice)
+plot.new()
+print(xyplot(y ~ x | height, subscripts=TRUE, xlab="", ylab="",
+ strip=function(...) { strip.default(style=4, ...) },
+ scales=list(draw=FALSE), panel=dendpanel),
+ newpage=FALSE)
+
+@
+
+The \verb|gridPLT()| function is useful for embedding just the
+plot region of a base graphics function (i.e., without labels and
+axes; another example of this usage
+is given in the next section). If labelling
+and axes are to be included it will make more sense to use
+\verb|gridFIG()|. The \verb|gridOMI()| function has pretty much
+the same effect as \verb|gridFIG()| except that it allows for the
+possibility of embedding multiple base plots at once. In the
+following code, a \lattice{} plot is placed alongside
+base diagnostic plots arranged in a 2-by-2 array.
+
+We use the data from page 93 of
+``An Introduction to Generalized Linear Models'' (Annette Dobson, 1990).
+
+<<>>=
+ counts <- c(18,17,15,20,10,20,25,13,12)
+ outcome <- gl(3,1,9)
+ treatment <- gl(3,3)
+
+@
+We create two regions using \grid{} viewports; the left region
+is for the \lattice{} plot and the right region is for the diagnostic
+plots. There is a middle column of 1cm to provide a gap between
+the two regions.
+
+% Save and restore settings so that vignette building will work(?)
+<<echo=FALSE>>=
+oldpar <- par(no.readonly=TRUE)
+
+<<regions, eval=FALSE>>=
+pushViewport(viewport(layout=grid.layout(1, 3,
+ widths=unit(rep(1, 3), c("null", "cm", "null")))))
+
+@
+We draw a \lattice{} plot in the left region.
+
+<<lattice, eval=FALSE>>=
+pushViewport(viewport(layout.pos.col=1))
+library(lattice)
+bwplot <- bwplot(counts ~ outcome | treatment)
+print(bwplot, newpage=FALSE)
+popViewport()
+
+@
+We draw the diagnostic plots in the right region. Here
+we use \verb|gridOMI()| to set the base inner region and
+\verb|par(mfrow)| and
+\verb|par(mfg)| to insert multiple plots\footnote{We use
+{\tt par(mfrow)} to specify the 2-by-2 array
+and {\tt par(mfg)} to start at position $(1,1)$ in the
+array.}.
+
+<<diagnostic, eval=FALSE>>=
+pushViewport(viewport(layout.pos.col=3))
+ glm.D93 <- glm(counts ~ outcome + treatment, family=poisson())
+ par(omi=gridOMI(), mfrow=c(2, 2), new=TRUE)
+ par(cex=0.5, mar=c(5, 4, 1, 2))
+ par(mfg=c(1, 1))
+ plot(glm.D93, caption="", ask=FALSE)
+popViewport(2)
+
+<<multiplot, echo=FALSE, results=hide, fig=TRUE, width=8, height=4, include=FALSE>>=
+<<regions>>
+<<lattice>>
+<<diagnostic>>
+
+@
+\includegraphics[width=5in]{gridBase-multiplot}
+
+% Save and restore settings so that vignette building will work(?)
+<<echo=FALSE>>=
+par(oldpar)
+
+@
+Notice that because there is only ever one current \grid{} viewport, it only
+makes sense to use one of \verb|gridOMI()|, \verb|gridFIG()|, or
+\verb|gridPLT()|. In other words, it only makes sense to
+align either the inner region, or the figure region, or the plot
+region with the current \grid{} viewport.
+
+@
+\section*{A more complex example}
+
+We will now look at a reasonably complex example involving
+embedding base graphics within grid viewports which are themselves
+embedded within a base plot. This example is motivated by
+ the following problem\footnote{This description is from an email to
+R-help from Adam Langley, 18 July 2003}:
+
+\begin{quote}
+I am looking at a way of plotting a series of pie charts at specified
+locations on an existing plot. The size of the pie chart would be proportion
+to the magnitude of the total value of each vector (x) and the values in x
+are displayed as the areas of pie slices.
+\end{quote}
+
+First of all, we construct some fake data, consisting of four
+$(x, y)$ values, and four $(z_1, z_2)$ values :
+
+<<>>=
+x <- c(0.88, 1.00, 0.67, 0.34)
+y <- c(0.87, 0.43, 0.04, 0.94)
+z <- matrix(runif(4*2), ncol=2)
+
+@
+Before we start any plotting, we save the current \verb|par()|
+settings so that at the end
+we can ``undo'' some of the complicated settings
+that we need to apply.
+
+<<>>=
+oldpar <- par(no.readonly=TRUE)
+
+@
+Now we do a standard base plot of the $(x, y)$ values, but do not
+plot anything at these locations (we're just setting up the
+user coordinate system).
+
+<<plot1, eval=FALSE>>=
+plot(x, y, xlim=c(-0.2, 1.2), ylim=c(-0.2, 1.2), type="n")
+
+@
+Now we make use of \verb|baseViewports|.
+This will create a list of grid viewports that correspond to the
+inner, figure, and plot regions set up by the base plot.
+By pushing these viewports, we establish a grid viewport that aligns
+exactly with the plot region created by the base plot, including a
+(grid) ``native'' coordinate system that matches the
+(base) user coordinate system\footnote{
+The {\tt grid.segments} call is just drawing some
+dashed lines to show that the pie charts we end up with
+are centred correctly at the appropriate $(x, y)$ locations.}.
+
+<<plot2, eval=FALSE>>=
+vps <- baseViewports()
+pushViewport(vps$inner, vps$figure, vps$plot)
+grid.segments(x0=unit(c(rep(0, 4), x),
+ rep(c("npc", "native"), each=4)),
+ x1=unit(c(x, x), rep("native", 8)),
+ y0=unit(c(y, rep(0, 4)),
+ rep(c("native", "npc"), each=4)),
+ y1=unit(c(y, y), rep("native", 8)),
+ gp=gpar(lty="dashed", col="grey"))
+
+@
+Before we draw the pie charts, we need to perform a couple of
+calculations to determine their size. In this case, we specify that
+the largest pie will be 1\verb|"| in diameter and the others will be
+a proportion of that size based on $\sum_i{z_{.i}} /
+{\mathrm{max}}\left( \sum_i{z_{.i}} \right)$
+
+<<>>=
+maxpiesize <- unit(1, "inches")
+totals <- apply(z, 1, sum)
+sizemult <- totals/max(totals)
+
+@
+We now enter a loop to draw a pie at each $(x, y)$ location
+representing the corresponding $(z_1, z_2)$ values. The first
+step is to create a grid viewport at the $(x, y)$ location,
+then we use \verb|gridPLT()|
+to set the base plot region to correspond to the grid viewport.
+With that done, we can use the base \verb|pie| function to draw a pie
+chart within the grid viewport\footnote{We draw a {\tt grid.rect}
+with a dashed border just to show the extent of each grid viewport.
+It is crucial that we again call {\tt par(new=TRUE)} so that
+we do not move on to a new page.}.
+
+<<plot3, eval=FALSE>>=
+for (i in 1:4) {
+ pushViewport(viewport(x=unit(x[i], "native"),
+ y=unit(y[i], "native"),
+ width=sizemult[i]*maxpiesize,
+ height=sizemult[i]*maxpiesize))
+ grid.rect(gp=gpar(col="grey", fill="white", lty="dashed"))
+ par(plt=gridPLT(), new=TRUE)
+ pie(z[i,], radius=1, labels=rep("", 2))
+ popViewport()
+}
+
+@
+Finally, we clean up after ourselves by popping the grid viewports
+and restoring the initial \verb|par| settings.
+
+<<plot4, eval=FALSE>>=
+popViewport(3)
+par(oldpar)
+
+@
+The final plot is shown below.
+
+<<complex, echo=FALSE, fig=TRUE, results=hide>>=
+<<plot1>>
+<<plot2>>
+<<plot3>>
+<<plot4>>
+
+@
+\section*{Problems and limitations}
+
+The functions provided by the \gridBase{} package allow the user
+to mix output from two quite different graphics systems and there
+are limits to how much the systems can be combined. It is important
+that users are aware that they are mixing two not wholly compatible
+systems (which is why these functions are provided in a separate
+package) and it is of course important to know what the limitations
+are:
+
+\begin{itemize}
+\item
+The \gridBase{} functions attempt to
+match \grid{} graphics settings with base graphics settings (and vice versa).
+ This
+is only possible under certain conditions. For a start, it is only
+possible if the device size does not change. If these functions are
+used to draw into a window, then the window is resized, the base and
+\grid{} settings will almost certainly no longer match and the graph
+will become a complete mess. This also applies to copying output between
+devices of different sizes.
+
+\item
+It is not possible to embed base graphics output within a
+\grid{} viewport that is rotated.
+
+\item
+There are certain base graphics functions
+which modify settings
+like \verb|par(omi)| and \verb|par(fig)| themselves (e.g., \verb|coplot()|).
+ Output from
+these functions may not embed properly
+within \grid{} viewports.
+
+\item
+\grid{} output cannot be
+saved and restored so any attempts to save a mixture of \grid{} and
+base output are likely
+to end in disappointment.
+
+\end{itemize}
+
+\section*{Summary}
+
+The functions in the \gridBase{} package provide a simple mechanism
+for combining base graphics output with \grid{} graphics output
+for static, fixed-size plots. This is not a full integration
+of the two graphics systems, but it does provide a useful bridge
+between the existing large body of base graphics functions and the
+powerful new features of \grid{}.
+
+
+\subsubsection*{Availability}
+
+The \grid{} package is now part of the base distribution of \R{}
+(from \R{} version 1.8.0). \\
+Additional information on \grid{}
+is available from:\\
+ {\tt http://www.stat.auckland.ac.nz/~paul/grid/grid.html}. \\
+The \gridBase{} package
+is available from \verb|CRAN| (e.g., {\tt http://cran.us.r-project.org}).
+
+\bibliographystyle{plain}
+\bibliography{gridBase}
+
+\end{document}
+
+We use the Plant Weight Data from
+``An Introduction to Generalized Linear Models'' (Annette Dobson, 1990).
+
+<<>>=
+ ctl <- c(4.17,5.58,5.18,6.11,4.50,4.61,5.17,4.53,5.33,5.14)
+ trt <- c(4.81,4.17,4.41,3.59,5.87,3.83,6.03,4.89,4.32,4.69)
+ group <- gl(2,10,20, labels=c("Ctl","Trt"))
+ weight <- c(ctl, trt)
+
+@
+We create two regions using \grid{} viewports; the left region
+is for the \lattice{} plot and the right region is for the diagnostic
+plots. There is a middle column of 1cm to provide a gap between
+the two regions.
+
+% Save and restore settings so that vignette building will work(?)
+<<echo=FALSE>>=
+oldpar <- par(no.readonly=TRUE)
+
+<<regions, eval=FALSE>>=
+pushViewport(viewport(layout=grid.layout(1, 3,
+ widths=unit(rep(1, 3), c("null", "cm", "null")))))
+
+@
+We draw a \lattice{} plot in the left region.
+
+<<lattice, eval=FALSE>>=
+pushViewport(viewport(layout.pos.col=1))
+library(lattice)
+bwplot <- bwplot(weight ~ group)
+print(bwplot, newpage=FALSE)
+popViewport()
+
+@
+We draw the diagnostic plots in the right region. Here
+we use \verb|gridOMI()| to set the base inner region and
+\verb|par(mfrow)| and
+\verb|par(mfg)| to insert multiple plots\footnote{We use
+{\tt par(mfrow)} to specify the 2-by-2 array
+and {\tt par(mfg)} to start at position $(1,1)$ in the
+array.}.
+
+<<diagnostic, eval=FALSE>>=
+pushViewport(viewport(layout.pos.col=3))
+ lm.D9 <- lm(weight ~ group)
+ par(omi=gridOMI(), mfrow=c(2, 2), new=TRUE)
+ par(cex=0.5)
+ par(mfg=c(1, 1))
+ plot(lm.D9, caption="", ask=FALSE)
+popViewport(2)
+
diff --git a/inst/doc/gridBase.pdf b/inst/doc/gridBase.pdf
new file mode 100644
index 0000000..90ed22c
Binary files /dev/null and b/inst/doc/gridBase.pdf differ
diff --git a/man/baseViewports.Rd b/man/baseViewports.Rd
new file mode 100644
index 0000000..32b8396
--- /dev/null
+++ b/man/baseViewports.Rd
@@ -0,0 +1,46 @@
+\name{baseViewports}
+\alias{baseViewports}
+%- Also NEED an '\alias' for EACH other topic documented here.
+\title{ Generate grid Viewports from Base Plot }
+\description{
+ This will generate a list of grid viewports which correspond
+ to the current inner, figure, and plot regions of the current
+ base plot.
+}
+\usage{
+baseViewports()
+}
+\details{
+ The figure region is relative to the inner region so you
+ must push the inner region before pushing the figure region.
+ Similarly, the plot region is relative to the figure region
+ so this should only be pushed after the previous two.
+ }
+%- maybe also 'usage' for other objects documented here.
+\value{
+ A list with three elements:
+ \item{inner }{A viewport corresponding to the inner region
+ of the current plot.}
+ \item{figure }{A viewport corresponding to the figure region
+ of the current plot.}
+ \item{plot }{A viewport corresponding to the plot region
+ of the current plot.}
+}
+\author{ Paul Murrell }
+
+\section{Warning}{ If you resize the device, all bets are off! }
+\seealso{ \link{Grid}, \code{\link{viewport}} }
+\examples{
+library(grid)
+par(oma=rep(1, 4), mfrow=c(1, 2), xpd=NA)
+plot(1:10)
+vps <- baseViewports()
+pushViewport(vps$inner)
+grid.rect(gp=gpar(lwd=3, col="red"))
+pushViewport(vps$figure)
+grid.rect(gp=gpar(lwd=3, col="green"))
+pushViewport(vps$plot)
+grid.rect(gp=gpar(lwd=3, col="blue"))
+grid.points(1:10, 10:1)
+}
+\keyword{ dplot }% at least one, from doc/KEYWORDS
diff --git a/man/gridOMI.Rd b/man/gridOMI.Rd
new file mode 100644
index 0000000..d5c51c9
--- /dev/null
+++ b/man/gridOMI.Rd
@@ -0,0 +1,107 @@
+\name{Set Base Plot Regions}
+\alias{gridOMI}
+\alias{gridFIG}
+\alias{gridPLT}
+\alias{gridPAR}
+%- Also NEED an '\alias' for EACH other topic documented here.
+\title{ Set Base Plotting Regions from Grid Viewport }
+\description{
+ These functions can be used to align base plotting regions
+ with the current grid
+ viewport. This can be used to draw base plots within a grid viewport.
+}
+\usage{
+gridOMI()
+gridFIG()
+gridPLT()
+gridPAR()
+}
+\details{
+ For this to be useful, you will have to make liberal use of
+ \code{par(new=TRUE)} to prevent base from moving to a new page.
+
+ With care, these can even be used to draw multiple base plots within
+ a grid viewport (see the examples below), but in general, base
+ plotting functions that draw multiple panels (e.g., \code{coplot})
+ should not be
+ expected to work.
+}
+%- maybe also 'usage' for other objects documented here.
+\value{
+ \code{gridOMI} returns a value that can be used to set the
+ \code{par(omi)} parameter.
+
+ \code{gridFIG} returns a value that can be used to set the
+ \code{par(fig)} parameter.
+
+ \code{gridPLT} returns a value that can be used to set the
+ \code{par(plt)} parameter.
+
+ \code{gridPAR} returns a value that can be used to set
+ some graphical parameters (currently, \code{lwd}, \code{lty},
+ and \code{col}).
+}
+\author{ Paul Murrell }
+
+\section{Warning}{ If you resize the device, all bets are off! }
+\seealso{ \link{Grid}, \code{\link{viewport}} }
+\examples{
+library(grid)
+opar <- par(no.readonly=TRUE)
+# gridFIG
+grid.newpage()
+pushViewport(viewport(width=0.5, height=0.5))
+grid.rect(gp=gpar(col="grey", lty="dashed"))
+par(fig=gridFIG())
+par(new=TRUE)
+plot(1:10)
+# multiple plots
+# NOTE the use of par(mfg)
+# gridOMI
+par(opar)
+grid.newpage()
+pushViewport(viewport(width=0.5, height=0.5))
+grid.rect(gp=gpar(col="grey", lty="dashed"))
+par(omi=gridOMI())
+par(mfrow=c(2, 2), mfg=c(1, 1), mar=c(3, 3, 1, 0))
+for (i in 1:4) {
+ plot(i)
+}
+# gridPLT
+par(opar)
+grid.newpage()
+pushViewport(viewport(width=0.5, height=0.5))
+grid.rect(gp=gpar(col="grey", lwd=5))
+par(plt=gridPLT())
+par(new=TRUE)
+plot(1:10)
+# gridFIG with par(omi) set
+par(opar)
+grid.newpage()
+par(omi=rep(1, 4))
+pushViewport(viewport(width=0.5, height=0.5))
+grid.rect(gp=gpar(col="grey", lwd=5))
+par(fig=gridFIG())
+par(new=TRUE)
+plot(1:10)
+# gridPLT with par(omi) set
+par(opar)
+grid.newpage()
+par(omi=rep(1, 4))
+pushViewport(viewport(width=0.5, height=0.5))
+grid.rect(gp=gpar(col="grey", lwd=5))
+par(plt=gridPLT())
+par(new=TRUE)
+plot(1:10)
+# gridPAR
+par(opar)
+grid.newpage()
+pushViewport(viewport(width=0.5, height=0.5,
+ gp=gpar(col="red", lwd=3, lty="dotted")))
+grid.rect(gp=gpar(col="grey", lwd=5))
+par(fig=gridFIG())
+par(gridPAR())
+par(new=TRUE)
+plot(1:10, type="b")
+}
+\keyword{ dplot }% at least one, from doc/KEYWORDS
diff --git a/vignettes/gridBase.Rnw b/vignettes/gridBase.Rnw
new file mode 100644
index 0000000..79ce1f6
--- /dev/null
+++ b/vignettes/gridBase.Rnw
@@ -0,0 +1,591 @@
+\documentclass[a4paper]{article}
+%\VignetteIndexEntry{gridBase}
+\newcommand{\grid}{{\tt grid}}
+\newcommand{\gridBase}{{\tt gridBase}}
+\newcommand{\lattice}{{\tt lattice}}
+\newcommand{\R}{{\tt R}}
+\setlength{\parindent}{0in}
+\setlength{\parskip}{.1in}
+
+\newcommand{\aside}[1]{\begin{list}{}
+ {\setlength{\leftmargin}{1in}
+ \setlength{\rightmargin}{1in}
+ \setlength{\itemindent}{0in}}
+ \item {\sc Aside:} {\it #1}
+ \end{list}}
+
+\title{Integrating Grid Graphics Output \\ with Base Graphics Output}
+\author{Paul Murrell}
+
+\begin{document}
+\maketitle
+
+@
+The \grid{} graphics package\cite{Rnews:Murrell:2002}
+ is much more powerful than the standard \R{} graphics system
+(hereafter ``base
+graphics'') when it comes to combining and arranging graphical elements.
+It is possible to create a greater variety of graphs more easily with
+\grid{} (see, for example, Deepayan Sarkar's \lattice{}
+package\cite{Rnews:Sarkar:2002}).
+However, there are very many plots based on base graphics (e.g.,
+biplots), that have not been implemented in \grid{}, and the
+task of reimplementing these in \grid{} is extremely daunting.
+It would be nice to be able to combine the
+ready-made base plots with the sophisticated arrangement features
+of grid.
+
+This document describes the \gridBase{} package which provides
+ some support for combining grid and base
+graphics output.
+
+\section*{Annotating base graphics using \grid{}}
+
+The \gridBase{} package has one function, \verb|baseViewports()|,
+that supports
+adding \grid{} output to a base graphics plot.
+This function creates a set of \grid{}
+viewports that correspond to the current
+base plot.
+This allows simple annotations such as adding lines and text using \grid{}'s
+units to locate them relative to
+a wide variety of coordinate systems, or something
+more complex involving
+pushing further \grid{} viewports.
+
+{\tt baseViewports()} returns a list of three grid viewports. The first
+corresponds to the base ``inner'' region. This viewport is relative to
+ the entire device; it only makes sense to push this viewport
+from the ``top level'' (i.e., only when no other viewports have been
+pushed).
+The second viewport corresponds to the base ``figure'' region
+and is relative to the inner region; it only makes sense to push it
+after the ``inner'' viewport has been pushed. The third
+viewport corresponds to the
+base ``plot'' region and is relative to the figure region; it only
+makes sense to push it after the other two viewports have been pushed in the
+correct order.
+
+A simple application of this facility involves adding text to
+the margins of a base plot at an arbitrary orientation. The base
+function \verb|mtext()| allows text to be located in terms of a number
+of lines away from the plot region, but only at rotations of 0 or
+90 degrees. The base \verb|text()| function allows arbitrary rotations,
+but only locates text relative to the user coordinate system in effect
+in the plot region (which is inconvenient for locating text in the
+margins of the plot). By contrast, the \grid{} function
+\verb|grid.text()| allows arbitrary rotations and can be used in
+any \grid{} viewport. In the following code we first create a base plot,
+leaving off the tick labels.
+
+<<echo=FALSE, results=hide>>=
+library(grid)
+library(gridBase)
+
+<<basesetup, eval=FALSE>>=
+midpts <- barplot(1:10, axes=FALSE)
+axis(2)
+axis(1, at=midpts, labels=FALSE)
+
+@
+Next we use \verb|baseViewports()| to
+create grid viewports that correspond to the base plot and we push
+those viewports.
+
+<<baseviewport, eval=FALSE>>=
+vps <- baseViewports()
+pushViewport(vps$inner, vps$figure, vps$plot)
+
+@
+Finally, we draw rotated labels using
+\verb|grid.text()| (and pop the viewports to clean up after ourselves).
+
+<<gridtext, eval=FALSE>>=
+grid.text(c("one", "two", "three", "four", "five",
+ "six", "seven", "eight", "nine", "ten"),
+ x=unit(midpts, "native"), y=unit(-1, "lines"),
+ just="right", rot=60)
+popViewport(3)
+
+<<fig=TRUE, echo=FALSE, results=hide>>=
+<<basesetup>>
+<<baseviewport>>
+<<gridtext>>
+
+@
+
+The next example is a bit more complicated because it involves
+embedding \grid{} viewports within a base graphics plot.
+The dataset is a snapshot of wind speed, wind direction, and temperature
+at several weather stations in the South China Sea, south west of
+Japan\footnote{Obtained from the CODIAC web site:
+{\tt http://www.joss.ucar.edu/codiac/codiac-www.html}. The file
+{\tt chinasea.txt} is in the {\tt gridBase/doc} directory.}.
+\grid{} is used to produce novel plotting symbols for a standard
+base plot.
+
+First of all, we need to define the novel plotting symbol. This consists
+of a dot at the data location, with a thermometer extending ``below''
+and an arrow extending ``above''. The thermometer is used to encode
+temperature
+and the arrow is used to indicate wind speed
+(both scaled to [0, 1]).
+
+<<plotsymbol, eval=FALSE>>=
+novelsym <- function(speed, temp,
+ width=unit(3, "mm"),
+ length=unit(0.5, "inches")) {
+ grid.rect(height=length, y=0.5,
+ just="top", width=width,
+ gp=gpar(fill="white"))
+ grid.rect(height=temp*length,
+ y=unit(0.5, "npc") - length,
+ width=width,
+ just="bottom", gp=gpar(fill="grey"))
+ grid.lines(x=0.5,
+ y=unit.c(unit(0.5, "npc"), unit(0.5, "npc") + speed*length),
+ arrow=arrow(length=unit(3, "mm"), type="closed"),
+ gp=gpar(fill="black"))
+ grid.points(unit(0.5, "npc"), unit(0.5, "npc"), size=unit(2, "mm"),
+ pch=16)
+}
+
+@
+Now we read in the data and generate a base plot, but plot no points.
+
+<<baseplot, eval=FALSE>>=
+chinasea <- read.table(system.file("doc", "chinasea.txt",
+ package="gridBase"),
+ header=TRUE)
+plot(chinasea$lat, chinasea$long, type="n",
+ xlab="latitude", ylab="longitude",
+ main="China Sea Wind Speed/Direction and Temperature")
+
+@
+Now we use \verb|baseViewports()| to align a \grid{} viewport
+with the plot region, and draw the symbols by creating a
+\grid{} viewport per $(x, y)$ location (we rotate the viewport to
+represent the wind direction).
+
+<<gridsym, eval=FALSE>>=
+speed <- 0.8*chinasea$speed/14 + 0.2
+temp <- chinasea$temp/40
+vps <- baseViewports()
+pushViewport(vps$inner, vps$figure, vps$plot)
+for (i in 1:25) {
+ pushViewport(viewport(x=unit(chinasea$lat[i], "native"),
+ y=unit(chinasea$long[i], "native"),
+ angle=chinasea$dir[i]))
+ novelsym(speed[i], temp[i])
+ popViewport()
+}
+popViewport(3)
+
+<<echo=FALSE, fig=TRUE, results=hide>>=
+<<plotsymbol>>
+<<baseplot>>
+<<gridsym>>
+
+@
+\section*{Embedding base graphics plots in \grid{} viewports}
+
+\gridBase{} provides several functions for adding base graphics
+output to \grid{} output. There are three functions that allow
+base plotting regions to be aligned with the current \grid{}
+viewport; this makes it possible to draw one or more base graphics plots
+within
+a \grid{} viewport. The fourth function provides a set of
+graphical parameter settings so that base {\tt par()} settings
+can be made to correspond to some of\footnote{Only {\tt lwd},
+{\tt lty}, {\tt col} are available yet. More should be available in
+future versions.} the current \grid{} graphical parameter settings.
+
+The first three functions are \verb|gridOMI()|, \verb|gridFIG()|,
+and \verb|gridPLT()|. They return the appropriate
+\verb|par()| values for setting the base ``inner'', ``figure'',
+and ``plot'' regions, respectively.
+
+The main usefulness of these functions is to allow you to create a
+complex layout using \grid{} and then draw a base plot within
+relevant elements of that layout. The following example
+uses this idea to create a \lattice{} plot where the panels contain
+dendrograms drawn using base graphics functions\footnote{Recall
+that \lattice{} is built on \grid{} so the panel region in
+a \lattice{} plot is a \grid{} viewport.}.
+
+First of all, we create a dendrogram and cut it into four
+subtrees\footnote{the data and cluster analysis are copied from the example
+in {\tt help(plot.dendrogram)}.}.
+
+<<eval=TRUE>>=
+ data(USArrests)
+ hc <- hclust(dist(USArrests), "ave")
+ dend1 <- as.dendrogram(hc)
+ dend2 <- cut(dend1, h=70)
+
+@
+Now we create some dummy variables which correspond to the four subtrees.
+
+<<>>=
+x <- 1:4
+y <- 1:4
+height <- factor(round(unlist(lapply(dend2$lower, attr, "height"))))
+
+@
+Next we define a \lattice{} panel function to draw the dendrograms.
+The first thing this panel function does is push a viewport
+that is smaller than the viewport \lattice{} creates for the panel;
+the purpose is to ensure there is enough room for the labels on
+the dendrogram. The \verb|space| variable contains a measure
+of the length of the longest label.
+The panel function then calls \verb|gridPLT()|
+and makes the base plot region correspond to the
+viewport we have just pushed. Finally, we
+call the base \verb|plot()| function to draw the
+dendrogram (and pop the viewport we pushed)\footnote{The {\tt grid.rect()}
+call is just to show the extent of the extra viewport we pushed.}.
+
+<<>>=
+space <- max(unit(rep(1, 50), "strwidth",
+ as.list(rownames(USArrests))))
+dendpanel <- function(x, y, subscripts, ...) {
+ pushViewport(viewport(y=space, width=0.9,
+ height=unit(0.9, "npc") - space,
+ just="bottom"))
+ grid.rect(gp=gpar(col="grey", lwd=5))
+ par(plt=gridPLT(), new=TRUE, ps=10)
+ plot(dend2$lower[[subscripts]], axes=FALSE)
+ popViewport()
+}
+
+@
+Finally, we draw a \lattice{} xyplot, using \lattice{} to set up the
+arrangement of panels and strips and our panel function to draw
+a base dendrogram in each panel.
+
+<<echo=FALSE, results=hide, fig=TRUE>>=
+library(lattice)
+plot.new()
+print(xyplot(y ~ x | height, subscripts=TRUE, xlab="", ylab="",
+ strip=function(...) { strip.default(style=4, ...) },
+ scales=list(draw=FALSE), panel=dendpanel),
+ newpage=FALSE)
+
+@
+
+The \verb|gridPLT()| function is useful for embedding just the
+plot region of a base graphics function (i.e., without labels and
+axes; another example of this usage
+is given in the next section). If labelling
+and axes are to be included it will make more sense to use
+\verb|gridFIG()|. The \verb|gridOMI()| function has pretty much
+the same effect as \verb|gridFIG()| except that it allows for the
+possibility of embedding multiple base plots at once. In the
+following code, a \lattice{} plot is placed alongside
+base diagnostic plots arranged in a 2-by-2 array.
+
+We use the data from page 93 of
+``An Introduction to Generalized Linear Models'' (Annette Dobson, 1990).
+
+<<>>=
+ counts <- c(18,17,15,20,10,20,25,13,12)
+ outcome <- gl(3,1,9)
+ treatment <- gl(3,3)
+
+@
+We create two regions using \grid{} viewports; the left region
+is for the \lattice{} plot and the right region is for the diagnostic
+plots. There is a middle column of 1cm to provide a gap between
+the two regions.
+
+% Save and restore settings so that vignette building will work(?)
+<<echo=FALSE>>=
+oldpar <- par(no.readonly=TRUE)
+
+<<regions, eval=FALSE>>=
+pushViewport(viewport(layout=grid.layout(1, 3,
+ widths=unit(rep(1, 3), c("null", "cm", "null")))))
+
+@
+We draw a \lattice{} plot in the left region.
+
+<<lattice, eval=FALSE>>=
+pushViewport(viewport(layout.pos.col=1))
+library(lattice)
+bwplot <- bwplot(counts ~ outcome | treatment)
+print(bwplot, newpage=FALSE)
+popViewport()
+
+@
+We draw the diagnostic plots in the right region. Here
+we use \verb|gridOMI()| to set the base inner region and
+\verb|par(mfrow)| and
+\verb|par(mfg)| to insert multiple plots\footnote{We use
+{\tt par(mfrow)} to specify the 2-by-2 array
+and {\tt par(mfg)} to start at position $(1,1)$ in the
+array.}.
+
+<<diagnostic, eval=FALSE>>=
+pushViewport(viewport(layout.pos.col=3))
+ glm.D93 <- glm(counts ~ outcome + treatment, family=poisson())
+ par(omi=gridOMI(), mfrow=c(2, 2), new=TRUE)
+ par(cex=0.5, mar=c(5, 4, 1, 2))
+ par(mfg=c(1, 1))
+ plot(glm.D93, caption="", ask=FALSE)
+popViewport(2)
+
+<<multiplot, echo=FALSE, results=hide, fig=TRUE, width=8, height=4, include=FALSE>>=
+<<regions>>
+<<lattice>>
+<<diagnostic>>
+
+@
+\includegraphics[width=5in]{gridBase-multiplot}
+
+% Save and restore settings so that vignette building will work(?)
+<<echo=FALSE>>=
+par(oldpar)
+
+@
+Notice that because there is only ever one current \grid{} viewport, it only
+makes sense to use one of \verb|gridOMI()|, \verb|gridFIG()|, or
+\verb|gridPLT()|. In other words, it only makes sense to
+align either the inner region, or the figure region, or the plot
+region with the current \grid{} viewport.
+
+@
+\section*{A more complex example}
+
+We will now look at a reasonably complex example involving
+embedding base graphics within grid viewports which are themselves
+embedded within a base plot. This example is motivated by
+ the following problem\footnote{This description is from an email to
+R-help from Adam Langley, 18 July 2003}:
+
+\begin{quote}
+I am looking at a way of plotting a series of pie charts at specified
+locations on an existing plot. The size of the pie chart would be proportion
+to the magnitude of the total value of each vector (x) and the values in x
+are displayed as the areas of pie slices.
+\end{quote}
+
+First of all, we construct some fake data, consisting of four
+$(x, y)$ values, and four $(z_1, z_2)$ values :
+
+<<>>=
+x <- c(0.88, 1.00, 0.67, 0.34)
+y <- c(0.87, 0.43, 0.04, 0.94)
+z <- matrix(runif(4*2), ncol=2)
+
+@
+Before we start any plotting, we save the current \verb|par()|
+settings so that at the end
+we can ``undo'' some of the complicated settings
+that we need to apply.
+
+<<>>=
+oldpar <- par(no.readonly=TRUE)
+
+@
+Now we do a standard base plot of the $(x, y)$ values, but do not
+plot anything at these locations (we're just setting up the
+user coordinate system).
+
+<<plot1, eval=FALSE>>=
+plot(x, y, xlim=c(-0.2, 1.2), ylim=c(-0.2, 1.2), type="n")
+
+@
+Now we make use of \verb|baseViewports|.
+This will create a list of grid viewports that correspond to the
+inner, figure, and plot regions set up by the base plot.
+By pushing these viewports, we establish a grid viewport that aligns
+exactly with the plot region created by the base plot, including a
+(grid) ``native'' coordinate system that matches the
+(base) user coordinate system\footnote{
+The {\tt grid.segments} call is just drawing some
+dashed lines to show that the pie charts we end up with
+are centred correctly at the appropriate $(x, y)$ locations.}.
+
+<<plot2, eval=FALSE>>=
+vps <- baseViewports()
+pushViewport(vps$inner, vps$figure, vps$plot)
+grid.segments(x0=unit(c(rep(0, 4), x),
+ rep(c("npc", "native"), each=4)),
+ x1=unit(c(x, x), rep("native", 8)),
+ y0=unit(c(y, rep(0, 4)),
+ rep(c("native", "npc"), each=4)),
+ y1=unit(c(y, y), rep("native", 8)),
+ gp=gpar(lty="dashed", col="grey"))
+
+@
+Before we draw the pie charts, we need to perform a couple of
+calculations to determine their size. In this case, we specify that
+the largest pie will be 1\verb|"| in diameter and the others will be
+a proportion of that size based on $\sum_i{z_{.i}} /
+{\mathrm{max}}\left( \sum_i{z_{.i}} \right)$
+
+<<>>=
+maxpiesize <- unit(1, "inches")
+totals <- apply(z, 1, sum)
+sizemult <- totals/max(totals)
+
+@
+We now enter a loop to draw a pie at each $(x, y)$ location
+representing the corresponding $(z_1, z_2)$ values. The first
+step is to create a grid viewport at the $(x, y)$ location,
+then we use \verb|gridPLT()|
+to set the base plot region to correspond to the grid viewport.
+With that done, we can use the base \verb|pie| function to draw a pie
+chart within the grid viewport\footnote{We draw a {\tt grid.rect}
+with a dashed border just to show the extent of each grid viewport.
+It is crucial that we again call {\tt par(new=TRUE)} so that
+we do not move on to a new page.}.
+
+<<plot3, eval=FALSE>>=
+for (i in 1:4) {
+ pushViewport(viewport(x=unit(x[i], "native"),
+ y=unit(y[i], "native"),
+ width=sizemult[i]*maxpiesize,
+ height=sizemult[i]*maxpiesize))
+ grid.rect(gp=gpar(col="grey", fill="white", lty="dashed"))
+ par(plt=gridPLT(), new=TRUE)
+ pie(z[i,], radius=1, labels=rep("", 2))
+ popViewport()
+}
+
+@
+Finally, we clean up after ourselves by popping the grid viewports
+and restoring the initial \verb|par| settings.
+
+<<plot4, eval=FALSE>>=
+popViewport(3)
+par(oldpar)
+
+@
+The final plot is shown below.
+
+<<complex, echo=FALSE, fig=TRUE, results=hide>>=
+<<plot1>>
+<<plot2>>
+<<plot3>>
+<<plot4>>
+
+@
+\section*{Problems and limitations}
+
+The functions provided by the \gridBase{} package allow the user
+to mix output from two quite different graphics systems and there
+are limits to how much the systems can be combined. It is important
+that users are aware that they are mixing two not wholly compatible
+systems (which is why these functions are provided in a separate
+package) and it is of course important to know what the limitations
+are:
+
+\begin{itemize}
+\item
+The \gridBase{} functions attempt to
+match \grid{} graphics settings with base graphics settings (and vice versa).
+ This
+is only possible under certain conditions. For a start, it is only
+possible if the device size does not change. If these functions are
+used to draw into a window, then the window is resized, the base and
+\grid{} settings will almost certainly no longer match and the graph
+will become a complete mess. This also applies to copying output between
+devices of different sizes.
+
+\item
+It is not possible to embed base graphics output within a
+\grid{} viewport that is rotated.
+
+\item
+There are certain base graphics functions
+which modify settings
+like \verb|par(omi)| and \verb|par(fig)| themselves (e.g., \verb|coplot()|).
+ Output from
+these functions may not embed properly
+within \grid{} viewports.
+
+\item
+\grid{} output cannot be
+saved and restored so any attempts to save a mixture of \grid{} and
+base output are likely
+to end in disappointment.
+
+\end{itemize}
+
+\section*{Summary}
+
+The functions in the \gridBase{} package provide a simple mechanism
+for combining base graphics output with \grid{} graphics output
+for static, fixed-size plots. This is not a full integration
+of the two graphics systems, but it does provide a useful bridge
+between the existing large body of base graphics functions and the
+powerful new features of \grid{}.
+
+
+\subsubsection*{Availability}
+
+The \grid{} package is now part of the base distribution of \R{}
+(from \R{} version 1.8.0). \\
+Additional information on \grid{}
+is available from:\\
+ {\tt http://www.stat.auckland.ac.nz/~paul/grid/grid.html}. \\
+The \gridBase{} package
+is available from \verb|CRAN| (e.g., {\tt http://cran.us.r-project.org}).
+
+\bibliographystyle{plain}
+\bibliography{gridBase}
+
+\end{document}
+
+We use the Plant Weight Data from
+``An Introduction to Generalized Linear Models'' (Annette Dobson, 1990).
+
+<<>>=
+ ctl <- c(4.17,5.58,5.18,6.11,4.50,4.61,5.17,4.53,5.33,5.14)
+ trt <- c(4.81,4.17,4.41,3.59,5.87,3.83,6.03,4.89,4.32,4.69)
+ group <- gl(2,10,20, labels=c("Ctl","Trt"))
+ weight <- c(ctl, trt)
+
+@
+We create two regions using \grid{} viewports; the left region
+is for the \lattice{} plot and the right region is for the diagnostic
+plots. There is a middle column of 1cm to provide a gap between
+the two regions.
+
+% Save and restore settings so that vignette building will work(?)
+<<echo=FALSE>>=
+oldpar <- par(no.readonly=TRUE)
+
+<<regions, eval=FALSE>>=
+pushViewport(viewport(layout=grid.layout(1, 3,
+ widths=unit(rep(1, 3), c("null", "cm", "null")))))
+
+@
+We draw a \lattice{} plot in the left region.
+
+<<lattice, eval=FALSE>>=
+pushViewport(viewport(layout.pos.col=1))
+library(lattice)
+bwplot <- bwplot(weight ~ group)
+print(bwplot, newpage=FALSE)
+popViewport()
+
+@
+We draw the diagnostic plots in the right region. Here
+we use \verb|gridOMI()| to set the base inner region and
+\verb|par(mfrow)| and
+\verb|par(mfg)| to insert multiple plots\footnote{We use
+{\tt par(mfrow)} to specify the 2-by-2 array
+and {\tt par(mfg)} to start at position $(1,1)$ in the
+array.}.
+
+<<diagnostic, eval=FALSE>>=
+pushViewport(viewport(layout.pos.col=3))
+ lm.D9 <- lm(weight ~ group)
+ par(omi=gridOMI(), mfrow=c(2, 2), new=TRUE)
+ par(cex=0.5)
+ par(mfg=c(1, 1))
+ plot(lm.D9, caption="", ask=FALSE)
+popViewport(2)
+
diff --git a/vignettes/gridBase.bib b/vignettes/gridBase.bib
new file mode 100644
index 0000000..e1c8360
--- /dev/null
+++ b/vignettes/gridBase.bib
@@ -0,0 +1,23 @@
+ at Article{Rnews:Murrell:2002,
+ author = {Paul Murrell},
+ title = {The grid Graphics Package},
+ journal = {R News},
+ year = 2002,
+ volume = 2,
+ number = 2,
+ pages = {14--19},
+ month = {June},
+ url = {http://CRAN.R-project.org/doc/Rnews/}
+}
+
+ at Article{Rnews:Sarkar:2002,
+ author = {Deepayan Sarkar},
+ title = {Lattice},
+ journal = {R News},
+ year = 2002,
+ volume = 2,
+ number = 2,
+ pages = {19--23},
+ month = {June},
+ url = {http://CRAN.R-project.org/doc/Rnews/}
+}
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-med/r-cran-gridbase.git
More information about the debian-med-commit
mailing list