addMapLegend: Add a legend to a map

In AndySouth/rworldmap: Mapping Global Data

Add a legend to a map

Description

Creates a colour bar legend, showing the range of colours and the values the colours correspond to. Relies heavily on image.plot() from the package fields. For simple use, simply use addLegend=TRUE in a rworldmap map function. Or users can call addMapLegend seperately to fine tune the legend. The user should insure that data, catMethod,numCats and colourPalette match the values used in the plot. The legend is designed to be useful for the variety of classification methods that exist.

Usage

addMapLegend(
  colourVector = "",
  cutVector = "",
  legendLabels = "limits",
  labelFontSize = 1,
  legendWidth = 1.2,
  legendShrink = 0.9,
  legendMar = 3,
  horizontal = TRUE,
  legendArgs = NULL,
  tcl = -0.5,
  mgp = c(3, 1, 0),
  sigFigs = 4,
  digits = 3,
  legendIntervals = "data",
  plottedData = "",
  catMethod = "pretty",
  colourPalette = "heat"
)

Arguments

colourVector	colours used in the map
cutVector	the categories or breaks used in the map
legendLabels	Controls the style of the labels on the legend. Choose "none" for no labels, "limits" for the two end values, and "all" to show all the break values if they fit.
labelFontSize	Controls font size of the labels. A multiplier, so use 2 to double the size, 0.5 to halve it, etc.
legendWidth	Controls the width of the colour bar.
legendShrink	Controls the length of the colour bar. 1 means full width of the plot.
legendMar	Moves the legend away from the side of the plot. Measured in character widths.
horizontal	If TRUE the legend is horizontal, if FALSE, vertical.
legendArgs	For producing titles and labels. A list of arguments to be passed to mtext.
tcl	Controls the length of the tick marks.Useful when labelFontSize is changed.
mgp	Numeric vector length 3. The second element controls the distance between labels and the axis. Useful when labelFontSize is changed.
sigFigs	The number of significant figures for legend labels.
digits	An argument to the formatting of the labels
legendIntervals	"page" or "data". Controls the division of the colour bar, "page" sets the intervals equal on the page, "data" sets them to be equal in the units of the data.
plottedData	unused but are passed with mapParams
catMethod	unused but are passed with mapParams
colourPalette	unused but are passed with mapParams

Details

The default legend is a horizontal colour bar, with labels only at the extremes.

Can use a parameter list returned from mapping functions, e.g. mapCountryData(). mapCountryData(addLegend=TRUE) produces same results as: mapParams <- mapCountryData(addLegend=FALSE) do.call(addMapLegend, mapParams)

Using the following allows the modification of the legend : mapParams <- mapCountryData(addLegend=FALSE) do.call(addMapLegend, c(mapParams, legendLabels="all", legendWidth=0.5))

Value

Adds a legend to a plot.

Note

Can have the unintentional effect of modifying graphical parameters, e.g. mfcol reverts to mfrow.

Author(s)

Andy South

See Also

mapCountryData, mapGriddedData, image.plot

Examples

#Set up the plot so the world map uses the full width.
mapDevice() 
#join eaxmple data to a map  
data("countryExData",envir=environment())
sPDF <- joinCountryData2Map(countryExData
              , joinCode = "ISO3"
              , nameJoinColumn = "ISO3V10"
              )
#map the data with no legend              
mapParams <- mapCountryData( sPDF
              , nameColumnToPlot="BIODIVERSITY"
              , addLegend='FALSE' 
              )
              
#add a modified legend using the same initial parameters as mapCountryData               
do.call( addMapLegend, c( mapParams
                        , legendLabels="all"
                        , legendWidth=0.5
                        ))

AndySouth/rworldmap documentation built on Sept. 3, 2023, 3:46 a.m.