Movatterモバイル変換

Title:	Specify (Pre)Registrations and Export Them Human- AndMachine-Readably
Version:	0.2.9
Description:	Preregistrations, or more generally, registrations, enable explicit timestamped and (often but not necessarily publicly) frozen documentation of plans and expectations as well as decisions and justifications. In research, preregistrations are commonly used to clearly document plans and facilitate justifications of deviations from those plans, as well as decreasing the effects of publication bias by enabling identification of research that was conducted but not published. Like reporting guidelines, (pre)registration forms often have specific structures that facilitate systematic reporting of important items. The 'preregr' package facilitates specifying (pre)registrations in R and exporting them to a human-readable format (using R Markdown partials or exporting to an 'HTML' file) as well as human-readable embedded data (using 'JSON'), as well as importing such exported (pre)registration specifications from such embedded 'JSON'.
URL:	https://preregr.opens.science
BugReports:	https://gitlab.com/r-packages/preregr/-/issues
License:	GPL (≥ 3)
Encoding:	UTF-8
LazyData:	true
RoxygenNote:	7.2.3
Imports:	cli (≥ 3.0), jsonlite (≥ 1.7), rmdpartials (≥ 0.5.8), yaml(≥ 2.2)
Suggests:	googlesheets4 (≥ 1.0), haven (≥ 2.4.3), justifier (≥0.2.2), knitr (≥ 1.34), openxlsx (≥ 4.2), markdown, readxl(≥ 1.3), rvest (≥ 1.0), testthat (≥ 3.0), writexl (≥ 1.4),XLConnect (≥ 1.0), rmarkdown
Config/testthat/edition:	3
Depends:	R (≥ 4.1)
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2023-05-04 18:15:16 UTC; gjalt
Author:	Gjalt-Jorn Peters [aut, cre], Szilvia Zörgő [ctb], Olmo den Akker [ctb], Aleksandra Lazić [ctb], Thomas Gültzow [ctb]
Maintainer:	Gjalt-Jorn Peters <preregr@opens.science>
Repository:	CRAN
Date/Publication:	2023-05-05 07:30:02 UTC

preregr: Specify (Pre)Registrations and Export Them Human- And Machine-Readably

Description

Preregistrations, or more generally, registrations, enable explicit timestamped and (often but not necessarily publicly) frozen documentation of plans and expectations as well as decisions and justifications. In research, preregistrations are commonly used to clearly document plans and facilitate justifications of deviations from those plans, as well as decreasing the effects of publication bias by enabling identification of research that was conducted but not published. Like reporting guidelines, (pre)registration forms often have specific structures that facilitate systematic reporting of important items. The 'preregr' package facilitates specifying (pre)registrations in R and exporting them to a human-readable format (using R Markdown partials or exporting to an 'HTML' file) as well as human-readable embedded data (using 'JSON'), as well as importing such exported (pre)registration specifications from such embedded 'JSON'.

Author(s)

Maintainer: Gjalt-Jorn Peterspreregr@opens.science (ORCID)

Other contributors:

• Szilvia Zörgő (ORCID) [contributor]

• Olmo den Akker (ORCID) [contributor]

• Aleksandra Lazić (ORCID) [contributor]

• Thomas Gültzow (ORCID) [contributor]

See Also

Useful links:

• https://preregr.opens.science

• Report bugs athttps://gitlab.com/r-packages/preregr/-/issues

Convert a "bipiped" value (or vector of values) to a vector

Description

"Bipiped" means that different values are separated by a pair ofpipes (||), like the logical OR operator in R. Usebipiped_value_to_vector() for single values, andbipiped_values_to_vector() for a vector of values, in which case a listis returned.

Usage

bipiped_value_to_vector(x)bipiped_values_to_vector(x)

Arguments

Value

A vector or list of vectors.

Examples

exampleValue <-  paste0('"Purposefully select" || "Aselect" || ',         '"Likely self-selected" || "Ameliorated self-selection"');bipiped_value_to_vector(exampleValue);

Concatenate to screen without spaces

Description

The cat0 function is to cat what paste0 is to paste; itsimply makes concatenating many strings without a separator easier.

Usage

cat0(..., sep = "")

Arguments

Value

Nothing (invisibleNULL, likecat).

Examples

cat0("The first variable is '", names(mtcars)[1], "'.");

