berryFunctions (version 1.16.0)

colPoints: Points colored relative to third dimension

Description

Draw colored points for 3D-data in a 2D-plane. Color is relative to third dimension, by different classification methods. Can take 3 vectors or, as in image, 2 vectors and a matrix for z.

Usage

colPoints(x, y, z, data, add = TRUE, col = seqPal(100), col2 = c(NA,
  "grey", "black"), Range = range(z, finite = TRUE), method = "linear",
  breaks = length(col), sdlab = 1, legend = TRUE, legargs = NULL,
  lines = FALSE, nint = 30, xlab = gsub("\"", "",
  deparse(substitute(x))), ylab = gsub("\"", "", deparse(substitute(y))),
  zlab = gsub("\"", "", deparse(substitute(z))), axes = TRUE, log = "",
  las = 1, bglines = NULL, pch = 16, x1 = 0.6, y1 = ifelse(horizontal,
  0.88, 0.3), x2 = 0.99, y2 = 0.99, density = NULL, horizontal = TRUE,
  quiet = FALSE, ...)

Arguments

x, y

Vectors with coordinates of the points to be drawn

z

z values belonging to coordinates. Vector or matrix with the color-defining height values

data

Optional: data.frame with the column names as given by x,y and z.

add

Logical. Should the points be added to current (existing!) plot? If FALSE, a new plot is started. DEFAULT: TRUE (It's called colPoints, after all)

col

Vector of colors to be used. DEFAULT: 100 colors from sequential palette seqPal (color-blind safe, black/white-print safe)

col2

Color for points where z is NA, or lower / higher than Range. DEFAULT: c(NA, 1, 8)

Range

Ends of color bar. If NULL, it is again the DEFAULT: range(z, finite=TRUE)

method

Classification method (partial matching is performed), see classify. DEFAULT: "linear"

breaks

Specification for method, see classify. DEFAULT: different defaults for each method

sdlab

Type of label and breakpoints if method="sd", see classify. DEFAULT: 1

legend

Logical. Should a colPointsLegend be drawn? DEFAULT: TRUE

legargs

List. Arguments passed to colPointsLegend. DEFAULT: NULL, with some defaults specified internally

lines

Logical. Should lines be drawn instead of / underneath the points? (color of each segments is taken from starting point, last point is endpoint.) If lines=TRUE and pch is not given, pch is set to NA. DEFAULT: FALSE

nint

Numeric of length 1. Number of interpolation points between each coordinate if lines=TRUE. nint=1 means no interpolation. Values below 10 will smooth coordinates and might miss the original points. DEFAULT: 30

xlab, ylab, zlab

X axis label, y axis label, colPointsLegend title. DEFAULT: gsub("\"", "", deparse(substitute(x/y/z)))

axes, las

Draw axes? Label Axis Style. Only used when add=FALSE. See par. DEFAULT: axes=TRUE, las=1 (all labels horizontal)

log

Logarithmic axes with log="y", "xy" or "x". DEFAULT: ""

bglines

If not NULL, passed to abline to draw background lines before adding colored points. DEFAULT: NULL

pch

Point CHaracter. See par. DEFAULT: 16

x1, x2, y1, y2

Relative coordinates [0:1] of inset plot, see smallPlot. Passed to colPointsLegend. DEFAULT: x: 0.6-0.99, y: 0.88-0.98

density

Arguments for density line in colPointsLegend, or FALSE to suppress drawing it. DEFAULT: NULL

horizontal

Logical passed to colPointsLegend. DEFAULT: TRUE

quiet

Turn off warnings? DEFAULT: FALSE

…

Further graphical arguments passed to plot, points and segments, eg cex, xlim (when add=F), mgp, main, sub, asp (when add=F), etc. Note: col does not work, as it is already another argument

Value

Invisible list of values that can be passed to colPointsLegend or colPointsHist.

References

http://uxblog.idvsolutions.com/2011/10/telling-truth.html, http://www.theusrus.de/blog/the-good-the-bad-22012/

See Also

classify, colPointsLegend, colPointsHist

Examples

# NOT RUN {
i <- c( 22,  40,  48,  60,  80,  70,  70,  63,  55,  48,  45,  40,  30,  32)
j <- c(  5,  10,  15,  20,  12,  30,  45,  40,  30,  36,  56,  33,  45,  23)
k <- c(175, 168, 163, 132, 120, 117, 110, 130, 131, 160, 105, 174, 190, 183)

# basic usage:
colPoints(i,j,k, cex=1.5, pch="+", add=FALSE)

# with custom Range:
colPoints(i,j,k, cex=1.5, pch="+", add=FALSE, Range=c(150,190), density=FALSE)
# can be used to allow comparison between several plots
# points outside the range are plotted with col2

# with custom colors:
mycols <- colorRampPalette(c("blue","yellow","red"))(50)
colPoints(i,j,k, cex=1.5, pch="+", add=FALSE, col=mycols)

# With legend title:
colPoints(i,j,k, cex=2, add=FALSE, zlab="Elevation [m above NN.]",
         legargs=list(density=FALSE))
?colPointsLegend # to see which arguments can be set via legargs

# with lines (nint to change number of linear interpolation points):
colPoints(i,j,k, cex=1.5, add=FALSE, lines=TRUE, nint=10, lwd=2)
# With NAs separating lines:
tfile <- system.file("extdata/rivers.txt", package="berryFunctions")
rivers <- read.table(tfile, header=TRUE, dec=",")
colPoints(x,y,n, data=rivers, add=FALSE, lines=TRUE)
colPoints(x,y,n, data=rivers, add=FALSE, lines=TRUE, pch=3, lwd=3)
colPoints(x,y,n, data=rivers, add=FALSE, lines=TRUE, pch=3, lwd=3, nint=2)
colPoints("x","y","n", data=rivers, add=FALSE)

# different classification methods:
# see ?classify

colPoints(i,j,k, add=FALSE) # use classify separately:
text(i,j+1,k, col=divPal(100,rev=TRUE)[classify(k)$index], cex=1)


# Add histogram:
cp <- colPoints(i,j,k, add=FALSE)
do.call(colPointsHist, cp[c("z","at","labels","bb","nbins")])
do.call(colPointsHist, owa(cp[c("z","at","labels","bb","nbins")], 
                           list(bg=5, breaks=5)))
do.call(colPointsHist, owa(cp[c("z","at","labels","bb","nbins")], 
                           list(mar=c(0,0,0,0), x1=0.5, x2=1, y1=0.8, 
                             y2=0.99, yaxt="n")))
# histogram in lower panel:
layout(matrix(1:2), heights=c(8,4) )
colPoints(i,j,k, add=FALSE, y1=0.8, y2=1)
colPointsHist(z=k, x1=0.05, x2=1, y1=0, y2=0.4, mar=3, outer=TRUE)
layout(1)


# Customizing the legend :
cp <- colPoints(i,j,k, legend=FALSE, add=FALSE)
colPointsLegend(x1=0.2, x2=0.95, y1=0.50, y2=0.40, z=k, labelpos=5, atminmax=TRUE, bg=7)
colPointsLegend(x1=0.5, x2=0.90, y1=0.28, y2=0.18, z=k, Range=c(80, 200), nbins=12, font=3)
colPointsLegend(x1=0.1, x2=0.40, y1=0.15, y2=0.05, z=k, labelpos=5, lines=FALSE, title="")
colPointsLegend(z=k, horizontal=FALSE)
colPointsLegend(x1=0.01, y2=0.80, z=k, horizontal=FALSE, labelpos=4, cex=1.2)
colPointsLegend(x1=0.23, y2=0.95, z=k, horizontal=FALSE, labelpos=5, cex=0.8,
  dens=FALSE, title="", at=c(130,150,170), labels=c("y","rr","Be"), lines=FALSE)
# For method other than colPoints' default, it is easiest to include these
# options as a list in legargs, but you can also use the invisible output
# from colPoints for later calls to colPointsLegend
do.call(colPointsLegend, cp)
do.call(colPointsLegend, owa(cp, list(colors=rainbow2(100), cex=1.2)))

# colPoints with matrix:
colPoints(z=volcano, add=FALSE)
# image and contour by default transpose the matrix!
# colPoints shows what is really in the data.
colPointsHist(z=volcano)

# highlight local character of points on a regular grid normally drawn with image:
z <- t(volcano)  ;  x <- 1:ncol(z)  ;  y <- 1:nrow(z)
colPoints(x,y,z, add=FALSE)  # takes matrix for z
contour(x,y,t(z), add=TRUE)
# image only takes a regular matrix, but not scatterpoints...
image(x,y,t(z), col=rainbow2(100))
# add single newly measured points to image (fictional data):
mx <- c( 22,  40,  80,  45,  60,  63,  30,  70)
my <- c(  5,  33,  12,  56,  20,  40,  45,  45)
mz <- c(135, 155, 120, 105, 140, 130, 190, 110)
colPoints(mx,my,mz, cex=5, pch="*", Range=c(94, 195), col=rainbow2(100), col2=NA, legend=FALSE)
points(mx,my, cex=4)
text(mx,my,mz, adj=-0.5, font=2)

# santiago.begueria.es/2010/10/generating-spatially-correlated-random-fields-with-r
if(require(gstat)){
xyz <- gstat(formula=z~1, locations=~x+y, dummy=TRUE, beta=1,
             model=vgm(psill=0.025,model="Exp",range=5), nmax=20)
xyz <- predict(xyz, newdata=data.frame(x=runif(200, 20,40),y=runif(200, 50,70)), nsim=1)
head(xyz)
colPoints(x,y,sim1, data=xyz, col=rainbow2(100), add=FALSE)
}

# }