RankPlot {RankingProject}

Figure containing a plot of ranking data.

Description

RankPlot creates a figure with a plot of ranking data, from among several options for showing uncertainty in the ranked estimates. This function is meant for use within RankPlotWithTable, which draws a ranking table aligned with this plot of the data in one combined figure.

Usage

RankPlot(
  est,
  se,
  names,
  refName = NULL,
  confLevel = 0.9,
  plotType = c("individual", "difference", "comparison", "columns"),
  tiers = 1,
  GH = FALSE,
  multcomp.scope = ifelse(plotType == "individual", "none", "demi"),
  multcomp.type = c("bonferroni", "independence"),
  tikzText = FALSE,
  cex = 1,
  tickWidth = NULL,
  rangeFactor = 1.2,
  textPad = 0,
  legendX = "topleft",
  legendY = NULL,
  legendText = NULL,
  lwdReg = 1,
  lwdBold = 3,
  thetaLine = 1,
  xlim = NULL,
  Bonferroni
)

Arguments

est, se

Vectors containing the point estimate and its standard error for each area.

names

Vector containing the name of each area. Abbreviations may be preferable to full names (e.g. "CO" instead of "Colorado") since these names will be displayed directly on the plot.

refName

String containing the name of the reference area; must be one of the values in names. Required for plotType = c("difference", "comparison"). Optional for plotType = "individual" (where it only determines the row above/below which the names are plotted to the right/left of the intervals; if unspecified, defaults to median rank); or for plotType = "columns" (where it selects one column to be highlighted by vertical lines, if specified).

confLevel

Number between 0 and 1: confidence level for individual (uncorrected) hypothesis tests and/or confidence intervals. E.g. with plotType = "individual", confLevel = 0.9 will plot individual 90% confidence intervals. If using GH = TRUE and/or multcomp.scope != "none", the Goldstein-Healy and/or Bonferroni/Independence corrections will be applied to the confLevel baseline.

plotType

Which type of ranking plot to use. See vignettes for examples and details.

• "individual" is used for usual individual confidence intervals, with or without Goldstein-Healy adjustment and/or (demi or full) Bonferroni/Independence corrections.

• "difference" shows confidence intervals for the differences between the reference area refName and all other areas.

• "comparison" also compares the reference area refName to all others, but using the "comparison intervals" of Almond et al. (2000).

• "columns" plots a grid of shaded columns, where each column uses shading to report demi-Bonferroni/Independence-corrected significance tests for comparing the reference area (labeled at the bottom of the column) with all other areas.

tiers

Numeric, either 1 for usual confidence intervals, or 2 for two-tiered intervals. 2 can only be used with plotType = "individual", when either GH = TRUE or multcomp.scope != "none" or both. In that case, the "inner tiers" run between each interval's cross-bars, and the "outer tiers" run past the cross-bars all the way to the ends of each interval. One of the tiers will show uncorrected confLevel*100% confidence intervals, and the other tier will show the Goldstein-Healy and/or Bonferroni/Independence adjusted intervals. A legend will show which tier is which; usually Goldstein-Healy alone gives shorter intervals (inner tier), but Bonferroni/Independence corrections make them into longer intervals (outer tier).

GH

Logical, for whether or not to plot adjusted confidence intervals at an "average" confLevel*100% confidence level as in Goldstein and Healy (1995). Can only be used with plotType = "individual".

multcomp.scope

Whether to correct for multiple comparisons, and if so, for how many (by a correction to the confidence level of the tests or intervals). "none" performs no correction; "demi" corrects for comparing one reference area to all n-1 other areas; and "full" corrects for comparing all possible choose(n, 2) pairs of areas. Also use the multcomp.type argument to specify whether the correction should rely on Bonferroni (default) or on an assumption of Independence. If GH = TRUE, the Goldstein-Healy adjustment is performed first, and any Bonferroni/Independence correction is applied afterwards. Settings "none" and "full" can only be used with plotType = "individual"; all other plot types use the setting "demi".

multcomp.type

(Only used if multcomp.scope != "none".) Whether multiple comparison corrections should use a Bonferroni correction ("bonferroni") or an independence-based correction ("independence"). See Section 4 of the paper "A Joint Confidence Region..." (2020, JRSS-C) for the difference in these two corrections.

tikzText

Logical, for whether or not to format text for tikz plotting.

cex

Character expansion factor for the points use to plot each area's point estimate, and for the text used to plot each area's name next to its interval.

tickWidth

Numeric height of the cross-bars on interval endpoints (or inner tiers, if tiers = 2). The function tries to leave a reasonable amount of space between intervals plotted in different rows, but sometimes it may help to adjust tickWidth manually.

rangeFactor

Numeric multiple by which to expand the range of the data when setting the x-axis limits. The function tries to leave sufficient room for plotting margins of error and names next to each area, but sometimes it may help to adjust rangeFactor manually.

textPad

Numeric amount by which to shift the text of names past the interval endpoints when plotting. Positive values shift outwards (towards the edges of the plot); negative values shift inwards.

legendX, legendY

The x and y co-ordinates used to position the legend; see legend for details on specifying x by keyword.

legendText

String, or string vector, with legend text. By default, each plot type adds informative legend text, but the user may override. To remove legends entirely, set legendText=NA.

lwdReg

Positive number for the line width of regular lines. Used for all intervals when plotType = "individual", or for intervals not significantly different from the reference area when plotType = c("difference", "comparison").

lwdBold

Positive number for the line width of bold lines. Used for intervals significantly different from the reference area when plotType = c("difference", "comparison").

thetaLine

Number for how many lines below bottom axis to display "theta" or other default x-axis labels (which depend on plotType).

xlim

Vector of 2 numbers for x-axis limits. If NULL, will be automatically set using range of data expanded by rangeFactor.

Bonferroni

Deprecated name for the multcomp.scope argument.

Details

Users may wish to modify this code and write their own plot function, which can be swapped into figureFunction within RankPlotWithTable. Be aware that RankPlotWithTable uses layout to arrange the table and plot side-by-side, so layout cannot be used within a new figureFunction.

See Goldstein and Healy (1995) for details on the "average" confidence level procedure used when GH = TRUE. See Almond et al. (2000) for details on the "comparison intervals" procedure.

References

Almond, R.G., Lewis, C., Tukey, J.W., and Yan, D. (2000). "Displays for Comparing a Given State to Many Others," The American Statistician, vol. 54, no. 2, 89-93.

Goldstein, H. and Healy, M.J.R. (1995). "The Graphical Presentation of a Collection of Means," JRSS A, vol. 158, no. 1, 175-177.

See Also

RankPlotWithTable and RankTable.

Examples

# Plot of 90% confidence intervals for differences
# between each state and Colorado, with demi-Bonferroni correction,
# for US states' mean travel times to work, from the 2011 ACS
data(TravelTime2011)
with(TravelTime2011,
     RankPlot(est = Estimate.2dec, se = SE.2dec,
              names = Abbreviation, refName = "CO",
              confLevel = 0.90, cex = 0.6,
              plotType = "difference"))