An example (pre)registration specification using the InclusiveGeneral-Purpose Registration Form

Description

This is a simple and relatively short partially completed (pre)registrationspecification.

Usage

examplePrereg_1

Format

An example of a (pre)registration specification

Select the first valid value

Description

From a vector or list of values, select the first valid value, valid beingdefined as a value that is not NULL or NA and has, after being trimmed ofwhitespace, a nonzero length. Optionally, only look at the element with agiven name.

Usage

first_valid_value(x, selectName = NULL)

Arguments

Value

The first valid value (or NULL).

OSF Prereg form

Description

Preregistration is the act of submitting a study plan, ideally alsowith analytical plan, to a registry prior to conducting the work.Preregistration increases the discoverability of research even if itdoes not get published further. Adding specific analysis plans canclarify the distinction between planned, confirmatory tests andunplanned, exploratory research.

Usage

form_OSFprereg_v1

Format

A (pre)registration form specification

Details

This preprint contains a template for the "OSF Prereg" form availablefrom the OSF Registry. An earlier version was originally developed forthe Preregistration Challenge, an education campaign designed toinitiate preregistration as a habit prior to data collection in basicresearch, funded by the Laura and John Arnold Foundation (now ArnoldVentures) and conducted by the Center for Open Science. More informationis available at https://www.cos.io/initiatives/prereg/, and other templatesare available at: https://osf.io/zab38/"

Source

doi:10.31222/osf.io/epgjd

Qualitative Preregistration Template

Description

The Qualitative Preregistration Template was created by researchers fromthe qualitative community for registration of primarily qualitative work.It is available as a registration option on the Open ScienceFramework (OSF).

Usage

form_OSFqual1_v1

Format

A (pre)registration specification

Details

This form was added topreregr by Aleksandra Lazic.

Add an instruction, section, or item to a (pre)registration form

Description

Add an instruction, section, or item to a (pre)registration form

Usage

form_add_instruction(x, heading, description, overwrite = TRUE)form_add_section(x, id, label, description, overwrite = TRUE)form_add_item(  x,  id,  label,  description,  section_id,  valueTemplate = "string",  validValues = NA,  validation = NA,  overwrite = TRUE)

Arguments

Value

The modified (pre)registration form

Examples

### Create an empty example formexampleForm <-  preregr::form_create(    title = "Example form",    version = "0.1.0"  ) |>  preregr::form_show();### Add some stuff;exampleForm <-  exampleForm |>  preregr::form_add_instruction(    heading = "First Real Instruction",    description = "Which normally also contains real instructions here"  ) |>  preregr::form_add_section(    id = "first_section",    label = "First Real Section",    description = "This section is very, very important."  ) |>  preregr::form_add_section(    id = "second_section",    label = "Second Real Section",    description = "This section is even more important then the first one."  ) |>  preregr::form_add_item(    id = "study_title",    label = "Study Title",    section_id = "first_section",    description = paste0(      "Think of a catching title, preferably with a colon in ",      "the middle. Bonus points for pop culture references."    )  ) |>  preregr::form_add_item(    id = "study_authors",    label = "Authors",    section_id = "first_section",    description = "Maybe list the authors, too."  ) |>  preregr::form_add_item(    id = "registration_type",    label = "Registration type",    section_id = "second_section",    description = paste0(      "Describe briefly why you are (pre)registering this ",      "study. For example, this might be a preregistration ",      "to allow others to know you're doing this study; or to ",      "make it clear you value transparency in science; or to ",      "remember your original plans later on. Or this might be ",      "a registration to update your plans after the data came ",      "in; or to document pragmatic changes in plans."    )  );### Show the result of our hard labourpreregr::form_show(exampleForm);

A mostly empty example form specification

Description

This form specification is mostly empty, so it can be auseful start if you want to create your own form. The accompanyingGoogle Sheet, which you can also copy, ishttps://docs.google.com/spreadsheets/d/14Qbak7JbBhTqmJaMgJ4tU9ZROaBbUfq37_UzkoHnM60

Usage

form_almostEmptyForm

Format

A (pre)registration specification

Create a new (pre)registration form

Description

You can use this function to create a new (pre)registration form.The "Creating a (pre)registration form" vignette explains how this works.That is available athttps://preregr.opens.science/articles/creating_prereg_form.htmlor can be shown by runningvignette("creating_prereg_form",package = "preregr").

