-
-
Notifications
You must be signed in to change notification settings - Fork 54
/
README.Rmd
217 lines (155 loc) · 7.65 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
---
# correlation <img src='man/figures/logo.png' align="right" height="139" />
```{r README-1, warning=FALSE, message=FALSE, echo=FALSE}
library(ggplot2)
library(poorman)
library(correlation)
options(digits = 2)
knitr::opts_chunk$set(
collapse = TRUE,
dpi = 300,
message = FALSE,
warning = FALSE,
fig.path = "man/figures/"
)
```
[](https://doi.org/10.21105/joss.02306) [](https://cranlogs.r-pkg.org/) [](https://CRAN.R-project.org/package=correlation)
<!-- [](https://cran.r-project.org/package=correlation) -->
`correlation` is an [**easystats**](https://github.com/easystats/easystats) package focused on correlation analysis. It's lightweight, easy to use, and allows for the computation of many different kinds of correlations, such as **partial** correlations, **Bayesian** correlations, **multilevel** correlations, **polychoric** correlations, **biweight**, **percentage bend** or **Sheperd's Pi** correlations (types of robust correlation), **distance** correlation (a type of non-linear correlation) and more, also allowing for combinations between them (for instance, *Bayesian partial multilevel correlation*).
# Citation
You can cite the package as follows:
Makowski, D., Ben-Shachar, M. S., Patil, I., \& Lüdecke, D. (2020). Methods and algorithms for correlation analysis in R. _Journal of Open Source Software_,
*5*(51), 2306. https://doi.org/10.21105/joss.02306
Makowski, D., Wiernik, B. M., Patil, I., Lüdecke, D., \& Ben-Shachar, M. S. (2022). *correlation*: Methods for correlation analysis [R package]. https://CRAN.R-project.org/package=correlation (Original work published 2020)
# Installation
[](https://cran.r-project.org/package=correlation) [](https://easystats.r-universe.dev) [](https://github.com/easystats/correlation/actions)
[](https://app.codecov.io/gh/easystats/correlation)
The *correlation* package is available on CRAN, while its latest development version is available on R-universe (from _rOpenSci_).
Type | Source | Command
---|---|---
Release | CRAN | `install.packages("correlation")`
Development | R-universe | `install.packages("correlation", repos = "https://easystats.r-universe.dev")`
Once you have downloaded the package, you can then load it using:
```{r, eval=FALSE}
library("correlation")
```
> **Tip**
>
> **Instead of `library(correlation)`, use `library(easystats)`.**
> **This will make all features of the easystats-ecosystem available.**
>
> **To stay updated, use `easystats::install_latest()`.**
# Documentation
Check out package [website](https://easystats.github.io/correlation/) for documentation.
# Features
The *correlation* package can compute many different types of correlation,
including:
✅ **Pearson's correlation**<br>
✅ **Spearman's rank correlation**<br>
✅ **Kendall's rank correlation**<br>
✅ **Biweight midcorrelation**<br>
✅ **Distance correlation**<br>
✅ **Percentage bend correlation**<br>
✅ **Shepherd's Pi correlation**<br>
✅ **Blomqvist’s coefficient**<br>
✅ **Hoeffding’s D**<br>
✅ **Gamma correlation**<br>
✅ **Gaussian rank correlation**<br>
✅ **Point-Biserial and biserial correlation**<br>
✅ **Winsorized correlation**<br>
✅ **Polychoric correlation**<br>
✅ **Tetrachoric correlation**<br>
✅ **Multilevel correlation**<br>
An overview and description of these correlations types is [**available here**](https://easystats.github.io/correlation/articles/types.html). Moreover,
many of these correlation types are available as **partial** or within a
**Bayesian** framework.
# Examples
The main function is [`correlation()`](https://easystats.github.io/correlation/reference/correlation.html), which builds on top of [`cor_test()`](https://easystats.github.io/correlation/reference/cor_test.html) and comes with a number of possible options.
## Correlation details and matrix
```{r README-4}
results <- correlation(iris)
results
```
The output is not a square matrix, but a **(tidy) dataframe with all correlations tests per row**. One can also obtain a **matrix** using:
```{r README-5}
summary(results)
```
Note that one can also obtain the full, **square** and redundant matrix using:
```{r README-6}
summary(results, redundant = TRUE)
```
```{r README-7}
library(see)
results %>%
summary(redundant = TRUE) %>%
plot()
```
## Correlation tests
The `cor_test()` function, for pairwise correlations, is also very convenient for making quick scatter plots.
```{r README-corr}
plot(cor_test(iris, "Sepal.Width", "Sepal.Length"))
```
## Grouped dataframes
The `correlation()` function also supports **stratified correlations**, all within the
*tidyverse* workflow!
```{r README-8}
iris %>%
select(Species, Sepal.Length, Sepal.Width, Petal.Width) %>%
group_by(Species) %>%
correlation()
```
## Bayesian Correlations
It is very easy to switch to a **Bayesian framework**.
```{r README-9}
correlation(iris, bayesian = TRUE)
```
## Tetrachoric, Polychoric, Biserial, Biweight...
The `correlation` package also supports different types of methods, which can
deal with correlations **between factors**!
```{r README-10}
correlation(iris, include_factors = TRUE, method = "auto")
```
## Partial Correlations
It also supports **partial correlations** (as well as Bayesian partial correlations).
```{r README-11}
iris %>%
correlation(partial = TRUE) %>%
summary()
```
## Gaussian Graphical Models (GGMs)
Such partial correlations can also be represented as **Gaussian Graphical
Models** (GGM), an increasingly popular tool in psychology. A GGM traditionally
include a set of variables depicted as circles ("nodes"), and a set of lines
that visualize relationships between them, which thickness represents the
strength of association (see [Bhushan et al., 2019](https://www.frontiersin.org/articles/10.3389/fpsyg.2019.01050/full)).
```{r README-12}
library(see) # for plotting
library(ggraph) # needs to be loaded
plot(correlation(mtcars, partial = TRUE)) +
scale_edge_color_continuous(low = "#000004FF", high = "#FCFDBFFF")
```
## Multilevel Correlations
It also provide some cutting-edge methods, such as Multilevel (partial)
correlations. These are are partial correlations based on linear mixed-effects
models that include the factors as **random effects**. They can be see as
correlations *adjusted* for some group (*hierarchical*) variability.
```{r README-13}
iris %>%
correlation(partial = TRUE, multilevel = TRUE) %>%
summary()
```
However, if the `partial` argument is set to `FALSE`, it will try to convert the
partial coefficient into regular ones.These can be **converted back** to full
correlations:
```{r README-14}
iris %>%
correlation(partial = FALSE, multilevel = TRUE) %>%
summary()
```
# Contributing and Support
In case you want to file an issue or contribute in another way to the package, please follow [this guide](https://easystats.github.io/correlation/CONTRIBUTING.html). For questions about the functionality, you may either contact us via email or also file an issue.
# Code of Conduct
Please note that this project is released with a
[Contributor Code of Conduct](https://easystats.github.io/correlation/CODE_OF_CONDUCT.html). By participating in this project you agree to abide by its terms.