README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  fig.width = 10,
  fig.height = 7
)

```

# ESDist: Calculate and visualise field-specific ESDs

<!-- badges: start -->
<!-- badges: end -->

## Description
The `ESDist` package is designed to calculate and visualise field-specific
effect size distributions, based on data that can easily be obtained from 
meta-analyses.

[![DOI](https://zenodo.org/badge/532824630.svg)](https://doi.org/10.5281/zenodo.8093616)


### Installation

You can install the `ESDist` package from [GitHub](https://github.com/) with:

```{r, message=FALSE, warning=FALSE, eval = FALSE}
library(devtools)
devtools::install_github("berntgl/ESDist")
```

```{r, echo = FALSE}
devtools::load_all()
```

### Data structure

The `ESDist` package is designed for datasets containing data that can easily 
be extracted from pre-existing meta-analyses. As such, most functions in this 
package work on a dataset that only contains a column with effect sizes. 
However, for some functions and additional functionalities, users might want to 
include some grouping variable or other study information. For the publication
bias-adjusted functions, users need a column with the standard error for each
study effect size. Alternatively, users can include a column with the lower 
bound of the 95% confidence interval, and one for the upper bound. The `ot_dat` 
dataset included in the `ESDist` package contains several columns in addition to 
the effect size column (`yi`).

```{r}
head(ESDist::ot_dat)
```

## esd_plot()
### Plot a simple ESD

The `esd_plot()` function can visualise ESDs based on effect size estimates 
obtained from meta-analyses.

```{r, message=FALSE, warning=FALSE}
library(ESDist)
```

```{r, fig.height = 7}
plot1 <- esd_plot(df = ot_dat,
                  es = yi,
                  es_type = "Hedges' g")

plot1
```


### Plot a weighted ESD

By supplying standard errors to the `esd_plot()` function's `se` argument, and 
setting `weighted` to `TRUE`, it is possible to plot a weighted ESD, based on
the inverse standard error. This effectively means that more information is
drawn from more precise effect size estimates (i.e., effect sizes with a smaller
standard error). 

```{r, fig.height = 7}
plot2 <- esd_plot(df = ot_dat,
                  es = yi,
                  se = sei,
                  weighted = TRUE,
                  es_type = "Hedges' g")

plot2
```

### Plot effect size benchmarks

It is also possible to plot effect size benchmarks based on the 25th, 50th, and 
75th percentiles by adding `method = "quads"` (or based on the 16.65th, 50th, 
and 83.35th percentiles by adding `method = "thirds"`). Following convention, we 
plot these benchmarks based on the distribution of absolute effect sizes by 
setting the `abs` argument to TRUE.

```{r, fig.height = 7}
plot3 <- esd_plot(df = ot_dat,
                  es = yi,
                  es_type = "Hedges' g",
                  method = "quads",
                  abs = TRUE)

plot3
```


### Plot empirical effect size ranges

We can specify the range of effect sizes that is equal to or larger 
than a specified `sesoi`.

```{r, fig.height = 7}
plot4 <- esd_plot(df = ot_dat,
                  es = yi,
                  se = sei,
                  es_type = "Hedges' g",
                  sesoi = 0.3,
                  abs = TRUE)

plot4
```
### Plot ESD per group

Finally, we can plot an ESD for each subgroup in our dataset by feeding our 
grouping variable to the `grouping_var` argument.

```{r, fig.height = 7}
plot5 <- esd_plot(df = ot_dat,
                  es = yi,
                  es_type = "Hedges' g",
                  grouping_var = group)

plot5
```

## esd_plot_pba()
### Plot an adjusted ESD against a raw ESD.
Using limit meta analysis (Schwarzer et al., 2023), we can adjust every 
individual effect size for publication bias and plot the adjusted distribution 
against the raw distribution. To do this, the `esd_plot_pba()` function takes
an additional `se` argument. Otherwise, it takes the same arguments as the 
`esd_plot()` function for additional functionality.


```{r, fig.height = 7}
plot6 <- esd_plot_pba(df = ot_dat,
                       es = yi,
                       se = sei,
                       es_type = "Hedges' g")

plot6
```

## esd_table()
### Calculate effect size benchmarks for whole dataset
By using the `esd_table()` function, you can calculate the effect size 
benchmarks for your dataset by specifying the dataset (`df`), and the column 
containing all effect sizes (`es`). This will give you the effect size 
benchmarks based on the 25th, 50th, and 75th percentiles. Following convention, 
we plot these benchmarks based on the distribution of absolute effect sizes by 
setting the `abs` argument to TRUE.


```{r, message=FALSE, warning=FALSE}
library(ESDist)
library(dplyr)
```

```{r}
table1 <- esd_table(df = ot_dat,
                    es = yi,
                    abs = TRUE)

table1
```

### Calculate effect size benchmarks per group
By specifying `grouping_var`, the user can calculate the effect size benchmarks
per group, for every group with at least three effect sizes. (The number of 
required effect sizes per group can be overwritten by specifying 
`min_group_size`.)

```{r}
table2 <- esd_table(df = ot_dat,
                    es = yi,
                    grouping_var = group,
                    abs = TRUE)

table2
```


### Calculate effect size benchmarks from a weighted distribution
By specifying `se` and setting `weighted` to `TRUE`, it is possible to calculate
benchmark estimates from a distribution that is weighted by inverse standard 
error, taking more information from precise estimates (i.e., effect size 
estimates with a lower standard error)

```{r}
table3 <- esd_table(df = ot_dat,
                    es = yi,
                    se = sei,
                    weighted = TRUE,
                    abs = TRUE)

table3
```


## esd_table_pba()
The `esd_table_pba()` function, similar to the `esd_plot_pba()` function, 
allows users to calculate effect size benchmarks that are adjusted for 
publication bias. Otherwise, this function takes the same additional arguments
as the standard `esd_table()` function. 

```{r}
table4 <- esd_table_pba(df = ot_dat,
                        es = yi,
                        se = sei,
                        abs = TRUE)

table4
```


### Editing and saving tables
The values presented in the table default to two decimal places. This can be 
overwritten by setting `ndec` to the desired number of decimal places. 
Tables can be saved by setting `csv_write` to `TRUE`. Optionally, by setting
`file_name` to a string specifying the sub-directory and file name (e.g., 
`sub-folder/table.csv`), the table can be saved to a specific location with a
specific name. 

## esd_perc()
### Calculating the percentile of a value
Using `esd_perc()`, you can calculate to which percentile of the ESD a given 
value corresponds.

```{r, message=FALSE, warning=FALSE}
library(ESDist)
library(dplyr)
library(ggplot2)
```

```{r}
esd_perc(df = ot_dat,
         es = yi,
         value = 0.3)
```