Usage

form_create(  title,  version,  author = NA,  date = format(Sys.Date(), "%Y-%m-%d"),  ...)

Arguments

Value

Thepreregr form object prefilled with some examples.

Examples

exampleForm <-  preregr::form_create(    title = "Example form",    version = "0.1.0"  );### Show the form summaryexampleForm;

Import a (pre)registration form specification from a spreadsheet

Description

With this function, you can import a (pre) registration from aspreadsheet. See the "Creating a form from a spreadsheet" vignettefor more information. That is available athttps://preregr.opens.science/articles/creating_form_from_spreadsheet.htmlor can be shown by runningvignette("creating_form_from_spreadsheet",package = "preregr")

Usage

form_fromSpreadsheet(  x,  localBackup = NULL,  exportGoogleSheet = TRUE,  xlsxPkg = c("rw_xl", "openxlsx", "XLConnect"),  silent = preregr::opts$get("silent"))

Arguments

Details

An empty simpleexample spreadsheet is available athttps://docs.google.com/spreadsheets/d/14Qbak7JbBhTqmJaMgJ4tU9ZROaBbUfq37_UzkoHnM60and can be initialized as thealmostEmptyForm formwithprereg_initialize()

Value

The preregr form specification

Generalized Systematic Review Registration Form

Description

This paper presents a generalized registration form for systematic reviewsthat can be used when currently available forms are not adequate. The formis designed to be applicable across disciplines (i.e., psychology,economics, law, physics, or any other field) and across review types(i.e., scoping review, review of qualitative studies, meta-analysis, orany other type of review). That means that the reviewed records may includeresearch reports as well as archive documents, case law, books, poems, etc.Items were selected and formulated to optimize broad applicability insteadof specificity, forgoing some benefits afforded by a tighter focus. ThisPRISMA 2020 compliant form is a fallback for more specialized forms andcan be used if no specialized form or registration platform is available.When accessing this form on the Open Science Framework website, users willtherefore first be guided to specialized forms when they exist. In additionto this use case, the form can also serve as a starting point for creatingregistration forms that cater to specific fields or review types.

Usage

form_genSysRev_v1

Format

A (pre)registration form specification

Source

doi:10.31222/osf.io/3nbea

Inclusive General-Purpose Registration Form

Description

This Inclusive General-Purpose Registration Form is designed to be applicableacross disciplines (i.e., psychology, economics, law, physics, or any otherfield) and across study types (i.e., qualitative studies, quantitativestudies, experiments, systematic reviews, case studies, archive studies,comparative legal studies, or any other type of study). This form,therefore, is a fall-back for more specialized forms and can be used ifno specialized form or registration platform is available. If at allpossible, it is recommended to use a specialized form, since thisinclusive general-purpose registration form achieves that inclusivenessand general-purposeness at the cost of specificity and comprehensiveness.Still, if specialized forms don't fit for your study, this form may be agood backup.

Usage

form_generalPurpose_v1_1

Format

A (pre)registration form specification

Inclusivity & Diversity Add-on for preregistration forms

Description

This form is meant as a generic add-on that can be added to anypreregistration form to ensure that researchers are mindful aboutissues related to inclusivity and diversity. With inclusivity we mean"The fact or quality of being inclusive; (now) esp. the practice orpolicy of not excluding any person on the grounds of race, gender,religion, age, disability, etc.; inclusiveness."(Oxford University Press, n.d.-b).

Usage

form_inclDivAddon_v0_1

Format

A (pre)registration specification

Details

With diversity we refer to "The fact, condition, or practice ofincluding or involving people from a range of different social andethnic backgrounds, and (more recently) of different genders, sexualorientations, etc." (Oxford University Press, n.d.-a).

Oxford University Press. (n.d.-a). Diversity, n. In OED Online. OxfordUniversity Press. Retrieved November 29, 2022, fromhttps://www.oed.com/view/Entry/56064

Oxford University Press. (n.d.-b). Inclusivity, n. In OED Online. OxfordUniversity Press. Retrieved November 29, 2022,from https://www.oed.com/view/Entry/93584"

Inclusive Systematic Review Registration Form

Description

