nightplot: Summarize bounded data using nightplots

In chrisadolph/tileForShiny: Plot multiple graphical displays in a tiled layout with automated or customizable titles, axes, and annotations

Description

Initializes a scatterplot of the relationship between one known variable and another variable known within an upper and lower bound. All observations are represented by equal area lozenges which are stretched between the bounds on the uncertain variable.

Usage

 nightplot(...)  

Arguments

...

Any number of arguments given below. At a minimum, inputs must include data for one known dimension (x, top, top, or right), and the bounds on an orthogonal dimension. All inputs should be identified by appropriate tags; i.e., use nightplot(x=myxvar, ylower=myylowervar, yupper=myyuppervar), not nightplot(myxvar, myylowervar, myyuppervar)

Details

This function does no plotting; instead, it creates a nightplot object, or trace of plotting data, to be drawn on one or more plots in a tiled arrangement of plots. To complete the drawing include the nightplot object as an input to tile, from which users can set further options including plot and axis titles, axis scaling and titles.

Nightplots are an experimental new plot aimed at addressing a problem in usual displays of bounded information, which arises most often when an estimated quantity is plotted against a known covariate. Two approaches—“lines” and “bubbles”—are most common. The “lines” approach draws a line between the lower and upper bound (see the first panel in the example below). The “bubbles” approach scales the plotted symbol—usually a circle—to be larger for more precisely known cases (see the second panel in the example below). Neither approach is entirely satisfactory. Lines between bounds give greatest visual emphasis to the least understood cases, and often hide the precisely known cases, even though these are exactly the most important observations for inference. Scaled bubbles restore the proper emphasis, but completely lose the clear presentation of the upper and lower bounds given by the lines approach.

Nightplots combine the virtues of each technique to draw a lozenge, or tablet shape, between the upper and lower bounds. All lozenges are scaled to have the same area, so cases with wide bounds will be stretch into thin, less noticeable bands, while precisely known cases will become large tablets or even circles centered on the known value. Additionally, more precisely known cases are plotted in bright yellow shades, while cases with wide bounds are shown as desaturated grays. Finally, the best known cases are plotted on top of the least known cases.

Run through tile, output from nightplot will yield a finished plot. The plot cannot be easily modified after creation. Rather, users should include in the initial call to tile additional traces for all desired annotations (text, symbols, lines, or polygons) to the finished plot.

Value

A nightplot object, used only as an input to tile.

nightplot-specific parameters

A call to nightplot must provide data on at least one and possibly two orthogonal dimensions of the plot:

x

coordinate vector of data to plot, attached to the x axis. If x is provided without xlower and xupper, it will be treated as the known dimension. If xlower and xupper are also provided, then x is optional, and if given will be treated as a bounded estimate on the x dimension.

y

coordinate vector of data to plot, attached to the y axis. If y is provided without ylower and yupper, it will be treated as the known dimension. If ylower and yupper are also provided, then y is optional, and if given will be treated as a bounded estimate on the y dimension.

top

coordinate vector of data to plot, attached to the top axis. If top is provided without toplower and topupper, it will be treated as the known dimension. If toplower and topupper are also provided, then top is optional, and if given will be treated as a bounded estimate on the top dimension.

right

coordinate vector of data to plot, attached to the right axis. If right is provided without rightlower and rightupper, it will be treated as the known dimension. If rightlower and rightupper are also provided, then right is optional, and if given will be treated as a bounded estimate on the right dimension.

Additionally, a call to nightplot should provide a set of bounds on each of the points in exactly one of the above dimensions:

xlower

vector of same length as x containing user-provided lower bounds.

xupper

vector of same length as x containing user-provided upper bounds.

ylower

vector of same length as y containing user-provided lower bounds.

yupper

vector of same length as y containing user-provided upper bounds.

toplower

vector of same length as top containing user-provided lower bounds.

topupper

vector of same length as top containing user-provided upper bounds.

