https://github.com/dalejbarr/explan

Planning psychology experiments

https://github.com/dalejbarr/explan

Repository

Planning psychology experiments

README.Rmd

---
output: github_document
---



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

# explan




The goal of `{explan}` is to help researchers design psychology experiments. Currently this package provides an implementation of Permuted Subblock Randomization (PSR), a restricted randomization approach that improves power for within-participant study designs. See [Liang & Barr (2024)](https://osf.io/preprints/psyarxiv/4ums9) for details.

```
@article{liangBetterPowerDesign2024,
  title = {Better Power by Design: {{Permuted-subblock}} Randomization Boosts Power in Repeated-Measures Experiments},
  author = {Liang, Jinghui and Barr, Dale J.},
  url={osf.io/preprints/psyarxiv/4ums9},
  year = {2024},
  journal = {Psychological methods},
  doi = {10.1037/met0000717}
}
```

The long-term goal is to provide a larger set of functions to help with counterbalancing, Latin Square designs, etc.

## Installation

You can install the development version of explan from [GitHub](https://github.com/) with:

``` r
## install.packages("remotes")
remotes::install_github("dalejbarr/explan", dependencies = TRUE,
                        build_vignettes = TRUE)
```

## Implementing Permuted Subblock Randomization

### One-factor designs

The package includes two main functions for implementing PSR, a vector version (`psr()`) and a data frame version (`psr_stimuli()`).

The vector version, `psr()` creates a vector of condition levels conforming to PSR given a set of levels corresponding to experimental conditions, desired number of subblocks, and number of repetitions per condition.

```{r example}
library(explan)

psr(c("condition-A", "condition-B", "condition-C"),
    n_subblocks = 6, n_reps = 6)
```

To find out the number of possible subblocks for a given number of repetition, use `possible_subblocks()`:

```{r poss-subblocks}
possible_subblocks(6)
```

The data frame version, `psr_stimuli()`, is a function that makes it possible to apply PSR to a table of stimuli. As an example, the built-in table `stroop_stimuli` contains example stimuli for a Stroop experiment, which has a two-level within participant factor of congruency.

```{r stroop-stimuli}
stroop_stimuli
```

You can determine the number of replications using `dplyr::count()`:

```{r congruency-count}
stroop_stimuli |>
  dplyr::count(congruency)
```

```{r poss-subblocks-stroop}
possible_subblocks(24)
```

To randomize these stimuli for a study with four participants, you would use the following code:

```{r randomize-stroop}
stroop_four <- psr_stimuli(stroop_stimuli, "congruency",
                           n_subblocks = 12, n_part = 4)

stroop_four |>
  head(10)
```

### Two-by-two (2x2) factorial designs

Our PSR algorithms can also be used in 2x2 factorial designs with two within-participant factors, each factor has two levels. Before conducting randomization, you would like to construct a 2x2 condition table with `con_2x2()` to see how factors are combined.

```{r fac-blocks}
con_2x2(facR = c("A", "a"), facC = c("B", "b"))
```

According to the resulting 2x2 matrix, conditions were generated by combining two factors in our design. Notice the numbers followed by, they determined the relative positions of conditions in the original sequence. That is, conditions are arranged as "A/B (1), A/b (2), a/B (3), a/b (4)".

Instead of choosing the number of subblocks, you can choose three versions of PSR to randomize your stimuli. All versions are based on the largest number of possible subblocks in order to match the context of 2x2 factorial designs. The first one is called "PSR-max". It simply randomizes all conditions under the largest number of subblocks. This is identical to the one-factor design situations. The second one is called "PSR-C" which clockwisly "moving" conditions in the 2x2 matrix. You can use our `walk_2x2()` to have an intuitive example.

```{r walk-c}
walk_2x2(np = 4, nr = 3, facR = c("A", "a"), facC = c("B", "b"), method = "c")
```

The list that `walk_2x2()` created contains four vectors within each one representing the condition sequences for each participant. With PSR-C, each sequence has a clockwise motion corresponding to the `con_2x2()` matrix (i.e., 1-2-4-3-1-...). The first condition (starting point) has been counterbalanced across participants.

The third version of PSR is called "PSR-E". This algorithm moves conditions in "nearby-diagonal" pattern (i.e., 1-3-2-4-1-...). The letter "E" represents such pattern since the motion is similar to horizontally drawing the number "8" in the 2x2 condition table. We avoid using the term "PSR-8" to avoid confusion when PSR-8 represents PSR with 8 subblocks.

```{r walk-e}
walk_2x2(np = 4, nr = 3, facR = c("A", "a"), facC = c("B", "b"), method = "e")
```

Finally, `walk_2x2()` also has a data frame version, `psr_2x2_stimuli()` to apply PSR to a table of stimuli in 2x2 factorial designs. The built-in table, `stroop_stimuli_factorial`, is an extension of the one-factor version `stroop_stimuli`, and additionally contains one more two-level within-participant factor of responding positions (standing versus sitting).

```{r fac-example}
stroop_stimuli_factorial
```

To randomize these stimuli for a study with four participants, you would use the following code:
```{r randomize-stroop-four}
stroop_fac_four <- psr_2x2_stimuli(
	stim_table = stroop_stimuli_factorial,
	IVs= c("congruency", "positions"),
	algorithm = "circular",
	n_part = 4L)
	
stroop_fac_four |> 
	head(10)
```



## Further information

Please see the included vignette entitled "randomization". Make sure you have installed the package from github using `build_vignettes = TRUE` (see above) and then use the following command to see the vignette.

``` r
browseVignettes(package = "explan")
```

Owner

GitHub Events