This Systematic Review Registration Form is intended as a general-purposeregistration form. The form is designed to be applicable to reviews acrossdisciplines (i.e., psychology, economics, law, physics, or any other field)and across review types (i.e., scoping review, review of qualitativestudies, meta-analysis, or any other type of review). That means that thereviewed records may include research reports as well as archive documents,case law, books, poems, etc. This form, therefore, is a fall-back for morespecialized forms and can be used if no specialized form or registrationplatform is available.

Usage

form_inclSysRev_v0_92

Format

A (pre)registration form specification

Source

doi:10.31222/osf.io/3nbea

Knit a (pre)registration form into an Rmd file

Description

This function inserts a (pre)registration form, or one or moresections, into an R Markdown file.

Usage

form_knit(x, section = NULL, headingLevel = 2)

Arguments

Value

x, invisibly

Examples

preregr::form_create(  title = "Example form",  version = "0.1.0") |>  preregr::form_knit();

Preregistration Template for Secondary Data Analysis

Description

Please cite the associated paper when using this preregistrationtemplate (see https://doi.org/10.15626/MP.2020.2625).

Usage

form_prereg2D_v1

Format

A (pre)registration specification

Preregistration Template for Qualitative and Quantitative Ethnographic Studies

Description

A preregistration is a way to design your research project before youbegin and to document your decisions, rationale. A template such asthis one can be employed to think about what you want to do and how,and subsequently, if you wish, you can submit the finished preregistrationto a registry, such as OSF's (https://osf.io/registries/). This templatewas developed to aid the preregistration of quantitative ethnographicstudies, but due to its modular nature, it can be employed for qualitativestudies as well.

Usage

form_preregQE_v0_95

Format

A (pre)registration form specification

Source

doi:10.23668/psycharchives.4584

Psychological Research Preregistration-Quantitative (aka PRP-QUANT) Template

Description

As an international effort toward increasing psychology’s commitment tocreating a stronger culture and practice of preregistration, amulti-society Preregistration Task Force* was formed, following the2018 meeting of the German Psychological Society in Frankfurt, Germany.The Task Force created a detailed preregistration template that benefitedfrom the APA JARS Quantitative Research guidelines, as well as acomprehensive review of many other preregistration templates.

Usage

form_prpQuant_v1

Format

A (pre)registration form specification

Source

doi:10.23668/psycharchives.4584

Show a (pre)registration form

Description

This function shows (parts of) a (pre)registration form.

Usage

form_show(x, section = NULL)

Arguments

Value

x, invisibly

Examples

### An empty formpreregr::form_create(  "Example form",  version = "1") |>  preregr::form_show();### A complete formpreregr::prereg_initialize("inclSysRev_v0_92") |>  preregr::form_show();

Convert a (pre)registration form to html

Description

Convert a (pre)registration form to html

Usage

form_to_html(  x,  file = NULL,  section = NULL,  headingLevel = 1,  silent = preregr::opts$get("silent"))

Arguments

Value

x, invisibly

Examples

### Load an example (pre)registration specificationdata("examplePrereg_1", package = "preregr");### Extract the form and show it as HTMLpreregr::form_to_html(  examplePrereg_1);

Convert a (pre)registration specification to YAML or JSON

Description

Convert a (pre)registration specification to YAML or JSON

Usage

form_to_json(x, file = NULL)prereg_spec_to_json(x, includeFormSpec = TRUE, file = NULL)## S3 method for class 'preregr_json'print(x, ...)prereg_spec_to_yaml(x, includeFormSpec = TRUE, file = NULL)## S3 method for class 'preregr_yaml'print(x, ...)

Arguments

Value

If a file is specified to write, to,x will be returned invisiblyto allow building a pipe chain; iffile=NULL, the resulting YAML/JSONwill be returned as a character vector.

Examples

### Load an example (pre)registration specificationdata("examplePrereg_1", package = "preregr");### Export to YAMLpreregr::prereg_spec_to_json(  examplePrereg_1);### Load an example (pre)registration specificationdata("examplePrereg_1", package = "preregr");### Export to YAMLpreregr::prereg_spec_to_yaml(  examplePrereg_1);

Convert a (pre)registration form to an R Markdown template

Description

This function creates an R Markdown template from a preregr(pre)registrations form specification. Pass it the URL to a GoogleSheet holding the (pre)registration form specification (in preregrformat), see the"Creating a form from a spreadsheet"vignette), the path to a file with a spreadsheet holding such aspecification, or a loaded or imported preregr (pre)registration form.

Usage

