-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathREADME.Rmd
218 lines (175 loc) · 8.24 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
---
output: github_document
bibliography: "inst/REFERENCES.bib"
csl: "inst/apa-6th.csl"
---
# superb: Summary plots with adjusted error bars
<img src="logo.png" align="right" alt="" width="120" />
<!-- badges: start -->
[](https://cran.r-project.org/package=superb)
<!-- badges: end -->
```{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 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 `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. Only
the factor `Day` is modeled as impacting the scores (increasing by 3 points on the
second day):
```{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