Learn R Programming

superb: Summary plots with adjusted error bars

The library superb offers two main functionalities. First, it can be used to obtain plots with adjusted error bars. The main function is superbPlot() but you can also use superbShiny() for a graphical user interface requiring no programming nor scripting. See the nice tutorial by Walker (2021).

The purpose of superbPlot() is to provide a plot with summary statistics and correct error bars. With simple adjustments, the error bar are adjusted to the design (within or between), to the purpose (single or pair-wise differences), to the sampling method (simple randomized samples or cluster randomized samples) and to the population size (infinite or of a specific size). The superbData() function does not generate the plot but returns the summary statistics and the interval boundaries. These can afterwards be sent to other plotting environment.

The second functionality is to generate random datasets. The function GRD() is used to easily generate random data from any design (within or between) using any population distribution with any parameters, and with various effect sizes. GRD() is useful to test statistical procedures and plotting procedures such as superbPlot().

Installation

The official CRAN version can be installed with

install.packages("superb")
library(superb)

The development version 0.95.15 can be accessed through GitHub:

devtools::install_github("dcousin3/superb")
library(superb)

Examples

The easiest is to use the graphical interface which can be launched with

superbShiny()

The following examples use the script-based commands.

Here is a simple example illustrating the ToothGrowth dataset of rats (in which the dependent variable is len) as a function of the dose of vitamin and the form of the vitamin supplements supp (pills or juice)

superbPlot(ToothGrowth, 
    BSFactors = c("dose","supp"), 
    variables = "len" )

In the above, the default summary statistic, the mean, is used. The error bars are, by default, the 95% confidence intervals. These two choices can be changed with the statistic and the errorbar arguments.

This second example explicitly indicates to display the median instead of the default mean summary statistics

superbPlot(ToothGrowth, 
    BSFactors = c("dose","supp"), 
    variables = "len",
    statistic = "median")

As a third example, we illustrate the harmonic means hmean along with 99.9% confidence intervals using lines:

superbPlot(ToothGrowth, 
    BSFactors = c("dose","supp"), 
    variables = "len",
    statistic = "hmean", 
    errorbar = "CI", gamma = 0.999,
    plotStyle = "line")

The second function, GRD(), can be used to generate random data from designs with various within- and between-subject factors. This example generates scores for 300 simulated participants in a 3 x 2 design with repeated-measures on Days. Only the factor Day is modeled as impacting the scores (the reduce by 3 points on the second day):

testdata <- GRD(
    RenameDV   = "score", 
    SubjectsPerGroup = 100, 
    BSFactors  = "Difficulty(A,B,C)", 
    WSFactors  = "Day(2)",
    Population = list(mean = 75,stddev = 12,rho = 0.5),
    Effects    = list("Day" = slope(-3) )
)
head(testdata)
##   id Difficulty  score.1  score.2
## 1  1          A 71.43951 56.40627
## 2  2          A 54.96865 47.87347
## 3  3          A 66.92676 74.19139
## 4  4          A 59.06399 65.31043
## 5  5          A 81.31176 72.11825
## 6  6          A 67.89877 81.92877

The simulated scores are illustrated using using a more elaborated layout, the pointjitterviolin which, in addition to the mean and confidence interval, shows the raw data using jitter dots and the distribution using a violin plot:

superbPlot(testdata, 
    BSFactors  = "Difficulty", 
    WSFactors  = "Day(2)",
    variables = c("score.1","score.2"),
    plotStyle = "pointjitterviolin",
    errorbarParams = list(color = "purple"),
    pointParams = list( size = 3, color = "purple")
)

In the above example, optional arguments errorbarParams and pointParams are used to inject specifications in the error bars and the points respectively. When these arguments are used, they override the defaults from superbPlot().

For more

As seen, the library superb makes it easy to illustrate summary statistics along with the error bars. Some layouts can be used to visualize additional characteristics of the raw data. Finally, the resulting appearance can be customized in various ways.

The complete documentation is available on this site.

A general introduction to the superb framework underlying this library is published at Advances in Methods and Practices in Psychological Sciences (Cousineau, Goulet, & Harding, 2021).

References

Walker, J. A. L. (2021). Summary plots with adjusted error bars (superb). Retrieved from https://www.youtube.com/watch?v=rw_6ll5nVus

Copy Link

Version

Install

install.packages('superb')

Monthly Downloads

736

Version

0.95.15

License

GPL-3

Maintainer

Denis Cousineau

Last Published

August 17th, 2024

Functions in superb (0.95.15)

dataFigure1

Data for Figure 1
dataFigure2

Data for Figure 2
CousineauLaurencelleLambda

Cousineau-Laurencelle's lambda correction for cluster-randomized sampling
poolSDTransform

pooled standard deviation transform
summaryStatistics

Additional summary statistics
superb-package

superb: Summary Plots with Adjusted Error Bars
superbData

Obtain summary statistics with correct error bars.
superbPlot

summary plot of any statistics with adjusted error bars.
dataFigure3

Data for Figure 3
MauchlySphericityTest

Mauchly's test of Sphericity
showSignificance

Annotate significance of results on plots
runDebug

runDebug
superbToWide

superbToWide: Reshape long data frame to wide, suitable for superbPlot
makeTransparent

makes ggplots with transparent elements
geom_superberrorbar

geom_superberrorbar for expanded error bar displays
superbPlot.line

superbPlot 'line' layout
twoStepTransform

two-step transform for subject centering and bias correction
superbShiny

User Interface to get summary plot of any statistics with adjusted error bars.
superbPlot.halfwidthline

superbPlot 'halfwidthline' layout
superbPlot.lineBand

superbPlot 'lineBand' layout
superbPlot.point

superbPlot 'point' layout
GRD

Generate random data
superbPlot.pointjitterviolin

superbPlot point, jitter and violin plot layout
superbPlot.raincloud

superbPlot 'raincloud' layout
dataFigure4

Data for Figure 4
superbPlot.boxplot

superbPlot 'boxplot' layout
superbPlot.bar

superbPlot 'bar' layout
precisionMeasures

Precision measures
precisionMeasureWithCustomDF

Confidence intervals with custom degree of freedom
slope

Effect description
superbPlot.pointindividualline

superbPlot point and individual-line layout for within-subject design
superbPlot.pointjitter

superbPlot point-and-jitter dots layout
subjectCenteringTransform

subject-centering transform
biasCorrectionTransform

bias-correction transform
HyunhFeldtEpsilon

Hyunh and Feldt's epsilon measure of sphericity
WelchDegreeOfFreedom

Welch's rectified degree of freedom
WinerCompoundSymmetryTest

Winer's test of compound symmetry
ShroutFleissICC1

Shrout and Fleiss intra-class correlation functions
TMB1964r

Data of Tulving, Mandler, & Baumal, 1964 (reproduction of 2021)
bootstrapPrecisionMeasures

Bootstrapped measures of precision
measuresWithMissingData

Measures with missing data