form_to_rmd_template(  x,  file = NULL,  title = NULL,  author = NULL,  date = "`r format(Sys.time(), '%Y-%m-%d at %H:%M:%S %Z (UTC%z)')`",  output = "html_document",  yaml = list(title = title, author = author, date = date, output = output),  includeYAML = TRUE,  chunkOpts = "echo=FALSE, results='hide'",  justify = FALSE,  headingLevel = 2,  showSpecification = FALSE,  preventOverwriting = preregr::opts$get("preventOverwriting"),  silent = preregr::opts$get("silent"))## S3 method for class 'preregr_rmd_template'print(x, ...)

Arguments

Value

x, invisibly

Examples

preregr::form_create(  title = "Example form",  version = "0.1.0") |>  preregr::form_to_rmd_template();

Export a (pre)registration form to an Excel spreadsheet

Description

Export a (pre)registration form to an Excel spreadsheet

Usage

form_to_xlsx(x, file)

Arguments

Value

x, invisibly

Included (pre)registration forms

Description

Show an overview of all included (pre)registration forms.

Usage

forms()

Value

Invisibly, a list of form identifiers of the available forms.

Examples

forms();

Print a heading

Description

This is just a convenience function to print a markdown or HTML heading ata given 'depth'.

Usage

heading(  ...,  headingLevel = preregr::opts$get("defaultHeadingLevel"),  output = "markdown",  cat = TRUE)

Arguments

Value

The heading, invisibly.

Examples

heading("Hello ", "World", headingLevel=5);### This produces: "\n\n##### Hello World\n\n"

Import a (pre)registration specification from JSON embedded in HTML

Description

Import a (pre)registration specification from JSON embedded in HTML

Usage

import_from_html(x, select = 1)

Arguments

Value

The (pre)registration specification.

Examples

### Note that this example writes to a local file!### Temporary file to save totmpFile <- tempfile(fileext = ".html");### Load an example (pre)registration specificationdata("examplePrereg_1", package = "preregr");### Save it to an HTML filepreregr::prereg_spec_to_html(  examplePrereg_1,  file = tmpFile);### Import the example againimportedPreregr <-  preregr::import_from_html(    tmpFile  );### Show the resultpreregr::prereg_show_item_completion(  importedPreregr,  section="metadata");

Convert a number to a date using Excel's system

Description

Convert a number to a date using Excel's system

Usage

number_as_xl_date(x)

Arguments

Value

The date(s)

Examples

preregr::number_as_xl_date(44113);

Options for the preregr package

Description

Thepreregr::opts object contains three functions to set, get, and resetoptions used by the preregr package. Usepreregr::opts$set to set options,preregr::opts$get to get options, orpreregr::opts$reset to reset specific orall options to their default values.

Usage

opts

Format

An object of classlist of length 4.

Details

It is normally not necessary to get or setpreregr options.

The following arguments can be passed:

...

Forpreregr::opts$set, the dots can be used to specify the optionsto set, in the formatoption = value, for example,utteranceMarker = "\n". Forpreregr::opts$reset, a list of options to be reset can be passed.

option

Forpreregr::opts$set, the name of the option to set.

default

Forpreregr::opts$get, the default value to return if theoption has not been manually specified.

The following options can be set:

quridPrefix

The prefix for quasi-unique record identifiers (QURIDs).

Two

Second item

Examples

### Get the default "silence versus chattiness" settingpreregr::opts$get(silent);### Set it to show all messagespreregr::opts$set(silent = FALSE);### Check that it workedpreregr::opts$get(silent);### Reset this option to its default valuepreregr::opts$reset(silent);### Check that the reset worked, toopreregr::opts$get(silent);

Initialize a (pre)registration

Description

To initialize a (pre)registration, pass the URL to a Google Sheet holdingthe (pre)registration form specification (in preregr format), see the"Creating a form from a spreadsheet"vignette), the path to a file with a spreadsheet holding such aspecification, or a loaded or imported preregr (pre)registration form.

Usage

prereg_initialize(x, initialText = "Unspecified")

Arguments

Details

For an introduction to working with preregr (pre)registrations,see the"Specifying preregistration content"vignette.

Value

The empty (pre)registration specification.

Examples

preregr::prereg_initialize(  "inclSysRev_v0_92");

Justify (and optionally specify) the content for one or more (pre)registration items

