In addition to being able to specify (pre)registration
forms from within R or importing
it from the URL of an existing form, you can also specify the form
using a spreadsheet. You can use an Excel file (
.xlsx) or a
Google Sheet. An empty spreadsheet is available
The spreadsheet should have the following worksheet names (in whichever order):
metadata: metdata about the (pre)registration form
instructions: instructions for the (pre)registration form
sections: the sections in which the (pre)registration form items are organized
items: the items in the (pre)registration form
valueTemplates: the value templates specifying valid values
metadata worksheet contains two columns (in
content. Every row
holds a different bit of metadata. The field name is specified in the
field column and the metadata itself is specified in the
content column in the corresponding row. Always specify
content for at least the following fields: specify the form’s title as
title; specify the form’s author(s) as
specify the date as
date, and specify the version as
Regarding versioning, if there is only one version and the creators do not plan to release future version, the recommendation is to set the version to 1.
If the creators have no clear idea about how to version the form (i.e. there may be improvements in the future), the recommendation is to set the first version to 0.0.1, and roughly adopt the system common for software: increment the first number when the form is substantially updated (e.g. such that preregistrations that used the previous version of the form may no longer be valid given the new version, for example becaue sections were added or removed, or value templates changed, etc), the third number for very small changes (e.g. typos, spelling corrections, clarification or extra explanations, bug fixes in regular expressions in value templates, etc), and the second number for changes in between (e.g. changing the order of items or moving an item to another section, or changing value templates to be more permissive (and so, retaining compatibility with (pre)registrations that used the previous version of the form)). In that case, use version 1.0.0 to signal that the form has reached maturity.
instructions worksheet contains two columns (in
Every row holds one specific set of instructions in the
description columns that will be included under the heading
These instructions can be used for general instructions about the form, such as the intended use cases or references to background materials.
The sections can be used to organize the items in the form. The
sections worksheet has three columns (in whichever order):
Every section has a unique section identifier that is specified in
section_id. Identifiers can only contain Latin lower- and
uppercase letters, Arabic digits, and underscores; and have to start
with a letter. These section identifiers are what are specified in the
items worksheet to assign an item to a section.
Sections have brief titles that are specified in
section_label, and can have longer descriptions
(e.g. instructions, background information etc) in
items worksheet contain the following columns
(again, in whichever order):
The section identifier in
section_id specifies to which
section an item belongs. The
item_id is the unique item
identifier that users use when specifying (pre)registration content
using [preregr::prereg_specify()]. The
a brief item name, and the
item_description a longer
description, for example an instruction.
item_valueTemplate column is used to specify the
value template to use for this item. This determines the valid input
item_validValues column is used to specify the
valid values, in case only a few values can be specified for this item;
item_validation column can be used to override the
validation information in the
Value templates are used to specify valid user input for form fields. For example, often any text input may be allowed. Sometimes, the text input will have to be a number. And other times, it will be necessary to force users to select one value out of multiple.
valueTemplates worksheet has columns
error (in whichever order).
identifier specifies the unique identifier for the
value template as used in the
items worksheet to specify
which value template applies. The
which content is valid for that value template.
validValues column can be used to specify a finite
list of valid values. These values are then used in the
examples column, the
validation column, and
default column is not used in
it is retained in the standard for compatibility with the
package, that also uses value templates.
As yet, the
examples column isn’t used yet, either,
although that will likely change in future versions (in which case
examples will be shown when the item’s description is shown).
error column specify the
validation rules (as R script) and the error to show when validation
The spreadsheet specifications for the (pre)registration forms that
are included with
preregr are publicly available at the
In addition, there’s an empty form available here.
To import a form specification in a spreadsheet, use preregr::form_fromSpreadsheet(). For example:
<- form_imported_from_a_spreadsheet ::form_fromSpreadsheet( preregrpaste0( "https://docs.google.com/spreadsheets/d/", "1bHDzpCu4CwEa5_3_q_9vH2691XPhCS3e4Aj_HLhw_U8" ) ); |> form_imported_from_a_spreadsheet ::form_show( preregrsection = "extraction" );
It’s also possible to directly initialize a new preregistration from a spreadsheet specification:
<- form_initialized_from_a_spreadsheet ::prereg_initialize( preregrpaste0( "https://docs.google.com/spreadsheets/d/", "1bHDzpCu4CwEa5_3_q_9vH2691XPhCS3e4Aj_HLhw_U8" ) ); |> form_initialized_from_a_spreadsheet ::prereg_show_item_completion( preregrsection = "extraction" );