*! Version 1.1 26Jun2020 by Mead Over, based on Cox (2009) sjart_gr0041.pdf

help for rankplotVersion 1.2, 27Jun2020

Title

rankplot -- Rank comparison plot: Compare two rankings of the same units

Syntax

rankplot
varname1
varname2
[if] [in]
,
id(idvar)
[options]

Options

Required options
varname1 Name of an existing numeric variable which will be used
for the intitial ranking, on left of plot. Required.

varname2 Name of an existing numeric variable which will be used
for the second or subsequent ranking of the same observations or units
to which the ranking of varname1 is compared.
The ranking of varname2 is displayed on the right of the plot.
Required.

id(idvar) Name of the variable which identifies the units
which are ranked on variables varname1 and varname2.
May be string or numeric, but if numeric, should have
value labels.
Required.

Analysis options
bigchange(integer) The integer specified by this option
determines the size of the change in rank that is big enough
to be flagged in the right margin of the graph. The default is 4.

noktau Suppress the calculation, display and return
of Kendall's tau_a.

keepdups Include duplicate observations. Default is to exclude
observations from the rank comparison that duplicate the id variable
and the variables, varname1 and varname2.

keepvars Specify additional variables to be retained and
displayed by the list option. Observations identical on id,
varname1 and varname2, but different on the variables
specified here are retained even without option keepdups.
Seldom used.

list List in the results window the same information that is
displayed in the rank comparison plot and return a matrix of
that information among the stored results.
The returned matrix contains only the first 100 observations
from the listed results.

Display options
round(real) Precision of rounding for displayed values.
Default is .01. See help for Stata's round() function.

leftalias(string) Optionally substitute this text string
for the variable name at the top of the left-side of the rank plot,
which labels the ranked list of values of varname1.

leftopts(string) Options to control the appearance of the text
labeling the left column of the rank plot.

noleftvalues Suppress display of the values listed on the left
of the rank comparison plot.

rightalias(string) Optionally substitute this text string
for the variable name at the top of the right-side of the rank plot,
which labels the ranked list of values of varname2.

rightopts(string) Options to control the appearance of the text
labeling the right column of the rank plot.

norightvalues Suppress display of the values listed on the right
of the rank comparison plot.

nonote Suppress the automatic display of notes at the bottom margin
display of the rank comparison plot.

shift Shift the entire plot to the left or right by this constant.
Try -0.2 or 0.2. Default is zero.

margadjust(real) Shift to the left or right the left margin
of the observation labels. Try -0.1 or 0.1. Default is zero.

add(real) Add this scalar to the values of both varname1
and varname2 prior to constructing and displaying the rank comparison plot.
This option does not change the observation ranking. The user wishing
to change the scale of observations by a power of ten might consider
installing the user written
rescale
program.

style(style) The default style for the labels and
connecting lines is p1, which will vary in appearance according to the
chosen scheme. With this style(style) option,
the user can specify another color style from p2-p15.

textsize(size) The default size for the all the text in the
figure is vsmall. The textsize(size) option allows the user to specify an altenative
text size from among the options listed here.
If there are more than 60 observations in the data being
ranked, specifying textsize(tiny) will help to distinguish the labels.

mlabcolor(color) This option enables the user to choose a specific color for
the text labels. The option mlabcolor(color) overrides the
option style(style).

lcolor(color) This option allows the user to specify the color
for the lines illustrating rank changes that join the same unit
in the left and right columns. The option lcolor(color) overrides
the option style(style).

grcolor(color) Specify the color of the graph region.
For some graph color schemes, it may be preferable to override the scheme's
choice for the color of the graph region. For example, if using scheme s2color
use this option to specify grcolor(white). See colorstyle.

* Other options are passed through as overall options to Stata's
graph command.

Description

In a 2009 "Speaking Stata" column for the Stata Journal,
Nick Cox provided the Stata code for constructing a "rank comparison plot".
His example, given in his Figure 7, consists of data on the area and the
discharge of the world's 25 largest rivers. While the Amazon is ranked number 1
on both measures, the Nile is ranked number four on area and dead last
on discharge. His Figure 7 dramatically illustrates this and other rank changes.

This contribution to the Stata user community uses Nick Cox's code as the kernel
of a utility that simplifies the production of a rank comparison plot.
The program preserves the data in memory before proceeding and restores it
at the end.

