mapStats (version 1.14)

mapStats: Calculate and plot survey statistics

Description

mapStats computes statistics and quantiles of a survey variable and displays them on a map. It calls functions calcStats, calcQuantiles, and plotStats. Functions calcStats and calcQuantiles can be used on their own to calculate statistics, but plotStats is designed to be run from within the wrapper function mapStats.

Usage

mapStats(d, var, stat = c("mean", "quantile"), quantiles = c(0.5, 0.75), 
         wt.var = NULL, wt.label = TRUE, x.geo.var, by.var = NULL, 
         map.file, map.geo.var = x.geo.var, makeplot = TRUE, ngroups = 4, 
         cell.min = 0, palette = "Reds", col = NULL, map.label = TRUE,
         map.label.names = map.geo.var, cex.label = 0.8, col.label = "black", 
         titles = NULL, cex.title = 1, var.pretty = var, geo.pretty = x.geo.var,
         by.pretty = by.var, as.table = TRUE, sp_layout.pars = list(), 
         between = list(y = 1), separate = TRUE, horizontal.fill = TRUE, 
         num.row = 1, num.col = 1, ...) 

calcStats(d, var, stat = c("mean", "total"), x.geo.var, 
          by.var = NULL, wt.var = NULL, cell.min = 0) 

calcQuantiles(d, var, quantiles = c(0.50, .75), x.geo.var,
              by.var = NULL, wt.var = NULL, cell.min = 2)

plotStats(statmats, x.geo.var, map.file, map.geo.var, ngroups, palette,  
          col, map.label, map.label.names, cex.label, col.label, titles, 
          cex.title, wt.ind = FALSE, wt.label, var.pretty, geo.pretty, 
          by.pretty, sp_layout.pars, separate, num.col, ...) 

## S3 method for class 'plotStats':
print(x, horizontal.fill = TRUE, num.row = 1, num.col = 1, ...)

Arguments

d

a data frame containing the variables to be analyzed.

var

a character string of the name of the variable that statistics will be calculated for. Only one variable can be used at a time.

stat

a character vector of names of statistics to calculate. Valid names are "mean", "total", and "quantile". "Quantile" must be included for the quantiles specified to be calculated. Statistics are printed in the order given. For instance if stat = c(

quantiles

a numeric vector of quantiles to be calculated for the variable var. The quantiles must be specified as decimals between 0 and 1. In order to be calculated, "quantile" must be specified as a statistic in the argument stat.

wt.var

a character string of the name of the variable to be used as sample weights in calculating statistics. The default is NULL, meaning unweighted statistics will be calculated.

wt.label

logical. Default is TRUE, in which case automatic titles will be followed by the string '(wtd.)' or '(unwtd.)' as appropriate, depending on whether weighted statistics were calculated. If FALSE no label will be added.

x.geo.var

a character string of the name of the variable in the data frame x that is the geographic identifier.

by.var

a character string specifying an optional class variable to calculate statistics by. If specified, statistics will be calculated at all level combinations of x.geo.var and by.var; otherwise, just overall statistics for x.

map.file

an object of class SpatialPolygonsDataFrame on which the statistics will be plotted.

map.geo.var

a character string of the name of the geographic identifier in the data portion of map.file. This is the counterpart of x.geo.var. The default is for this to be the same name as x.geo.var. The values of x.g

makeplot

logical. Default is TRUE; if FALSE, plots will not be drawn.

ngroups

a numeric vector of the number of levels for color plotting of variable statistics. If more than one number is specified, ngroups will be different in each plot.

cell.min

numeric. Indicates the minimum number of observations in a cell combination of x.geo.var and by.var (if specified). If there are fewer than that, the statistic will be NA in that cell. For calcQuantiles, ce

palette

a character vector containing palette names from the list below in details. This is used to specify a palette from brewer.pal). The default is to use colors from this palette. If argument

col

a list where each element is a sequence of colors. These can be used instead of palette to introduce HCL sequential palettes from sequential_hcl.

