https://github.com/dcousin3/superb
Summary plots with adjusted error bars
https://github.com/dcousin3/superb
error-bars plotting r statistics summary-plots summary-statistics visualization
Last synced: 5 months ago
JSON representation
Summary plots with adjusted error bars
- Host: GitHub
- URL: https://github.com/dcousin3/superb
- Owner: dcousin3
- Created: 2019-07-21T19:59:16.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2025-01-24T02:48:41.000Z (about 1 year ago)
- Last Synced: 2025-04-02T06:18:11.565Z (11 months ago)
- Topics: error-bars, plotting, r, statistics, summary-plots, summary-statistics, visualization
- Language: R
- Homepage: https://dcousin3.github.io/superb
- Size: 307 MB
- Stars: 19
- Watchers: 1
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.Rmd
- Changelog: NEWS.md
Awesome Lists containing this project
README
---
output: github_document
bibliography: "inst/REFERENCES.bib"
csl: "inst/apa-6th.csl"
---
# superb: Summary plots with adjusted error bars
[](https://cran.r-project.org/package=superb)
```{r, echo = FALSE, message = FALSE, results = 'hide', warning = FALSE}
cat("this will be hidden; use for general initializations.\n")
library(superb)
library(ggplot2)
options("superb.feedback" = "none") # shut down all information
```
The library `superb` offers two main functionalities. The first and foremost functionnality
is to obtain plots with adjusted error bars. The main function is `superb()`
but you can also use `superbShiny()` for a graphical user interface requiring
no programming nor scripting. See the nice tutorial by @w21.
The purpose of the function `superb()` 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, i.e., in isolation, or
difference, i.e., for pair-wise comparisons),
to the sampling method (simple randomized samples or cluster
randomized samples) and to the population size (infinite or of a specific
size). The `superb(..., showPlot=FALSE)` argument does not generate the plot but returns the
summary statistics and the interval boundaries. These can afterwards
be sent to other plotting environments.
The second, subsidiary, 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 quite handy to test statistical procedures and plotting procedures
such as `superb()`.
# Installation
The official **CRAN** version can be installed with
```{r, echo = TRUE, eval = FALSE}
install.packages("superb")
library(superb)
```
The development version `r packageVersion("superb")` can be accessed through GitHub:
```{r, echo = TRUE, eval = FALSE}
devtools::install_github("dcousin3/superb")
library(superb)
```
```{r, echo = FALSE, eval = FALSE, results = FALSE}
library(superb)
```
# Examples
The easiest is to use the graphical interface which can be
launched with
```{r, echo = TRUE, eval = FALSE}
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)
```{r, fig.alt="mean+-95%CI", fig.cap="**Figure 1**. A simple _superb_ plot"}
superb(len ~ dose + supp, ToothGrowth )
```
In the above, the default summary statistic, the mean, is used. The error
bars are, by default, the 95% confidence intervals (of the mean). 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 along with the default 95% confidence interval of the median here (the correct
function is automatically selected):
```{r, fig.alt="median+-95%CI", fig.cap="**Figure 2**. A median _superb_ plot"}
superb(len ~ dose + supp, ToothGrowth,
statistic = "median")
```
As a third example, we illustrate the harmonic means
`hmean` along with 99.9% confidence intervals of the harmonic
mean displayed using bars:
```{r, fig.alt="harmonic mean+-95%CI", fig.cap="**Figure 4**. A simple _superb_ plot with 99.9%CI"}
superb(len ~ dose + supp, ToothGrowth,
statistic = "hmean",
errorbar = "CI", gamma = 0.999,
plotLayout = "bar")
```
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 30 simulated participants in
a 3 x 6 design with 6 daily repeated-measures on `Day`s. The
factor `Day` is modeled as impacting the scores (increasing by 3 points
per day) whereas difficulty is beneficial for the C level only:
```{r}
set.seed(663) # for reproducibility
testdata <- GRD(
RenameDV = "score",
SubjectsPerGroup = 10,
BSFactors = "Difficulty(A,B,C)",
WSFactors = "Day(6)",
Population = list(mean = 75,stddev = 10,rho = 0.8),
Effects = list( "Difficulty" = custom(-5,-5,+10), "Day" = slope(3) )
)
head(testdata)
```
This is here that the full benefits of `superb()` is seen: with
just a few adjustments, you can obtained decorrelated error bars
with the Correlation-adjusted (CA), the Cousineau-Morey (CM) or
the Loftus & Masson (CM) techniques:
```{r, fig.alt="mean+-95%CI", fig.cap="**Figure 4**. Multiple _superb_ plots"}
library(gridExtra) # for grid.arrange
library(RColorBrewer) # for nicer color palette
plt1 <- superb( crange(score.1, score.6) ~ Difficulty,
testdata, WSFactors = "Day(6)",
plotLayout = "line"
) + ylim(50,100) + labs(title = "No adjustments") +
theme_bw() + ylab("Score") +
scale_color_brewer(palette="Dark2")
plt2 <- superb( crange(score.1, score.6) ~ Difficulty,
testdata, WSFactors = "Day(6)",
adjustments = list(purpose = "difference", decorrelation = "CA"),
plotLayout = "line"
)+ ylim(50,100) + labs(title = "correlation- and difference-adjusted") +
theme_bw() + ylab("Score") +
scale_color_brewer(palette="Dark2")
grid.arrange(plt1,plt2, ncol=2)
```
Even better, the simulated scores can be illustrated using
more elaborate layouts such as the ``pointjitter`` layout which,
in addition to the mean and confidence interval, shows the raw
data using jitter dots:
```{r, fig.alt="mean+-95%CI", fig.cap="**Figure 5**. A decorated _superb_ plot"}
superb( crange(score.1, score.6) ~ Difficulty,
testdata, WSFactors = "Day(6)",
adjustments = list(purpose = "difference", decorrelation = "CM"),
plotLayout = "pointjitter",
errorbarParams = list(color = "purple"),
pointParams = list( size = 3, color = "purple")
) +
theme_bw() + ylab("Score") +
scale_color_brewer(palette="Dark2")
```
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 ``superb()``.
Lastly, we could aim for a radar (a.k.a. circular) plot with
```{r, fig.alt="mean+-95%CI", fig.cap="**Figure 6**. A simple _superb_ plot"}
superb( crange(score.1, score.6) ~ Difficulty, testdata,
WSFactors = "Day(6)",
adjustments = list(purpose = "difference", decorrelation = "CM"),
plotLayout = "circularpointlinejitter",
factorOrder = c("Day", "Difficulty"),
pointParams = list( size = 3 ),
jitterParams = list(alpha=0.25),
errorbarParams= list(width=0.33, color = "black")
) +
theme_bw() + ylab("") +
theme(panel.border = element_blank(), text = element_text(size = 16) ) +
scale_color_brewer(palette="Dark2") +
theme(axis.line.y = element_blank(),
axis.text.y=element_blank(), axis.ticks.y=element_blank())
```
Every time, you get error bars for free! no need to compute them on the side, no
need to worry about the adjustments (whether you want stand-alone error
bars or adjusted for purpose or correlation, it is all just one option).
Also, keep in mind that it is easy to change the default (mean +- 95%
confidence intervals) to any other summary statistics --e.g., median-- and
any other measure of error --e.g., standard error, standard deviation,
inter-quartile range, name it--; you can find some responses in the vignettes
or on stackExchange or just open an issue on the github repository.
# For more
_superb_ is for __summary plot with error bars__, as simple as that.
The library `superb` makes it easy to illustrate summary statistics
along with 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](https://dcousin3.github.io/superb/).
A general introduction to the `superb` framework underlying this
library is published
at *Advances in Methods and Practices in Psychological Sciences* [@cgh21]. Also, most of the formulas for confidence intervals when statistics other than the mean are displayed can be found in [@htc14,@htc15].
# References