{smcl} {* 14mar2010}{...} {hline} help for {hi:zmap} {hline} {title:Binned scatter map} {p 8 17 2} {cmd:zmap} {it:zvar} {it:xvar} {it:yvar} [{cmd:if} {it:exp}] [{cmd:in} {it:range}] [ {cmd:,} {c -(} {cmdab:pct:iles(}{it:numlist}{cmd:)} {c |} {cmdab:br:eaks(}{it:numlist}{cmd:)} {c )-} {cmdab:mult:iples} {it:graph_options} ] {title:Description} {p 4 4 2} {cmd:zmap} graphs (or maps) binned values of a variable z with respect to two variables x and y treated as Cartesian coordinates. In geographical or cartographical terms x defines distance east and y defines distance north. The range of z is divided into two or more bins or classes and points in each bin are shown distinctly. The resulting plot is thus a composite scatter plot. {p 4 4 2} By default binning is into 8 classes with 7 breaks determined by the 5 10 25 50 75 90 95% points or percentiles of the distribution of z. Alternatively, the user may specify other percentile breaks, or a set of breaks on the scale of z. The number of classes in general is naturally one more than the number of breaks. {p 4 4 2} By default with between 1 and 8 breaks, points falling into different bins are shown with different gray scale colours, darker meaning higher values. If more than 8 breaks are specified, default colours are just those of the prevailing graph scheme. In either case users may specify their own colour choices to override defaults. {p 4 4 2} Lower limits are inclusive, so that each bin contains points >= its lower limit and < its upper limit. The upper limit of the highest class is open. {title:Remarks} {p 4 4 2} The main intended application is that z is a spatial series measured at numerous points or for numerous small areas with respect to map coordinates x and y. However, nothing ties this command to spatial data. Users may wish to use the command on other trivariate data. The marker symbols used may then be better set to something larger than the default of points. {p 4 4 2} If the y variable follows a table or matrix row or Southern latitude convention so that it increases downwards, then use the {cmd:ysc(reverse)} option. {p 4 4 2} If you already have a classificatory variable, you do not need any special machinery. Some basic technique is given by the schematic examples below. See also Cox (2005). {p 4 8 2} {cmd:separate y, by(}{it:classvar}{cmd:) veryshortlabel}{p_end} {p 4 8 2} {cmd:scatter `r(varlist)' x}{p_end} {p 4 4 2}or {p 4 8 2} {cmd:scatter y x, by(}{it:classvar}{cmd:)}{p_end} {p 4 4 2} The following limitations may be noted: {p 4 4 2} 1. {cmd:zmap} is not smart about tied values. Higher values of z for the same x and y values will just overplot lower values. If this is important, consider averaging z for each distinct combination of x and y in some way. An example appears below. {p 4 4 2} 2. {cmd:zmap} does not apply any special intelligence to ensure appropriate aspect ratios to maintain equal scales on both x and y axes. The presumption is that most uses will be exploratory or that, if this is important, {cmd:xsize()}, {cmd:ysize()} or {cmd:aspect()} options may be used according to taste. {p 4 4 2} 3. {cmd:zmap} can do nothing about the limitations of your monitor, or indeed any other monitor. {title:Options} {p 4 8 2} {cmd:pctiles(}{it:{help numlist}}{cmd:)} specifies that breaks between categories are defined by the percent points or percentiles indicated. For example, {cmd:pct(25 50 75)} specifies that the 25%, 50% and 75% points (lower quartile, median, upper quartile) be used as breaks, thus defining 4 classes. Percent points must be greater than 0 and less than 100. {p 4 8 2} {cmd:breaks(}{it:{help numlist}}{cmd:)} specifies that breaks between categories are defined by the values indicated. For example, {cmd:br(100 200 400)} specifies that values of 100, 200 and 400 be used as breaks, thus defining 4 classes. {p 8 8 2} Only one of {cmd:pctiles()} and {cmd:breaks()} may be specified. If neither is specified, the default is {cmd:pctiles(5 10 25 50 75 90 95)}. {p 4 8 2} {cmd:multiples} specifies that each bin or class be shown as a separate graph. Thus each plot is just a plot of the x and y values of points in that bin of z. {cmd:multiples} is likely to be most useful with a small number of bins. {p 4 8 2} {it:graph_options} refers to any of the options of {help scatter}. Defaults include, but are not limited to, {p 8 8 2}if {cmd:multiples} is not specified: {cmd:ysc(off) xsc(off) ms(p ..) legend(col(1) pos(3)) plotregion(style(none))} {p 8 8 2}if {cmd:multiples} is specified: {cmd:by(, compact) yla(none) xla(none) ms(p) mcolor(gs4) legend(off) plotregion(style(none))} {title:Examples} {p 4 4 2}(spatial data, all x, y pairs distinct){p_end} {p 4 8 2}{cmd:. zmap B5 X Y, pct(25 50 75)}{p_end} {p 4 8 2}{cmd:. zmap B5 X Y, pct(25 50 75) mcolor(blue blue*0.5 orange*0.5 orange)}{p_end} {p 4 8 2}{cmd:. zmap B5 X Y, pct(25 50 75) multiples}{p_end} {p 4 8 2}(non-spatial data, average z given x, y first){p_end} {p 4 8 2}{cmd:. webuse nlswork}{p_end} {p 4 8 2}{cmd:. egen mean = mean(ln_wage), by(age grade)}{p_end} {p 4 8 2}{cmd:. egen tag = tag(age grade)}{p_end} {p 4 8 2}{cmd:. label var mean "mean ln wage"}{p_end} {p 4 8 2}{cmd:. su ln_wage if !missing(age, grade), detail}{p_end} {p 4 8 2}{cmd:. zmap mean age grade if tag, breaks(.993 1.166 1.361 1.641 1.964 2.275 2.456) ms(S ..) ysc(on) xsc(on) yla(0/18, ang(h)) ytitle(`: var label grade') xla(15(5)45) note("")}{p_end} {title:Acknowledgments} {p 4 4 2}Vince Wiggins made a very helpful suggestion. {title:Author} {p 4 4 2}Nicholas J. Cox, Durham University, U.K.{break} n.j.cox@durham.ac.uk {title:References} {p 4 8 2} Cox, N.J. 2005. Classifying data points on scatter plots. {it:Stata Journal} 5: 604{c -}606. {title:Also see} {p 4 13 2} On-line: help for {help spmap} (if installed)