map.label

logical. Default is TRUE; if FALSE, names of the geographic regions will not be labeled on the map outputs.

map.label.names

a character string naming the vector from the map.file@data data.frame to use to label the map. The default is to use map.geo.var.

cex.label

numeric. Character expansion for the labels to be printed.

col.label

color of the label text to be printed. Default is black.

titles

a character string of length equal to the number of statistics to be plotted, in order. Note that mean and total will be printed before the quantiles. Replaces the default plot titles.

cex.title

numeric. Character expansion for the plot titles.

var.pretty

a character string used to name the analysis variable in the default plot titles. The default is to use var as the name in titles.

geo.pretty

a character string used to name the geographic class variable in the default plot titles. The default is to use x.geo.var as the name in titles.

by.pretty

a character string used to name the by variable in the default panel strip labels. The default is to use by.var as the name labels.

as.table

logical. Default is TRUE, meaning the panels will be displayed in ascending order of the by variable (top to bottom).

sp_layout.pars

a list. This contains additional parameters to be plotted on each panel. See details section below and explanation of sp.layout in spplot.

between

list. Parameters for spacing between panels.

separate

logical. Default is TRUE, meaning that each statistic will be plotted on its own page with the color key calculated on its values alone. Setting it to FALSE causes the function to calculate a color key by pooling the values from all the statistics acro

horizontal.fill

logical. Default is TRUE, meaning that given the plot arrangement specified with num.row and num.col, that plots will be plotted in order left to right then down. FALSE means they will be plotted going down first and then lef

num.row

numeric. To print multiple statistics on one page, indicate the number of rows for panel arrangement. Under the default, one statistic is printed per page.

num.col

numeric. To print multiple statistics on one page, indicate the number of columns for panel arrangement. Under the default, one statistic is printed per page.

...

Further arguments, usually lattice plot arguments.

statmats

an list object produced by calcStats or calcQuantiles containing the matrices of statistics to plot.

wt.ind

logical. Default is FALSE. If TRUE, weighted statistics were calculated. If map.label is TRUE, default plot titles will indicate whether weighted or unweighted statistics were calculated.

x

list. A list produced by plotStats containing trellis plot objects.

Value

• mapStats, calcStats, and calcQuantiles return an object of class "list"
• summary.stats
  a list containing the calculated statistics matrices
• with attribute
• variable
  the name of the variable

Details

Quantiles for combinations x.geo.var and by.var (if specified) will be missing if the combination has fewer than two non-missing observations. A warning message may be returned by the function rq that the output may be singular if there are small cell sizes. palette should be the name of a sequential color palette in R from the RColorBrewer package. These are: Blues BuGn BuPu GnBu Greens Greys Oranges OrRd PuBu PuBuGn PuRd Purples RdPu Reds YlGn YlGnBu YlOrBr YlOrRd. The argument ngroups should be between 3 and 9 since sequential color palettes have at most nine levels. The style argument from classIntervals can be included to change the method for calculating breaks (the default is by quantiles). The default titles for the plots will be "(stat) of (variable) by (geography)", followed by either "(unwtd.)" or "(wtd.)", as appropriate. Using the wt.label argument controls the appearance of the weight label in the titles. Providing a value for the titles argument will override the default titles. This can be used, for instance, as shown below, to display percentages for a binary variable by calculating the mean of an indicator variable and specifying titles that indicate the percent is displayed. If quantiles are 0 (minimum), 0.50 (median), or 1 (maximum), the statistics in the titles will be named "Minimum", "Median", and "Maximum" instead of "Q0", "Q50" or "Q100". The lattice layout argument can be used to control the placement of panels within a graph, especially if multiple plots are done on a page. sp_layout.pars must itself be a list, even if its contents are a list also. This allows overplotting of more than one object. For instance, say you had a shapefile areas to be colored blue, and a vector of strings labels1 that had x-coordinates xplaces and y-coordinates yplaces to overlay on the plot. Create objects areas_overlay= list("sp.polygons", areas_overlay, fill="blue"), and labels_overlay= list("panel.text", labels1, xvalues, yvalues). Then set argument sp_layout.pars= list(areas_overlay, labels_overlay). Even if you only wanted to overlay with areas, you would still need to enclose it in another list, for example sp_layout.pars= list(areas_overlay).