rightlower

vector of same length as right containing user-provided lower bounds.

rightupper

vector of same length as right containing user-provided upper bounds.

The following inputs are all optional, and other features of nightplot.

truex

vector of the same length of x containing the true values of each case on the x dimension. Only provide this input if x is the unknown dimension (ie, you have also provided xlower and xupper).

truey

vector of the same length of y containing the true values of each case on the y dimension. Only provide this input if y is the unknown dimension (ie, you have also provided ylower and yupper).

truetop

vector of the same length of top containing the true values of each case on the top dimension. Only provide this input if top is the unknown dimension (ie, you have also provided toplower and topupper).

trueright

vector of the same length of right containing the true values of each case on the right dimension. Only provide this input if right is the unknown dimension (ie, you have also provided rightlower and rightupper).

bw

Logical, indicates whether to draw a gray-scale version of the nightplot, with a white background and black or gray lozenges (TRUE, or to draw the color version, with a black background and yellow or gray lozenges (FALSE). Default is FALSE.

plot

scalar or vector, the plot(s) in which this trace will be drawn; defaulting to the first plot. Plots are numbered consecutively from the top left, row-by-row. Thus in a 2 x 3 tiling, the first plot in the second row is plot number 4.

In addition to these nightplot-specific parameters, users may provide any of the generic tile parameters documented in pointsTile.

Author(s)

Christopher Adolph [e-mail]

See Also

tile, scatter

Examples

# Generate some data
n <- 100
x <- runif(n)
disturbance <- rnorm(n,sd=0.05)
y <- 0.25 + 0.5*x + disturbance
firsthalf <- 1:80
secondhalf <- 81:100

# Some bad "estimates" for the first half of the data
ylower <- yupper <- yhat <- rep(NA,n)
badbounds <- sort(runif(2*n))
ylower[firsthalf] <- badbounds[firsthalf]
yupper[firsthalf] <- rev(badbounds)[firsthalf]
yhat[firsthalf] <- apply(cbind(yupper[firsthalf], ylower[firsthalf]), 1, mean)

# Some "good" estimates for the second half of the data
res <- lm(y[secondhalf] ~ x[secondhalf])
fitted <- predict(res,interval="confidence")
yhat[secondhalf] <- fitted[,1]
ylower[secondhalf] <- fitted[,2]
yupper[secondhalf] <- fitted[,3]

# Lines approach to plotting bounded data
trace1 <- scatter(x=x,
                  y=yhat,
                  ylower=ylower,
                  yupper=yupper,
                  size = 0.5,
                  plot = 1
                  )

# Bubbles approach to plotting bounded data
inversebndwidth <- 1/(yupper - ylower)
trace2 <- pointsTile(x=x,
                     y=yhat,
                     pch=1,
                     size=0.25*inversebndwidth,
                     markers=TRUE,
                     plot=2
                     )

# Nightplot approach to plotting bounded data 
trace3 <- nightplot(x=x,
                    y=yhat,
                    ylower=ylower,
                    yupper=yupper,
                    plot = 3
                    )

# Nightplot approach (grayscale)
trace4 <- nightplot(x=x,
                    y=yhat,
                    ylower=ylower,
                    yupper=yupper,
                    truey=y,
                    bw=TRUE,
                    plot = 4
                    )

# Tile all four approaches
tile(trace1, trace2, trace3, trace4,
     RxC=c(2,2),
     limits=c(0,1,0,1),
     frame=TRUE,
     xaxistitle=list(labels="A precise quantity"),
     yaxistitle=list(type="row",labels=c("A bounded quantity",
                                         "A bounded quantity")),
     maintitle=list(labels="Plots for Bounded Variables"),
     plottitle=list(labels=c("Lines", "Bubbles", "Nightplot", "Grayscale Nightplot"))
     )        

chrisadolph/tileForShiny documentation built on Feb. 6, 2022, 12:34 a.m.