{smcl}
{* 5july2004}{...}
{hline}
help for {hi:onewayplot}
{hline}

{title:Oneway dot plots}

{p 8 17 2}
{cmd:onewayplot}
{it:varlist} 
[{cmd:if} {it:exp}] 
[{cmd:in} {it:range}] 
[ 
{cmd:,}
{cmdab:vert:ical} 
{cmdab:w:idth(}{it:#}{cmd:)} 
{cmdab:st:ack}
{cmdab:h:eight(}{it:#}{cmd:)}
{c -(} 
{cmdab:ce:ntre}
{c |} 
{cmdab:ce:nter}
{c )-} 
{cmd:variablelabels} 
{cmd:plot(}{it:plot}{cmd:)} 
{it:graph_options} ]

{p 8 17 2}
{cmd:onewayplot}
{it:varname} 
[{cmd:if} {it:exp}] 
[{cmd:in} {it:range}] 
[ 
{cmd:,}
{cmd:by(}{it:byvar}{cmd:)}
{cmdab:vert:ical} 
{cmdab:w:idth(}{it:#}{cmd:)} 
{cmdab:st:ack}
{cmdab:h:eight(}{it:#}{cmd:)}
{c -(} 
{cmdab:ce:ntre}
{c |} 
{cmdab:ce:nter}
{c )-} 
{cmd:plot(}{it:plot}{cmd:)} 
{it:graph_options} 
]


{title:Description}

{p 4 4 2}{cmd:onewayplot} plots data as a series of marks against a 
single magnitude axis. By default this axis is horizontal. With the 
option {cmd:vertical} it is vertical.  


{title:Remarks}

{p 4 4 2}{cmd:onewayplot} differs from {cmd:gr7, oneway} and {cmd:dotplot}: 

{p 8 8 2}{cmd:onewayplot} may have either horizontal or vertical magnitude
axis.  With {cmd:gr7, oneway} the magnitude axis is always horizontal.  With
{cmd:dotplot} the magnitude axis is always vertical. 

{p 8 8 2}{cmd:onewayplot} and {cmd:dotplot} put descriptive text on the axes. 
{cmd:gr7, oneway} puts descriptive text under each line of marks.

{p 8 8 2}{cmd:onewayplot} and {cmd:dotplot}
allow any marker symbol to be used for the data marks. 
{cmd:gr7, oneway} always shows data marks as short vertical bars,
unless {cmd:jitter()} is specified. 

{p 8 8 2}{cmd:onewayplot} and {cmd:dotplot} interpret
{cmd:jitter()} in the same way as does {cmd:scatter}. 
{cmd:gr7, oneway} interprets {cmd:jitter()} as replacing short
vertical bars by sets of dots.

{p 8 8 2}{cmd:onewayplot} and {cmd:dotplot} allow tuning of {cmd:xlabel()}.
{cmd:gr7, oneway} does not allow such tuning: the minimum and maximum are
always shown.  Similarly, {cmd:onewayplot} and {cmd:dotplot} allow the use of
{cmd:xline()} and {cmd:yline()}. 

{p 8 8 2}{cmd:onewayplot} and {cmd:dotplot} use by default only one colour in
the body of the graph. {cmd:gr7, oneway} uses several colours with several
variables. 

{p 8 8 2}There is no equivalent with {cmd:onewayplot} or {cmd:dotplot} to
{cmd:gr7, oneway rescale}, which  stretches each set of data marks to extend
over the whole horizontal range of the graph.   

{p 8 8 2}{cmd:onewayplot} and {cmd:dotplot} with option
{cmd:by(}{it:byvar}{cmd:)} do not require data to be sorted by {it:byvar}.
{cmd:gr7, oneway by(}{it:byvar}{cmd:)} requires this. 

{p 8 8 2}{cmd:onewayplot} and {cmd:dotplot} with option
{cmd:by(}{it:byvar}{cmd:)} do take the values of {it:byvar} literally.
{cmd:gr7, oneway by(}{it:byvar}{cmd:)} does not take the values of {it:byvar}
literally: displays for values 1, 2 and 4 will appear equally spaced. 

{p 8 8 2}{cmd:onewayplot} with the {cmd:stack} option produces a variant on
{cmd:dotplot}. There is by default no binning of data: compare 
{cmd:dotplot, nogroup}. Binning may be accomplished with the {cmd:width()} 
option so that
classes are defined by {it:width} {cmd:* floor(}{it:varname/width}{cmd:)}:
contrast {cmd:dotplot, ny()}. 

{p 8 8 2}{cmd:onewayplot} has no options for showing means, means +/- SDs, 
medians or quartiles, in contrast to {cmd:gr7, oneway box} or {cmd:dotplot}. 

{p 4 4 2}Similar plots under a variety of names go back at least as far as
Langren (1644): see Tufte (1997, p.15). Wilkinson (1999) gives several further 
references of historical interest. Chambers {it:et al.} (1983) used the term
{it:one-dimensional scatter plots}. The term {it:oneway plots}
appears to have been introduced by Computing Resource Center (1985) and 
the term {it:strip plots} appears traceable to work by J.W. and P.A. Tukey. 
Wild and Seber (2000) show many interesting examples of oneway plots. 


{title:Options}

{p 4 8 2}{cmd:by(}{it:byvar}{cmd:)} specifies that values of {it:varname} are
to be shown separately by groups defined by {it:byvar}. This option may only be
specified with a single variable.  If {cmd:stack} is also specified, then note
that distinct values of any numeric {it:byvar} are assumed to differ by at
least 1. {cmd:height()} or the prior use of {cmd:egen, group() label} will
fix any problems. See help on {help egen} if desired. 

{p 4 8 2}{cmd:width(}{it:#}{cmd:)} specifies that values are to be rounded in
classes of specified width. Classes are defined by {it:width} 
{cmd:* floor(}{it:varname/width}{cmd:)}. 

{p 4 8 2}{cmd:vertical} specifies that the magnitude axis should be
vertical. 

{p 4 8 2}{cmd:stack} specifies that data points with identical values are to
be stacked, as in {cmd:dotplot}, except that by default there is no binning of
data.

{p 4 8 2}{cmd:height(}{it:#}{cmd:)} controls the amount of graph space
taken up by stacked data points under the {cmd:stack} option above. The default
is 0.8.  This option will not by itself change the appearance of a plot for a
single variable. Note that the height may need to be much smaller
or much larger than 1 with {cmd:by()}, given that the latter takes values
literally. For example, if your classes are 0(45)360, 36 might be 
a suitable height. 

{p 4 8 2}{cmd:centre} or {cmd:center} centres or centers marks
for each variable or group on a hidden line.

{p 4 8 2}{cmd:variablelabels} specifies that multiple variables be labelled by 
their variable labels. The default is to use variable names. 

{p 4 8 2}{cmd:plot(}{it:plot}{cmd:)} provides a way to add other plots to the 
generated graph; see help {help plot_option}.

{p 4 8 2}{it:graph_options} are options of {help scatter}. 


{title:Examples} 

{p 4 8 2}{cmd:. onewayplot mpg}{p_end}
{p 4 8 2}{cmd:. onewayplot mpg, by(foreign)}{p_end}
{p 4 8 2}{cmd:. onewayplot mpg, by(foreign) vertical}{p_end}
{p 4 8 2}{cmd:. onewayplot mpg, by(foreign) vertical stack}{p_end}
{p 4 8 2}{cmd:. onewayplot mpg, by(foreign) vertical stack h(0.4)}

{p 4 8 2}{cmd:. gen pipe = "|"}{p_end}
{p 4 8 2}{cmd:. onewayplot mpg, ms(none) mlabpos(0) mlabel(pipe) mlabsize(*2) stack}

{p 4 8 2}{cmd:. onewayplot price, by(rep78) w(200) stack h(0.4)} 

{p 4 8 2}{cmd:. egen median = median(mpg), by(rep78)}{p_end}
{p 4 8 2}{cmd:. egen loq = pctile(mpg), by(rep78) p(25)}{p_end}
{p 4 8 2}{cmd:. egen upq = pctile(mpg), by(rep78) p(75)}{p_end}
{p 4 8 2}{cmd:. gen rep78_2 = rep78 - 0.2}{p_end}
{p 4 8 2}{cmd:. onewayplot mpg, by(rep78) stack h(0.5) plot(scatter rep78_2 median || rcap upq loq rep78_2, hor legend(off) xtitle("Mileage (mpg)"))}

{p 4 8 2}{cmd:. egen mean = mean(mpg), by(rep78)}{p_end}
{p 4 8 2}{cmd:. gen lb = .}{p_end}
{p 4 8 2}{cmd:. gen ub = .}{p_end}
{p 4 8 2}{cmd:. qui forval i = 1/5 {c -(}}{p_end}
{p 4 8 2}{cmd:. {space 8}ci mpg if rep78 == `i'}{p_end}
{p 4 8 2}{cmd:. {space 8}replace lb = r(lb) if rep78 == `i'}{p_end}
{p 4 8 2}{cmd:. {space 8}replace ub = r(ub) if rep78 == `i'}{p_end}
{p 4 8 2}{cmd:. {c )-}}{p_end}
{p 4 8 2}{cmd:. gen rep78_4 = rep78 + 0.4}{p_end}
{p 4 8 2}{cmd:. onewayplot mpg, by(rep78) stack h(0.25) plot(scatter rep78_4 mean || rcap ub lb rep78_4, hor legend(off) xtitle("Mileage (mpg)"))}


{title:Acknowledgements}

{p 4 4 2}Philip Ender helpfully identified a bug.  


{title:Author}

{p 4 4 2}Nicholas J. Cox, University of Durham, U.K.{break} 
n.j.cox@durham.ac.uk


{title:References} 

{p 4 8 2}Chambers, J.M., W.S. Cleveland, B. Kleiner and P.A.Tukey. 1983. 
{it:Graphical methods for data analysis.} Belmont, CA: Wadsworth. 

{p 4 8 2}Computing Resource Center. 1985. {it:STATA/Graphics User's Guide.} 
Los Angeles, CA: Computing Resource Center. 

{p 4 8 2}Langren, Michael Florent van. 1644. 
{it:La verdadera longitud por mar y tierra.} Antwerp. 

{p 4 8 2}Tufte, E.R. 1997. 
{it:Visual explanations: images and quantities, evidence and narrative.} 
Cheshire, CT: Graphics Press. 

{p 4 8 2}Wild, C.J. and G.A.F. Seber. 2000. 
{it:Chance encounters: a first course in data analysis and inference.} 
New York: John Wiley. 

{p 4 8 2}Wilkinson, L. 1999. Dot plots. {it:American Statistician} 
53: 276-281. 


{title:Also see} 

{p 4 13 2} 
On-line: help for {help dotplot}, {help gr7oneway}, {help histogram}