addLabels {PBSmapping}

Add Labels to an Existing Plot

Description

Add the label column of data to the existing plot.

Usage

addLabels (data, xlim = NULL, ylim = NULL, polyProps = NULL,
           placement = "DATA", polys = NULL, rollup = 3,
           cex = NULL, col = NULL, font = NULL, ...)

Arguments

data

EventData or PolyData to add (required).

xlim

range of X-coordinates.

ylim

range of Y-coordinates.

polyProps

PolyData specifying which labels to plot and their properties. par parameters passed as direct arguments supersede these data.

placement

one of "DATA", "CENTROID", "MEAN_RANGE", or "MEAN_XY".

polys

PolySet to use for calculating label placement.

rollup

level of detail at which to process polys, and it should match that in data. 1 = PIDs only, 2 = outer contours only, and 3 = no roll-up.

cex

vector describing character expansion factors (cycled by EID or PID).

col

vector describing colours (cycled by EID or PID).

font

vector describing fonts (cycled by EID or PID).

...

additional par parameters for the text function.

Details

If data is EventData, it must minimally contain the columns EID, X, Y, and label. Since the EID column does not match a column in polys, set placement = "DATA". The function plots each label at its corresponding X/Y coordinate.

If data is PolyData, it must minimally contain the columns PID and label. If it also contains X and Y columns, set placement = "DATA" to plot labels at those coordinates. Otherwise, set placement to one of "CENTROID", "MEAN_RANGE", or "MEAN_XY". When placement != "DATA", supply a PolySet polys. Using this PolySet, the function calculates a centroid, mean range, or mean X/Y coordinate for each polygon, and then links those PolyData with data by PID/SID to determine label coordinates.

If data contains both PID and EID columns, the function assumes it is PolyData and ignores the EID column.

For additional help on the arguments cex, col, and font, please see par.

Value

EventData or PolyData with X and Y columns that can subsequently reproduce the labels on the plot. Modify this data frame to tweak label positions.

Author(s)

Nicholas M. Boers, Staff Software Engineer
Jobber, Edmonton AB
Last modified Rd: 2013-04-10

See Also

addPoints, calcCentroid, calcMidRange, calcSummary, EventData, plotPoints, PolyData.

Examples

local(envir=.PBSmapEnv,expr={
  oldpar = par(no.readonly=TRUE)
  #--- create sample PolyData to label Vancouver Island
  labelData <- data.frame(PID=33, label="Vancouver Island");
  #--- load data
  if (!is.null(version$language) && (version$language == "R"))
    data(nepacLL,envir=.PBSmapEnv)
  #--- plot the map
  plotMap(nepacLL,xlim=c(-129,-122.6),ylim=c(48,51.1),col="lemonchiffon")
  #--- add the labels
  addLabels(labelData,placement="CENTROID",polys=nepacLL,cex=1.2,col=2,font=2)
  par(oldpar)
})