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

mapplot {latticeExtra} | R Documentation

## 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(brewer.pal(n = 11, name = "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, relvant here mostly because they have different defaults than usual:

`outer` | logical; how variables separated by `+` in the formula are interpreted. It is not advisable to change the default.
`prepanel, panel` | the prepanel and panel functions
`aspect` | 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

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

### See Also

`Lattice`

### Examples

    library(maps)
    library(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 = brewer.pal(9, "Purples"),
                                 alpha.line = 0.5))
    suppressWarnings(print(
    mapplot(county ~ log10(population), ancestry, map = county.map,
        colramp = NULL)
    ))
    trellis.par.set(opar)

    ## Not run:

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

    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)

[Package latticeExtra version 0.6-28 Index]