Adds Rays with Optional Confidence Arcs (Sectors)

DESCRIPTION:

Adds rays to an existing plot with angles determined by a third variable and optional confidence sectors around the rays.

USAGE:

rayplot(x, y, z, lowbnd, highbnd, minz = <<see below>>, maxz = <<see below>>, 
   arcs = list(length=0.75, sides=18, lwd=1, density=-1, border=F, col=2), 
   tics = list(length=0.06, sides= 8, lwd=1, col=1),  
   dots = list(length=0.06, sides= 8, lwd=1, density=0, border=T, col=1), 
   rays = list(length=0.30, lwd=2, col=1),  
   minangle= -pi/2, maxangle=pi/2, clockwise=F) 

REQUIRED ARGUMENTS:

x,y
coordinates of points where the rays are wanted.
z
numeric vector of values to translate into the ray angles.

OPTIONAL ARGUMENTS:

lowbnd
numeric vector. Lower bound of the confidence interval that is desired for z. If provided then it must be the same length as z.
highbnd
numeric vector. Upper bound of the confidence interval desired for z. Must be the same length as z, if provided. Either both or none of lowbnd and highbnd must be given.
minz
a numeric constant to scale z by. minz maps into minangle so only one of the two is necessary. Its default value is min(z) if lowbnd is missing or min(lowbnd) otherwise.
maxz
a numeric constant to scale z by, maxz maps into maxangle so only one of the two is necessary. Its default value is max(z) if highbnd is missing or max(highbnd) otherwise.

Lists of parameters to customize each component of the individual rays can be provided in each of the following arguments:
arcs
list of parameters affecting the confidence arcs. This is only relevant if lowbnd and highbnd are provided. The possible components of this list are:

length= numeric scalar or vector giving the confidence sector radii in inches. If a constant, then it is taken to be a fraction of the ray length. If a vector (of the same length as x), then each component is taken to represent the corresponding arc's length.

sides= scalar giving the number of polygon sides for the maximum sector.

lwd= sector line width

density= sector fill options. If density is zero, no filling will occur. If density is negative, the sector will be filled solidly using the device-dependent polygon filling algorithm.

border= logical flag. Should the border of the sector be plotted?

col= integer determining the color for the sector.

tics
list of parameters affecting the reference angles against which the user can read the angles of the rays more accurately. Its components are:

length= radius of the tics in inches. No tics are plotted if this is 0 or FALSE.

sides= number of tics at the base of a ray. Default is 8.

lwd= tic line width.

col= integer determining the color of the tics.

dots
list of parameters affecting the dot at the base of each ray:

length= numeric scalar or vector giving the radius of the dot in inches. No dots are plotted if this is 0 or FALSE.

sides= integer. Number of sides of the "dot."

lwd= line width parameter.

density= dot fill parameter. See its definition above for arcs.

border= logical flag. Should the border of the dot be plotted?

col= integer determining the color for the dot.

rays
The options in the list rays affect the characteristics of the main rays:

length= numeric scalar or vector giving the ray length in inches. No rays are plotted if this is 0 or FALSE. If this is a scalar, it will be replicated to the a length equivalent to the number of points at which rays are desired, length(x).

lwd= line width parameter.

col= integer determining the color of each ray.

minangle
numeric scalar giving the minimum angle for the plotting of rays in radians.
maxangle
numeric scalar giving the maximum angle for the plotting of rays in radians.
clockwise
logical flag, should the direction from the minimum angle to the maximum be clockwise or not?

SIDE EFFECTS:

rays with angles from a downward position are added to the current plot. The smallest value is mapped to -pi/2 and the greatest to pi/2.

DETAILS:

Only one direction can be mapped with the current release, if both directions are desired, then call rayplot twice setting clockwise to FALSE and TRUE respectively.

Confidence sectors are useful but should be used with caution. Big arcs will call attention to the less accurate estimates. Consequently, the user may want to use shorter arc lengths for the less accurate estimates to de- emphasize this effect.

The options rays affects the characteristics of the main rays. If the given length for these is a constant value, it will be replicated to the a length equivalent to the number of points at which rays are desired.

The option for tics provides reference angles against which the user can read the ray angles more accurately.

The option for dots will put a dot at the base of each ray. Typically, an open dot surrounds the tics.

Outliers are not easily spotted when encoded as ray-angles. If the user wants to highlight selected observations or determine global scaling, rayplot should be called for each of the selected data subsets with changing parameters, such as color ( col), length ( length), or line width ( lwd).

REFERENCES:

Carr, D. B., Olsen, A. R. and White, D. (1992). Hexagon mosaic maps for display of univariate and bivariate geographical data. Cartography and Geographics Information Systems 19, 228-236.

EXAMPLES:

# Random locations values and bounds 
x <- rnorm(100) 
y <- rnorm(100) 
z <- rnorm(100) 
inc <- abs(rnorm(100,sd=.4)) 
lowbnd <- z-inc 
highbnd <- z+inc 
  
# No confidence bounds 
plot(x,y,type='n') 
rayplot(x, y, z) 
  
# Confidence bounds 
plot(x,y,type='n') 
rayplot(x, y, z, lowbnd, highbnd) 
  
# Clockwise orientation 
plot(x,y,type='n') 
rayplot(x, y, z, lowbnd, highbnd, clockwise=TRUE) 
  
# No tics and small filled dots 
plot(x,y,type='n') 
rayplot(x, y, z, lowbnd, highbnd, tics=list(F), 
        dots=list(sides=20, length=.025, density=-1)) 
  
# Bivariate rays for smoothed data on a hexagon grid 
# (Data not provided) 
plot(mymap,type='l') 
rayplot(grid$x,grid$y,pred$so4) 
rayplot(grid$x,grid$y,pred$no3,clockwise=T,tics=list(F))