---
title: "Specifying preregistration content"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Specifying preregistration content}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

The `preregr` package enables specifying (pre)registration content from within R. This information can then be exported to a human-readable HTML file with embedded machine-readable JSON, which can be imported again with `preregr`. This has three benefits:

- It decentralizes specification of (pre)registration forms, contributing to the democratization and inclusiveness aims of the open science movement;
- It enables harvesting (pre)registration information from arbitrary sources in a machine-readable format, making (pre)registrations more findable, accessible, interoperable, and reusable;
- It facilitates integrating (pre)registration specification in an R Markdown-based reproducible research workflow.

# Integrating preregistration in project planning

One of the advantages of integrating preregistration forms in R Markdown is that it becomes possible to produce R Markdown preregistration templates that include a number of parameters that then automatically conduct the sample size computations and insert those into the preregistration form specification.

Similarly, such templates can integrate R packages such as [ganttrify](https://medium.com/european-data-journalism-network/beautiful-gantt-charts-with-ggplot2-80ccd8c2c788) to facilitate straightforward but thorough planning of a project, documenting the results in a preregistration with little extra effort.

# An example

In this example, we will load the "inclusive systematic review registration form", a (pre)registraton form that was intended to be useable for all types of systematic reviews in all scientific fields. We will store the example in our R session, so we can add more item content later on.

```{r, preregr-example-1a}

preregExample <-
  preregr::prereg_initialize(
    "inclSysRev_v0_92"
  );

```

To see which items to complete next, we can use [`preregr::prereg_next_item()`](https://preregr.opens.science/reference/prereg_next_item.html).

```{r, preregr-example-1b}

preregr::prereg_next_item(
  preregExample,
  nrOfItems = 4
);

```

We can then follow this suggestion to specify content. For example:

```{r, preregr-example-1c}

preregExample <-
  preregExample |>
  preregr::prereg_specify(
    title = "Example Study",
    authors = "Littlebottom, C., Dibbler, C., & Aching, T."
  );

```

## Erroneous item identifiers

`preregr` checks whether users don't try to pass content for fields that weren't specified in the form that was initialized:

```{r, preregr-example-2}

preregExample <-
  preregExample |>
  preregr::prereg_specify(
    nonExistent_item = "This can't be stored anywhere"
  );

```

# Item Content Validation

In addition, `preregr` form specifications can contain item content validation information with custom error messages. By default, validation is performed and item content isn't stored unless the validation passes (although this can be overwritten):

```{r, preregr-example-3}

preregExample <-
  preregExample |>
  preregr::prereg_specify(
    start_date = "2021-9-01"
  );

```

If we do comply, `preregr` happily saves the specified content:

```{r, preregr-example-4}

preregExample <-
  preregExample |>
  preregr::prereg_specify(
    start_date = "2021-09-01"
  );

```

## Specifying validation expressions

Although the format for specifying (pre)registration forms for `preregr` was designed to be usable by users without R experience, more experienced users can integrate validation of item content by including bits of R code in the prergistration form.

# Viewing the preregistration

## Viewing specific content

(Pre)registrations forms are divided into sections, enabling viewing the specified content by section:

```{r, preregr-example-5}

preregExample |>
  preregr::prereg_show_item_content(
    section="metadata"
  );

```

## Viewing completion only

It is also possible to just view which fields have been completed:

```{r, preregr-example-6}

preregExample |>
  preregr::prereg_show_item_completion();

```

## R Markdown partials

The (pre)registration specification can also be knitted into an R Markdown document directly. The full preregistration item content will be stored machine-readably in JSON, and can be imported later on again with `preregr`.

```{r, preregr-example-7}

preregr::prereg_knit_item_content(
  preregExample,
  section="metadata"
);

```

# Justifying decisions

`preregr` integrates the `justifier` package, allowing immediate specification of the decision and its justification. These justifier specifications will also be stored machine-readably in the R Markdown document.

```{r, preregr-example-8}

preregExample <-
  preregExample |>
  preregr::prereg_justify(
    item = "start_date",
    decision = "We decided to start on the first, rather than the second, of September 2021.",
    justification = "It's a bit weird to start on the second day of a month."
  );

```