This implementation adds some functionality. The program computes and displays
on the plot the Kendall's Tau rank correlation coefficient and it's p-value.
Optionally it also lists and stores as a matrix the data in the rank comparison plot.
Other options offer some control over the placement of graph elements and
the aesthetics of the display. The companion DO file named example_rankplot.do
illustrates the program use, as do the examples below.

Examples

The DO file with the code from the examples can be downloaded
here.

Use Stata's automobile data set to compare the ranks of foreign cars on two variables, weight and length:

. sysuse auto, clear

The next command shows the default output using the user's default graph scheme.
We limit the analysis to the foreign makes of automobile, because with all 74 observations the plot
becomes illegible.

. rankplot weight length if foreign, id(make)

With the list option, the plotted values are also displayed in Stata's results window.

. rankplot weight length if foreign, id(make) list

After the list option, the results are also available as a matrix among the stored results.

. return list
. matrix list r(list)

Specify the graph scheme as with any Stata graph. Scheme -s1rcolor- has a black background.

. rankplot weight length if foreign, id(make) scheme(s1rcolor)

Here's the same graph using -s2color-.

. rankplot weight length if foreign, id(make) scheme(s2color)

With scheme -s2color-, you may want to specify the color of the graph region.

. rankplot weight length if foreign, id(make) scheme(s2color) grcolor(white)

Or install and use scheme -s2clr_on_white-. Check to see if it is
already installed using the which command.

. which scheme-s2clr_on_white.scheme

If it is not already installed, you can choose to install it here.

Then invoke rankplot with the scheme(scheme_name) option.

. rankplot weight length if foreign, id(make) scheme(s2clr_on_white)

Choose the graph's "style" determines the colors of the labels and
the connecting lines, according to the selected graph scheme.
Possible styles are -p1- through p-15-. For your default scheme,
style -p6- looks like this...

. rankplot weight length if foreign, id(make) style(p6)

...while for the black background scheme, -s1rcolor-, style -p6- looks like this:

. rankplot weight length if foreign, id(make) style(p6) scheme(s1rcolor)

Alternatively, one can directly specify the colors of the labels and
connecting lines.

. rankplot weight length if foreign, id(make) mlabcolor(black) lcolor(red)

Or for a black background...

. rankplot weight length if foreign, id(make) scheme(s1rcolor) mlabcolor(red) lcolor(white)

If the -style- option is specified, it is overridden by either
the -mlabcolor- or the -lcolor- option.

. rankplot weight length if foreign, id(make) style(p6) mlabcolor(black)

Two options are available to accommodate various label lengths.
Using the -shift- option, one can shift the entire rank comparison plot
to the right (with a positive value) or left (with a negative value).

. rankplot weight length if foreign, id(make) shift(-0.2)

Using the -margadjust- option shifts only the labels on the left

. rankplot weight length if foreign, id(make) margadjust(0.1)

The -nonote- option suppresses the automatic notes, but they
can also be suppressed by specifying the user's own -note- option.

. rankplot weight length if foreign, id(make) note(This note replaces the automatic notes.)

Stored results

scalars:
r(N) Number of observations analyzed.

r(bigchange) Threshold for the difference in an observation's ranking on varname1 and varname2 above which an observation is flagged in the plot.

r(nchgrank) Number of observations which change rank by at least bigchange.

Unless the the noktau option suppresses the Kendall's Tau computation,
the following scalars from that computation are also stored. See help for Kendall's Tau.

r(tau_a) The rank correlation statistic displayed in the rankplot graph.

r(tau_b)

r(score)

r(se_score)

r(p) The p-value for the test of the null hypotheisis Ho: abs(r(tau_a)==0.

If the list option is selected, rankplot stores the followiing matrix:

matrices:
r(list) The numerical output displayed by the list option is also stored in this matrix.

References

Cox, Nicholas J. (2009) "Speaking Stata: Paired, parallel, or profile plots
for changes, correlations, and other comparisons," The Stata Journal,
Vol. 9, No. 4, pp. 621-39. Especially Figure 7. Accessible online
here.

Author

Mead Over Contact him at
MOver@CGDev.Org if you observe any
problems. Browse other programs from the Center for Global Development
here.