See Also

The survey package function svyby is used to calculate mean and totals, and rq calculates quantiles. spplot plots the map.

Examples

#More complex examples with formatting are shown in the map_examples demo for the package

#create synthetic survey dataset


state_codes <- c('AL','AK','AZ','AR','CA','CO','CT','DE','DC','FL','GA','HI','ID','IL',
                 'IN','IA','KS','KY','LA','ME','MD','MA','MI','MN','MS','MO','MT','NE',
                 'NV','NH','NJ','NM','NY','NC','ND','OH','OK','OR','PA','RI','SC','SD',
                 'TN','TX','UT','VT','VA','WA','WV','WI','WY')

surveydata <- data.frame(state=factor(rep(rep(state_codes, 
                         times=3), times=2)))
surveydata$year <- rep(c(2009, 2010), each=nrow(surveydata)/2)
surveydata$obs_weight <- runif(n=nrow(surveydata), min=0.8, max=1.5)

#two income distributions
surveydata$income <- 100000*rbeta(n=nrow(surveydata), 
                                  shape1=ifelse(surveydata$year==2009, 2, 1.5),
                                  shape2=ifelse(surveydata$year==2010, 10, 11))
surveydata$income_ge20k <- ifelse(surveydata$income >=20000, 100, 0)

#these state and year combinations will not be shaded if they are missing entirely
surveydata[ surveydata$state == "NV" & surveydata$year == 2009, c("income","income_ge20k")] <- NA
surveydata[ surveydata$state == "OH" & surveydata$year == 2010, c("income","income_ge20k")] <- NA


#load map shapefile
usMap <- readShapePoly(system.file("shapes/usMap.shp", package="mapStats")[1])


#Calculate weighted mean of variable income by state.  Display using red 
#sequential color palette with 4 groups.  In the titles, rename 'income'
#by 'household income'.     

mapStats(d=surveydata, var="income", wt.var="obs_weight", 
         map.file=usMap, x.geo.var="state", map.geo.var="STATE_ABBR",
         stat=c("mean"), ngroups=4, palette="Reds", 
         var.pretty="household income", geo.pretty="state",
         map.label=TRUE)


#Calculate the weighted mean and 40th and 50th quantiles of the variable income
#by state and survey year. Display 2 statistics on the first page and 1 on the
#last, and use three color palettes

mapStats(d=surveydata, var="income", by.var="year",
         wt.var="obs_weight", map.file=usMap,
         x.geo.var="state", map.geo.var="STATE_ABBR",
         stat=c("mean","quantile"), quantiles=c(.4, .5),
         ngroups=6, palette=c("Reds","Greens","Blues"), 
         var.pretty="household income", geo.pretty="state", 
         by.pretty="Year", map.label=TRUE, num.col=1, num.row=2, 
         layout=c(2,1))

#To calculate percentages of class variables, create an indicator variable, calculate
#its mean, and override the default titles to say you are calculating the percentage.
#Here we illustrate by calculating the percent of respondents by state that have income
#above $20,000.

mapStats(d=surveydata, var="income_ge20k", wt.var="obs_weight", 
         map.file=usMap, x.geo.var="state", map.geo.var="STATE_ABBR", 
         col.pal="Reds", stat=c("mean"), 
         titles="Percent of respondents with income at least $20,000")


#calculating statistics using the functions outside of mapStats
#unweighted quantiles

calcQuantiles(d=surveydata, x.geo.var="state", var="income", 
              by.var="year", quantiles=c(0.5, 0.75))