Description

Justify (and optionally specify) the content for one or more (pre)registration items

Usage

prereg_justify(  x,  item,  decision = NULL,  justification = NULL,  assertion = NULL,  source = NULL,  content = NULL,  append = TRUE,  validate = TRUE,  requireValidContent = TRUE,  silent = preregr::opts$get("silent"))

Arguments

Value

x, invisibly

Examples

### Start with an empty form, then specify and justify### content for an item.preregExampl <-  preregr::prereg_initialize(    "inclSysRev_v0_92"  ) |>    preregr::prereg_justify(      item = "title",      content = "Example title",      decision = "We decide to call this study 'Example title'.",      justification = "It seems a fitting title for an example."    ) |>    preregr::prereg_show_item_completion(      section="metadata"    );

Knit the specified content for the items in a (pre)registration into an Rmd file

Description

This function inserts the specified content for the items in a(pre)registration, or in one or more sections, into an R Markdown file.

Usage

prereg_knit_item_content(x, section = NULL, headingLevel = 2)

Arguments

Value

x, invisibly

Examples

### Load an example (pre)registration specificationdata("examplePrereg_1", package = "preregr");### Knit the contents of the "metadata" section### as an R Markdown partialexamplePrereg_1 |>  preregr::prereg_knit_item_content(    section="metadata"  );

Show the next item to specify content for

Description

This function shows the next item (or items) in a (pre)registrationfor which to specify content (searching through all sections or througha selection of sections).

Usage

prereg_next_item(x, nrOfItems = 1, section = NULL)

Arguments

Value

x, invisibly

Examples

### Load an example (pre)registration specificationdata("examplePrereg_1", package = "preregr");### Check next itemexamplePrereg_1 |>  preregr::prereg_next_item();### Specify content for this itemexamplePrereg_1 <-  preregr::prereg_specify(    examplePrereg_1,    funding = paste0(      "No funding. There's never any ",      "funding for this kind of stuff."    )  );### Get the next three itemspreregr::prereg_next_item(  examplePrereg_1,  nrOfItems = 3);

Show which items in a (pre)registration have been completed

Description

This function shows which items in a (pre)registration, or in one or moresections, have been completed - or, more accurately, contain at least somecontent that is different from the default content.

Usage

prereg_show_item_completion(x, section = NULL)

Arguments

Value

x, invisibly

Examples

### Load an example (pre)registration specificationdata("examplePrereg_1", package = "preregr");### Show which items were completedexamplePrereg_1 |>  preregr::prereg_show_item_completion(    section="metadata"  );

Show the specified content for the items in a (pre)registration

Description

This function shows the specified content for the items in a(pre)registration, or in one or more sections.

Usage

prereg_show_item_content(x, section = NULL)

Arguments

Value

x, invisibly

Examples

### Load an example (pre)registration specificationdata("examplePrereg_1", package = "preregr");### Show the item content for the "metadata" sectionexamplePrereg_1 |>  preregr::prereg_show_item_content(    section="metadata"  );

Convert a (pre)registration specification to html

Description

Use this function to export your (pre)registration specification to anHTML file. To instead embed it in an R Markdown file, useprereg_knit_item_content().

Usage

prereg_spec_to_html(  x,  file = NULL,  section = NULL,  headingLevel = 1,  silent = preregr::opts$get("silent"))

Arguments

Value

The produced HTML, which will print in the viewer in RStudio.

Examples

### Load an example (pre)registration specificationdata("examplePrereg_1", package = "preregr");### Convert it to HTML and show the resultpreregr::prereg_spec_to_html(  examplePrereg_1);

Convert a (pre)registration specification to PDF

Description

Use this function to export your (pre)registration specification to a PDFfile. To embed it in an R Markdown file, useprereg_knit_item_content() instead.

Usage

prereg_spec_to_pdf(  x,  file,  author = NULL,  section = NULL,  headingLevel = 1,  silent = preregr::opts$get("silent"))

Arguments

Value

x, invisibly

Examples

### Use a temporary file to write totmpFile <- tempfile(fileext = ".pdf");### Load an example (pre)registration specificationdata("examplePrereg_1", package = "preregr");### Only run this if you have a functional LaTeX installationif (FALSE) {  preregr::prereg_spec_to_pdf(    examplePrereg_1,    file = tmpFile  );}

Specify the content for one or more (pre)registration items

