help for pairplot

Plots of paired observations

pairplot yvar1 yvar2 [xvar] [if exp] [in range] [, horizontal { diff | ratio } base(#) { mean | gmean | sort(sortvarlist) [sortlabel(labelvar)] } trscale(transformation_syntax) y2options(scatter_options) rspike_options scatter_options ]


pairplot plots paired data for yvar1 and yvar2 using parallel lines to show the differences between or ratios of values. By default lines are vertical.

By default, yvar1 and yvar2 are plotted on the y axis. Normally they will have the same units.

If xvar is specified it is used for the x axis: otherwise the order of the observations is used for the x axis.

Other kinds of plots may be obtained through particular options.


horizontal specifies horizontal alignment. The default is vertical.

diff specifies that the y axis should show the difference yvar1 - yvar2.

ratio specifies that the y axis should show the ratio yvar1 / yvar2.

base(#) specifies a baseline for comparison if either diff or ratio is specified. With diff, base has default 0. With ratio, base has default 1.

mean specifies that the x axis should show the mean of yvar1 and yvar2. This option may not be combined with specification of xvar, nor with gmean or sort().

gmean specifies that the x axis should show the geometric mean of yvar1 and yvar2. This option may not be combined with specification of xvar, nor with mean or sort(). It requires that data be positive for both yvar1 and yvar2.

sort(sortvarlist) specifies that the order of the data is determined by sortvarlist. The x axis then shows order of observations on sortvarlist. This option invokes gsort, so that the order of sorting may be indicated by + or - signs. This option may not be combined with specification of xvar, nor with mean or gmean.

sortlabel(labelvar) specifies a variable whose values (or whose value labels if they exist) will be used to label each observation whenever sort() is also specified. Normally this option will be used to specify an identifier variable for labelling the x axis.

trscale() specifies the use of an alternative transformed scale on which to show responses. Any calculations on the fly (e.g. differences or means) will be carried out on that scale and results shown on that scale. Stata syntax should be used with @ as placeholder for untransformed values. For example, to show proportions on a logit scale, specify trscale(logit(@)); to show percents on a logit scale, specify trscale(logit(@/100)). Tools to make associated labels and ticks easier are available on SSC: see ssc desc mylabels.

y2options() specifies options of graph twoway scatter that control the display of the second y variable when horizontal is specified. Understand that at the heart of pairplot is a scatter yvar1 yvar2 xvar with vertical alignment, but a scatter xvar yvar1 || scatter xvar yvar2 with horizontal alignment. The difference means that it is easiest to control display of yvar2 by way of a collective option to be passed to the second scatter.

rspike_options refers to options of graph twoway rspike apart from horizontal.

scatter_options refers to options of graph twoway scatter.


. pairplot after before

. pairplot after before, ms(Oh D)

. pairplot after before, sort(before)

. pairplot after before, diff mean

. pairplot after before, ratio base(2)

. pairplot before after, horizontal sort(before) sortlabel(id) ms(O) mc(green) y2(ms(T) mc(red)) yla(, ang(h))

. pairplot spring fall, sort(fall) sortlabel(student)


Cox, N.J. 2004. Graphing agreement and disagreement. Stata Journal 4: 329-349.

Cox, N.J. 2006. Assessing agreement of measurements and predictions in geomorphology. Geomorphology 76: 332-346.

McNeil, D.R. 1992. On graphing paired data. American Statistician 46, 307-11.


Bob Fitzgerald alerted me to a problem. Erik Beecroft alerted me to an interesting example. David Schwappach alerted me to another problem. Scott Merryman made suggestions on how to solve it. Friedrich Huebler asked a question which prompted improvements to this help.


Nicholas J. Cox, Durham University n.j.cox@durham.ac.uk

Also see

On-line: graph, gsort