---
title: "Converting statistics to a data frame"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Converting statistics to a data frame}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r, echo = FALSE}
library(knitr)
options(knitr.kable.NA = "-")
```

Besides using tidystats in combination with a text editor add-in to report 
statistics, you can also use tidystats to read and use the statistics for other
purposes. For example, researchers can extract specific statistics 
and perform analyses such as meta-analyses or a p-curve analysis on the 
extracted statistics.

One particular useful function that was created for this purpose is 
`tidy_stats_to_data_frame()`. This function converts a tidystats list of 
statistics to a standard data frame. That means you can use standard subsetting functions such as `subset()` on the
data to retrieve the statistics of interest.

## An example

Below is an example of how to convert a list of statistics to a data frame and 
perform several simple operations.

In the example below we read the tidystats list and select all the p-values.

```{r, results = "hide", message = FALSE}
library(tidystats)

# Read the .json file containing the statistics and immediately convert it to
# a data frame
stats_file <- system.file("extdata", "statistics.json", package = "tidystats")
if (!nzchar(stats_file)) stats_file <- "../inst/extdata/statistics.json"

statistics <- read_stats(stats_file) |>
  tidy_stats_to_data_frame()

# Extract all the p-values
p_values <- subset(statistics, statistic_name == "p")

p_values
```

```{r, echo = FALSE}
kable(p_values, format = "markdown")
```

Alternatively, we can can also easily select all significant p-values.

```{r}
sig_p_values <- subset(statistics, statistic_name == "p" & value < .05)
```

```{r example2_eval, echo = FALSE}
kable(sig_p_values, format = "markdown")
```

This could be useful if you want to conduct a 
[p-curve analysis](https://doi.org/10.1177/1745691614553988). 
Although do note that you should not blindly select all *p*-values. You should 
select only the *p*-values that are relevant to a particular hypothesis. If 
researchers provide the correct meta-information for each test 
(e.g., by indicating whether it is a primary analysis), this could help 
meta-researchers make correct decisions about which statistics to include in 
their analyses.

## Summary

By importing a tidystats-produced file of statistics, you can convert 
the statistics to a data frame using the `tidy_stats_to_data_frame` function and 
apply common data transformation functions to extract specific statistics. These
statistics can then be used in analyses such as meta-analyses, p-curve analyses,
or other analyses.

## References

Simonsohn, U., Nelson, L. D., & Simmons, J. P. (2014). p-curve and effect size: Correcting for publication bias using only significant results. *Perspectives on Psychological Science*, *9*(6), 666-681. https://doi.org/10.1177/1745691614553988
