mapplot {latticeExtra}

Trellis displays on Maps a.k.a. Choropleth maps

Description

Produces Trellis displays of numeric (and eventually categorical) data on a map. This is largely meant as a demonstration, and users looking for serious map drawing capabilities should look elsewhere (see below).

Usage

mapplot(x, data, ...)

## S3 method for class 'formula'
mapplot(x, data, map, outer = TRUE,
        prepanel = prepanel.mapplot,
        panel = panel.mapplot,
        aspect = "iso",
        legend = NULL,
        breaks, cuts = 30,
        colramp = colorRampPalette(hcl.colors(n = 11, palette = "Spectral")),
        colorkey = TRUE,
        ...)

prepanel.mapplot(x, y, map, ...)
panel.mapplot(x, y, map, breaks, colramp, exact = FALSE, lwd = 0.5, ...)

Arguments

x, y

For mapplot, an object on which method dispatch is carried out. For the formula method, a formula of the form y ~ x, with additional conditioning variables as desired. The extended form of conditioning using y ~ x1 + x2 etc. is also allowed. The formula might be interpreted as in a dot plot, except that y is taken to be the names of geographical units in map.

Suitable subsets (packets) of x and y are passed to the prepanel and panel functions.

data

A data source where names in the formula are evaluated

map

An object of class "map" (package maps), containing boundary information. The names of the geographical units must match the y variable in the formula.

The remaining arguments are standard lattice arguments, relevant here mostly because they have different defaults than usual:

outer

Logical flag specifying how variables separated by + in the formula are interpreted. It is not advisable to change the default.

prepanel

The prepanel function.

panel

The panel function.

aspect

The aspect ratio.

breaks, cuts, colramp

controls conversion of numeric x values to a false color. colramp should be a function that produces colors (such as cm.colors). If it is NULL, colors are taken from trellis.par.get("regions").

exact

the default exact = FALSE allows the given y values to match sub-regions of map, i.e. region names with a qualifier following ":", like "michigan:north", "michigan:south". These will both match a y value of "Michigan".

legend, colorkey

controls legends; usually just a color key giving the association between numeric values of x and color.

lwd

line width

...

Further arguments passed on to the underlying engine. See xyplot for details.

Value

An object of class "trellis".

Note

This function is meant to demonstrate how maps can be incorporated in a Trellis display. Users seriously interested in geographical data should consider using software written by people who know what they are doing.

Author(s)

Deepayan Sarkar

References

https://en.wikipedia.org/wiki/Choropleth_map

See Also

Lattice

Examples

## Requires the 'maps' and 'mapproj' packages:

if (require(maps) && require(mapproj)) {

    ## Note: Alaska, Hawaii and others are not included in county map;
    ## this generates warnings with both USCancerRates and ancestry.

    data(USCancerRates)

    suppressWarnings(print(
        mapplot(rownames(USCancerRates) ~ log(rate.male) + log(rate.female),
                data = USCancerRates,
                map = map("county", plot = FALSE, fill = TRUE,
                          projection = "mercator"))
    ))

    suppressWarnings(print(
        mapplot(rownames(USCancerRates) ~ log(rate.male) + log(rate.female),
                data = USCancerRates,
                map = map("county", plot = FALSE, fill = TRUE,
                          projection = "tetra"),
                scales = list(draw = FALSE))
    ))

    data(ancestry)

    county.map <- 
        map('county', plot = FALSE, fill = TRUE, 
            projection = "azequalarea")

    ## set a sequential color palette as current theme, and use it
    opar <- trellis.par.get()
    trellis.par.set(custom.theme(region = rev(hcl.colors(9, "Purp")),
                                 alpha.line = 0.5))
    suppressWarnings(print(
        mapplot(county ~ log10(population), ancestry, map = county.map,
                colramp = NULL, border = "transparent")
    ))
    trellis.par.set(opar)
}

## Not run: 

## this may take a while (should get better area records)

if (require(maps) && require(mapproj)) {

    county.areas <- 
        area.map(county.map, regions = county.map$names, sqmi = FALSE)
    
    ancestry$density <- 
        with(ancestry, population / county.areas[as.character(county)])

    mapplot(county ~ log(density), ancestry,
            map = county.map, border = NA,
            colramp = colorRampPalette(c("white", "black")))

}

## End(Not run)