hray {hexbin}R Documentation

Represent Values and Confidence Bounds on a Map Using Rays


Adds rays and optional confidence arcs (sectors) to an existing plot.


hray(x, y, val, lowbnd = NULL, highbnd = NULL,
     minval = if(is.null(lowbnd)) min(val) else min(lowbnd),
     maxval = if(is.null(highbnd)) max(val) else max(highbnd),
     raylength = 0.3, raylwd = 2, raypen = 1, dotlength = 0.06,
     dotsides = 8, dotlwd = 1, dotden = 0, dotborder = TRUE,
     dotpen = 1,
     ticlength = 0.06, ticsides = 8, ticlwd = 1, ticpen = 1,
     arclength = 0.75, arcsides = 18, arclwd = 1, arcden = NULL,
     arcborder = FALSE, arcpen = 2,
     minangle =  - pi/2, maxangle = pi/2, clockwise = FALSE)


x vector of xcoordinates for plotting
y vector of ycoordinates for plotting
val vector of values to translate into ray angles
lowbnd The lower bound
highbnd The higher bound
minval Constant for scaling val. Minval maps into minangle.
maxval Constant for scaling val. Maxval maps into maxangle.
raylength Constant or vector giving the ray length in inches. No rays plotted if 0 or FALSE.
raylwd Ray line width
raypen Ray color number
dotlength Radius of dot in inches, No dots plotted if 0 or FALSE
dotsides Number of polygon sides for the "dot"
dotlwd Dot line width
dotden Dot file option (see polygon)
dotborder Logical, plot border of dot (see polygon)
dotpen Dot color number
ticlength Radius of tic in inches. No tics plotted if 0 or FALSE
ticsides Number of tic radii.
ticlwd Tic line width
ticpen Tic color number
arclength Sector radius in inches. No sector plotted if is.null(lowbnd)
arcsides Number of polygon sides for the maximum sector
arclwd Sector line width
arcden Sector fill option (see polygon)
arcborder Logical, plot border of sector (see polygon)
arcpen Sector color number
minangle Constant: Minimum angle for rays or ray bounds (radians)
maxangle Constant: Maximum angle for ryas or ray bounts (radians)
clockwise Logical: Direction from minangle to maxangle


This function has been made very general to support contining experiments. The addition of confidence arcs is a useful. However,the big arcs call attention to the least accurate of the estimates. Consequently experiments are in progress to use a shorter radii for less accurate estimates.

If raylength (inches) is a constant the function replicates it to be a vector. When the function plots confidence bounds, the arclength is treated in one of two ways. If arclength is a constant (fraction), the function recalculates the arclength as a fraction of the raylength. Otherwise the function uses the arclength (inches) as is. Both ray and arc length can be data dependent.

The tic option provides reference angles to help people to read angles more accurately. The argments control standard Splus graphics arguments.

The dot option puts a dot at the base of the ray. Typically an open dot surrounds the tics. The arguments control standar Splus graphics arguments.

Outliers are not so easily spotted when encoded as rays. To highlight selected observations, determine global scaling, call hray with each data subset, and change graphics arguments such as pen (and associated color) , length and lwd arguments.


This function does not return any value.


Adds ray, confidence arcs, angle reference tics and based dot to a plot.


Dan Carr <>

ported by Nicholas Lewin-Koh <>


see in hcell.

See Also

hcell, hcell2xy


# Random  locations values and bounds
x <- rnorm(100)
y <- rnorm(100)
val <- rnorm(100)
inc <- abs(rnorm(100,sd=.4))
lowbnd <- val-inc
highbnd <- val+inc

#no confidence bounds

#confidence bounds

# Clockwise orientation

# No tics and small filled dots

# bivariate rays for smoothed data on a hexagon grid
# Data not provided
#plot(mymap,type='l') ## Do not work. Commented out.
## End of commented out code

# temporal trends with confidence bounds plotted on a map
# Data and user function not provided
#  mtapply()   like tapply but for matrices
#  sens.season.slope()  computes sen's seasonal slope
#bin  <- hcell(x,y)
#  x and y are in map projection units
#newdat < dat[,c('month','year','value')]
# extract columns
#stats <- mtapply(newdat,bin$cell,sens.season.slope,season=12)
# map boundaries in map projection units
#xy <- hcell2xy(bin)
# x and y coordinates for hexagon cell centers
#hray(xy$x, xy$y,stat[,1],lowbnd= stat[,2],highbnd=stat[,3])

[Package hexbin version 1.0.10 Index]