Description

Specify the content for one or more (pre)registration items

Usage

prereg_specify(  x,  ...,  append = TRUE,  validate = TRUE,  requireValidContent = TRUE,  silent = preregr::opts$get("silent"))

Arguments

Value

x, invisibly

Examples

### Load an example (pre)registration specificationdata("examplePrereg_1", package = "preregr");### Specify some fields and show the resultsexamplePrereg_1 |>  preregr::prereg_specify(    tasks_and_roles = "All authors contributed equally",    nonExistent_item = "This can't be stored anywhere",    start_date = "2021-9-01"  ) |>  preregr::prereg_show_item_completion(    section="metadata"  );

Generate a random slug

Description

idSlug is a convenience function with swapped argument order.

Usage

randomSlug(x = 10, id = NULL, chars = c(letters, LETTERS, 0:9))idSlug(id = NULL, x = 10, chars = c(letters, LETTERS, 0:9))

Arguments

Value

A character value.

Examples

randomSlug();idSlug("identifier");

Bind lots of dataframes together rowwise

Description

Bind lots of dataframes together rowwise

Usage

rbind_df_list(x)

Arguments

Value

A dataframe

Examples

rbind_df_list(list(Orange, mtcars, ChickWeight));

Simple alternative for rbind.fill or bind_rows

Description

Simple alternative for rbind.fill or bind_rows

Usage

rbind_dfs(x, y, clearRowNames = TRUE)

Arguments

Value

The merged dataframe

Examples

rbind_dfs(Orange, mtcars);

Convenience function to read spreadsheet-like files

Description

Currently reads spreadsheets from Google Sheets or fromxlsx,csv,orsav files. Normally, you don't use this, but instead youuseform_fromSpreadsheet().

Usage

read_spreadsheet(  x,  sheet = NULL,  columnDictionary = NULL,  localBackup = NULL,  exportGoogleSheet = FALSE,  flattenSingleDf = FALSE,  xlsxPkg = c("rw_xl", "openxlsx", "XLConnect"),  failQuietly = FALSE,  silent = preregr::opts$get("silent"))

Arguments

Value

A list of dataframes, or, if only one data frame was loaded andflattenSingleDf isTRUE, a data frame.

Examples

### Note that this example requires an internet connection!read_spreadsheet(  paste0(    "https://docs.google.com/",    "spreadsheets/d/",    "1bHDzpCu4CwEa5_3_q_9vH2691XPhCS3e4Aj_HLhw_U8"  ));

Repeat a string a number of times

Description

Repeat a string a number of times

Usage

repeatStr(n = 1, str = " ")

Arguments

Value

A character vector of length 1.

Examples

### 10 spaces:repStr(10);### Three euro symbols:repStr("\u20ac", 3);

"Serialize" a data frame or (pre)registration specification

Description

When exporting a (pre)registration specification to YAML or JSON, the mosthuman-readable format differs from the way data frames are comprised oflists. Data frames are lists that are bound together as columns; and so,when saving a data frame to YAML or JSON, the data in each column iscombined (e.g. first all item identifiers, then all item labels, then allitem descriptions, etc). However, for humans, it makes more sense tohave all data belonging to the same item close together. These functionsdo that processing.

Usage

serialize_df(x, idCol = NULL)structure_for_serialization(x)

Arguments

Value

The restructured list

In an object imported from YAML or JSON, convert some elements to dataframes

Description

In an object imported from YAML or JSON, convert some elements to dataframes

Usage

serialized_data_to_dfs(x)

Arguments

Value

The restructured object

Programmatically constructing justifier elements

Description

These functions can be used to programmatically construct decision,justifications, assertions, and sources using thejustifier package.

Usage

source(label, description = NULL, type = NULL, id = NULL, xdoi = NULL, ...)assert(label, description = "", type = NULL, id = NULL, source = NULL, ...)justify(label, description = "", type = NULL, id = NULL, assertion = NULL, ...)decide(  label,  description = NULL,  type = NULL,  id = NULL,  alternatives = NULL,  justification = NULL,  ...)

Arguments

Value

The generated object.

Examples

