-------------------------------------------------------------------------------
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 ]


Description

    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.


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.


Examples

    . 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)


References 

    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.


Acknowledgements

    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.


Author

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


Also see 

    On-line: graph, gsort