1\name{svyplot}
2\alias{svyplot}
3\alias{svyplot.default}
4%- Also NEED an '\alias' for EACH other topic documented here.
5\title{Plots for survey data }
6\description{
7  Because observations in survey samples may represent very different
8  numbers of units in the population ordinary plots can be misleading.
9  The \code{svyplot} function produces scatterplots adjusted in various ways
10  for sampling weights.
11}
12\usage{
13svyplot(formula, design,...)
14\method{svyplot}{default}(formula, design, style = c("bubble", "hex", "grayhex","subsample","transparent"),
15sample.size = 500, subset = NULL, legend = 1, inches = 0.05,
16amount=NULL, basecol="black",
17alpha=c(0, 0.8),xbins=30,...)
18}
19%- maybe also 'usage' for other objects documented here.
20\arguments{
21  \item{formula}{A model formula}
22  \item{design}{ A survey object (svydesign or svrepdesign)}
23  \item{style}{See Details below}
24  \item{sample.size}{For \code{style="subsample"}}
25  \item{subset}{expression using variables in the design object}
26  \item{legend}{For \code{style="hex"} or \code{"grayhex"}}
27  \item{inches}{Scale for bubble plots}
28  \item{amount}{list with \code{x} and \code{y} components for amount of
29    jittering to use in subsample plots, or \code{NULL} for the default
30    amount}
31  \item{basecol}{base color for transparent plots, or a function to
32    compute the color (see below), or color for bubble plots}
33  \item{alpha}{minimum and maximum opacity for transparent plots}
34\item{xbins}{Number of (x-axis) bins for hexagonal binning}
35  \item{\dots}{Passed to \code{plot} methods}
36}
37\details{
38  Bubble plots are scatterplots with circles whose area is proportional
39  to the sampling weight.  The two "hex" styles produce hexagonal
40  binning scatterplots, and require the \code{hexbin} package from
41  Bioconductor. The "transparent" style plots points with opacity
42  proportional to sampling weight.
43
44
45  The \code{subsample} method uses the sampling weights to create a
46  sample from approximately the population distribution and passes this to \code{\link{plot}}
47
48  Bubble plots are suited to small surveys, hexagonal binning and
49  transparency to large surveys where plotting all the points would
50  result in too much overlap.
51
52  \code{basecol} can be a function taking one data frame argument, which
53  will be passed the data frame of variables from the survey object.
54  This could be memory-intensive for large data sets.
55}
56\value{
57  None
58}
59
60\seealso{
61  \code{\link{symbols}} for other options (such as colour) for bubble
62  plots.
63
64  \code{\link{svytable}} for plots of discrete data.
65}
66
67\references{
68
69Korn EL, Graubard BI (1998) "Scatterplots with Survey Data" The American Statistician 52: 58-69
70
71Lumley T, Scott A (2017) "Fitting Regression Models to Survey Data"
72Statistical Science 32: 265-278
73}
74
75\examples{
76data(api)
77dstrat<-svydesign(id=~1,strata=~stype, weights=~pw, data=apistrat, fpc=~fpc)
78
79svyplot(api00~api99, design=dstrat, style="bubble")
80svyplot(api00~api99, design=dstrat, style="transparent",pch=19)
81
82## these two require the hexbin package
83svyplot(api00~api99, design=dstrat, style="hex", xlab="1999 API",ylab="2000 API")
84svyplot(api00~api99, design=dstrat, style="grayhex",legend=0)
85
86
87dclus2<-svydesign(id=~dnum+snum,  weights=~pw,
88                    data=apiclus2, fpc=~fpc1+fpc2)
89svyplot(api00~api99, design=dclus2, style="subsample")
90svyplot(api00~api99, design=dclus2, style="subsample",
91          amount=list(x=25,y=25))
92
93svyplot(api00~api99, design=dstrat,
94  basecol=function(df){c("goldenrod","tomato","sienna")[as.numeric(df$stype)]},
95  style="transparent",pch=19,alpha=c(0,1))
96legend("topleft",col=c("goldenrod","tomato","sienna"), pch=19, legend=c("E","H","M"))
97
98## For discrete data, estimate a population table and plot the table.
99plot(svytable(~sch.wide+comp.imp+stype,design=dstrat))
100fourfoldplot(svytable(~sch.wide+comp.imp+stype,design=dstrat,round=TRUE))
101
102
103## To draw on a hexbin plot you need grid graphics, eg,
104library(grid)
105h<-svyplot(api00~api99, design=dstrat, style="hex", xlab="1999 API",ylab="2000 API")
106s<-svysmooth(api00~api99,design=dstrat)
107grid.polyline(s$api99$x,s$api99$y,vp=h$plot.vp@hexVp.on,default.units="native",
108   gp=gpar(col="red",lwd=2))
109}
110\keyword{survey}% at least one, from doc/KEYWORDS
111\keyword{hplot}% __ONLY ONE__ keyword per line
112