Intro to preregr"
In preregr: Specify (Pre)Registrations and Export Them Human- And Machine-Readably

Welcome to this introductory preregr vignette. This vignette will first describe the preregistration landscape, cover why preregr was developed, and then briefly introduce its functions, signposting to dedicated vignettes.

The preregistration landscape

Preregistration forms are typically tied to the organizations offering the registration as a service (e.g. trial registries). The website implementing that registration service and the form used by that organization are therefore often intertwined.

For example, PROSPERO (the International Prospective Register of Systematic Reviews), a preregistration service for systematic reviews with health-related outcomes, uses a form that is often referred to as PROSPERO, too. Similarly, https://clinicaltrials.gov has its own specific form, as does https://aspredicted.org. The Open Science Framework (https://osf.io/registries) offers multiple forms, centrally administered by the Center for Open Science.

To register a preregistration, researchers typically visit such a service, create an account, and create a new preregistration form. They then complete the form and submit it. These forms are then (if/once published) served at the corresponding organization's website.

Why `preregr`?

The preregr package was created to facilitate a number of things that are not yet possible with the current infrastructure. First, the control of this infrastructure by a relatively small number of organizations is hard to reconcile with the Open Science imperative to build open, community-owned infrastructure. Second, the public-facing completed registration forms are not stored in a machine-readable format (and although they can often be scraped, this is not a robust procedure). Third, submitting these preregistration forms requires separate, manual actions by researchers, which means both extra work and opportunity for errors to be introduced.

To address these, preregr aims to support the following:

Democratize science, facilitate inclusivity & diversity.
Make (pre)registrations machine-readable.
Connect (pre)registrations with R Markdown-based workflow.

Democratize science, facilitate inclusivity & diversity

Everybody can specify new (pre)registration forms that fit with a specific approach, method, epistemological perspective, et cetera. You create a form using Google Sheets or Excel, and then pass the Google Sheets URL (or file path) to preregr to initialize this form. To jump in, check the vignettes Creating a form from a spreadsheet, Creating a (pre)registration form, Specifying preregistration content, or Create an R Markdown template from a form.

To explain this point a bit more, consider the following. Currently, (pre)registration services offer a selection of forms that are based on certain ontological and epistemological assumptions, and are geared towards specific methods & conventions.

On the one hand, this helps with being precise: some things make sense for psychology, others for chemistry or law; different things make sense for quantitative and qualitative approaches; etc. It also affords standardization, e.g. by societies or journals.

On the other hand, these forms 'miss' many use cases. They run the risk of implicitly discouraging designs that don't easily fit, exluding researchers falling outside those constraints. To benefit from epistemic diversity (pre)reg form development has to be decentralized.

In other words, in addition to forms that are produced by consensus efforts or curated by institutions, it is important there are as few thresholds as possible for researchers to create new (and improve on existing) (pre)registration forms.

Make (pre)registrations machine-readable

Once you're done with completing a form, you can write your (pre)registration form to an HTML file that also (invisibly) contains a machine-readable version of the content you specified as well as the original form specification.

The content specified in the (pre)registration form (or just the form specification) can be imported directly from a URL (see the Importing a (pre)registration from embedded JSON from a URL and Importing a (pre)registration form from embedded JSON from a URL vignettes).

This makes re-using forms very easy. It also facilitates meta-science: you can harvest (pre)registration specifications that are already organized, and that include the original form with the instructions (and validation directives).

The move towards machine-readable specification of reports, but also (pre)registrations, is a logical next step now that preregistrations exist. Human extraction and coding of information is inaccurate and resource-intensive.

Connect (pre)registrations with R Markdown-based workflow

To facilitate integration with R Markdown, you can write forms to R Markdown templates that include the instructions. Just specify all items at your leisure (or skip those that aren't applicable).

This R Markdown template can then be inserted into another Rmd file as a child document and/or you can export it to a PDF. This PDF can be uploaded as an attachment to a (pre)registration server (e.g. the @OSFramework, using e.g. the open-ended registration form).

This allows you to, for example, create augmented R Markdown templates for your lab that implement sample size computations and automatically insert them into the form.

It also allows you to work on (pre)registrations forms using the power of Git for version control, making collaboration on (pre)registrations with large groups easier to manage (though admittedly, this may not be for everybody).