### Programmatically create a partial justification objectexampleAssertion <-  preregr::assert(    "This is an assertion",    source = c(      preregr::source('This is a first source'),      preregr::source('This is a second source')));### Programmatically create a justification with two assertions### but without sourcesexampleJustification <-  preregr::justify(    "Icecream will make me feel less fit",    assertion = c(      preregr::assert('Icecream is rich in energy'),      preregr::assert('Consuming high-energy foods makes me feel less fit')    ),    weight = -.5  );### Show itexampleJustification;### Programmatically create a simple decisionsimpleDecision <-  preregr::decide(    "decision",    justification = preregr::jstf(      "justification",      assertion = exampleAssertion    )  );### Programmatically create a justification object for a full decisionfullJustifierObject <-  preregr::decide(    "I decide to go get an icecream",    justification = c(      preregr::justify(        "Having an icecream now would make me happy",        assertion = c(          preregr::assert(            "Decreasing hunger increases happiness",            source = preregr::source(              "My past experiences"            )          ),          preregr::assert(            "I feel hungry",            source = preregr::source(              "Bodily sensations"            )          )        ),        weight = 1      ),      exampleJustification,      preregr::justify(        "I can afford to buy an icecream.",        assertion = c(          preregr::assert(            "My bank account balance is over 300 euro.",            source = preregr::source(              "My bank app"            )          ),          preregr::assert(            "I need to keep at least 100 euro in my bank account.",            source = preregr::source(              "Parental advice"            )          )        ),        weight = .3      )    )  );### Show the full objectfullJustifierObject;### Combine both into a list of decisionstwoDecisions <-  c(simpleDecision,    fullJustifierObject);### Show the combinationtwoDecisions;

Validate a value

Description

This function validates a value. Before validation, it checksthe validation expression and optionally performs replacements, where thereplacement strings (delimited by the validation replacement delimiters,by default,⁠{{⁠ and⁠}}⁠) arereplaced by the first valid corresponding value from thereplacementSources (working through those sources consecutively, i.e.only looking in the second one of the first one doesn't contain a validvalue for the relevant replacement string, valid being defined as a valuethat is not NULL or NA and has, after being trimmed of whitespace, anonzero length).

Usage

validate_value(  VALUE,  validations,  replacementSources,  errorMessages,  convert_bipiped = TRUE)

Arguments

Details

To change the validation replacement delimiters, usepreregr::opts$set(validation_replacementDelimiters = c("{{", "}}"));.

Value

The message resulting from the validation (i.e. an error or "").

Examples

### Set some validation variablesvalidationStatement <-  paste(    "is.na(VALUE) ||",    "(VALUE %in% {{validValues}}) ||",    "(VALUE %in% {{testField}})"  );replacementSources <-  list(    list(validValues = '"testValue" || "anotherValue"'),    list(testField = "Yet another testvalue")  );errorMessages <-  "No valid test value passed!";### Run a passing validationpreregr::validate_value(  "testValue",  validations = validationStatement,  replacementSources = replacementSources,  errorMessages = errorMessages);### Run a failing validationpreregr::validate_value(  "A testvalue that won't pass",  validations = validationStatement,  replacementSources = replacementSources,  errorMessages = errorMessages);

Easily parse a vector into a character value

Description

Easily parse a vector into a character value

Usage

vecTxt(  vector,  delimiter = ", ",  useQuote = "",  firstDelimiter = NULL,  lastDelimiter = " & ",  firstElements = 0,  lastElements = 1,  lastHasPrecedence = TRUE,  colFun = NULL)vecTxtQ(vector, useQuote = "'", ...)

Arguments

Value

A character vector of length 1.

Examples

vecTxtQ(names(mtcars));

Wrap all elements in a vector

Description

Wrap all elements in a vector

Usage

wrapVector(x, width = 0.9 * getOption("width"), sep = "\n", ...)

Arguments

Value

A character vector

Examples

res <- wrapVector(  c(    "This is a sentence ready for wrapping",    "So is this one, although it's a bit longer"  ),  width = 10);print(res);cat(res, sep="\n");

Convert a (pre)registration specification from YAML or JSON

Description

Convert a (pre)registration specification from YAML or JSON

Usage

yaml_to_prereg_spec(x)

Arguments

Value

The imported object.

Examples

### Get path to example fileexamplePreregFile <-  system.file(    "extdata",    "preregr-spec-example1.yml",    package = "preregr"  );### Load it and show which items are completedpreregr::yaml_to_prereg_spec(  examplePreregFile) |>  preregr::prereg_show_item_completion();