R/form_to_json.R, R/prereg_spec_to_json.R, R/prereg_spec_to_yaml.R
export_to_yaml_or_json.RdConvert a (pre)registration specification to YAML or JSON
The (pre)registration object (as produced by a call to
prereg_initialize()), or, for the print method, the produced
YAML or JSON.
Optionally, a file to save the YAML or JSON to.
Whether to include the (pre)registration form specification. Note that this includes metadata about the form fields such as their labels and descriptions - without the form specification, only the item identifiers are stored.
Any additional arguments are ignored.
If a file is specified to write, to, x will be returned invisibly
to allow building a pipe chain; if file=NULL, the resulting YAML/JSON
will be returned as a character vector.
### Load an example (pre)registration specification
data("examplePrereg_1", package = "preregr");
### Export to YAML
preregr::prereg_spec_to_json(
examplePrereg_1
);
#> {
#> "specs": {
#> "discipline": {
#> "text": ["Thaumatology"]
#> },
#> "title": {
#> "text": ["Cabbages cast in moderation: a comparative analysis"]
#> },
#> "authors": {
#> "text": ["Littlebottom, C., Dibbler, C., & Aching, T."]
#> },
#> "tasks_and_roles": {
#> "text": ["Unspecified"]
#> },
#> "funding": {
#> "text": ["Unspecified"]
#> },
#> "cois": {
#> "text": ["Unspecified"]
#> },
#> "type_of_study": {
#> "text": ["Unspecified"]
#> },
#> "background": {
#> "text": ["Unspecified"]
#> },
#> "philsci": {
#> "text": ["Unspecified"]
#> },
#> "positionality": {
#> "text": ["Unspecified"]
#> },
#> "stages": {
#> "text": ["Unspecified"]
#> },
#> "stage": {
#> "text": ["Unspecified"]
#> },
#> "start_date": {
#> "text": ["Unspecified"]
#> },
#> "end_date": {
#> "text": ["Unspecified"]
#> },
#> "primary_research_question": {
#> "text": ["Unspecified"]
#> },
#> "secondary_research_question": {
#> "text": ["Unspecified"]
#> },
#> "expectations_hypotheses": {
#> "text": ["Unspecified"]
#> },
#> "main_vars": {
#> "text": ["Unspecified"]
#> },
#> "secondary_vars": {
#> "text": ["Unspecified"]
#> },
#> "additional_vars": {
#> "text": ["Unspecified"]
#> },
#> "data_origin": {
#> "text": ["Unspecified"]
#> },
#> "data_sampling": {
#> "text": ["Unspecified"]
#> },
#> "data_registration": {
#> "text": ["Unspecified"]
#> },
#> "data_bias_minimization": {
#> "text": ["Unspecified"]
#> },
#> "data_amount": {
#> "text": ["Unspecified"]
#> },
#> "anyware": {
#> "text": ["Unspecified"]
#> },
#> "repositories": {
#> "text": ["Unspecified"]
#> },
#> "preprint": {
#> "text": ["Unspecified"]
#> },
#> "misc_methods_details": {
#> "text": ["Unspecified"]
#> },
#> "missing_data": {
#> "text": ["Unspecified"]
#> },
#> "data_validation": {
#> "text": ["Unspecified"]
#> },
#> "analysis_plan": {
#> "text": ["Unspecified"]
#> },
#> "criteria_for_conclusions": {
#> "text": ["Unspecified"]
#> },
#> "analyst_masking": {
#> "text": ["Unspecified"]
#> },
#> "misc_analysis_details": {
#> "text": ["Unspecified"]
#> }
#> },
#> "jstf": {
#> "sources": [],
#> "assertions": [],
#> "justifications": [],
#> "decisions": [],
#> "justifier": []
#> },
#> "form": {
#> "instructions": {
#> "Intended Use": {
#> "heading": ["Intended Use"],
#> "description": ["This Inclusive General-Purpose Registration Form is designed to be applicable across disciplines (i.e., psychology, economics, law, physics, or any other field) and across study types (i.e., qualitative studies, quantitative studies, 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 if no specialized form or registration platform is available. As such, if at all possible, it is recommended to avoid using this form and instead use a specialized form. This inclusive general-purpose registration form achieves that inclusiveness and general-purposeness at the cost of specificity and comprehensiveness. Still, if specialized forms don't fit for your study, this form may be a good backup."]
#> }
#> },
#> "metadata": {
#> "title": {
#> "field": ["title"],
#> "content": ["Inclusive General-Purpose Registration Form"]
#> },
#> "author": {
#> "field": ["author"],
#> "content": ["Gjalt-Jorn Peters & Szilvia Zörgő"]
#> },
#> "date": {
#> "field": ["date"],
#> "content": ["2022-01-11"]
#> },
#> "comments": {
#> "field": ["comments"],
#> "content": ["This form was heavily based on the Inclusive Systematic Review Form by Van den Akker et al. (2020)."]
#> },
#> "version": {
#> "field": ["version"],
#> "content": ["1.1"]
#> }
#> },
#> "items": {
#> "discipline": {
#> "section_id": ["metadata"],
#> "item_id": ["discipline"],
#> "item_label": ["Discipline"],
#> "item_description": ["Here you can specify your discipline (e.g. law, chemistry, anthropology, etc)."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "title": {
#> "section_id": ["metadata"],
#> "item_id": ["title"],
#> "item_label": ["Title"],
#> "item_description": ["The title of this study (at this stage, anyway)."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "authors": {
#> "section_id": ["metadata"],
#> "item_id": ["authors"],
#> "item_label": ["Author(s) / contributor(s)"],
#> "item_description": ["The authors of / contributors to this study."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "tasks_and_roles": {
#> "section_id": ["metadata"],
#> "item_id": ["tasks_and_roles"],
#> "item_label": ["Tasks and roles"],
#> "item_description": ["Describe the expected tasks and roles of each author/contributor, for example using the Contributor Roles Taxonomy (CRediT)."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "funding": {
#> "section_id": ["metadata"],
#> "item_id": ["funding"],
#> "item_label": ["Funding"],
#> "item_description": ["List the funding sources for everybody that is involved in this study at this stage. If the work is not funded, please state this as such."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "cois": {
#> "section_id": ["metadata"],
#> "item_id": ["cois"],
#> "item_label": ["Conflicts of interest"],
#> "item_description": ["List any potential conflicts of interest (e.g., if there is a potential outcome of this study that can in any way have negative or positive effects for anybody involved in this study in terms of funding, prestige, or opportunities). If there are no conflicts of interest, please state this as such."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "type_of_study": {
#> "section_id": ["background"],
#> "item_id": ["type_of_study"],
#> "item_label": ["Type of study"],
#> "item_description": ["How would you describe the type of study you are (pre)registering (examples are \"systematic review\", \"cost-effectiveness trial\", or \"observational study\", but use your own words)?"],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "background": {
#> "section_id": ["background"],
#> "item_id": ["background"],
#> "item_label": ["Background"],
#> "item_description": ["Introduce the topic of your study, its aims, and/or provide a short summary of known literature and what you want to add to this literature with your study."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "philsci": {
#> "section_id": ["background"],
#> "item_id": ["philsci"],
#> "item_label": ["Philosophy of Science"],
#> "item_description": ["Describe the relevant elements of your ontological perspective (e.g. realism, relativism, pragmatism) and your epistemological perspective (e.g. empiricism, constructivism, skepticism), that is, those elements that are most relevant as a basis for the methodological choices you make in this study."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "positionality": {
#> "section_id": ["background"],
#> "item_id": ["positionality"],
#> "item_label": ["Positionality"],
#> "item_description": ["Describe how you (as a person) see your association with the studied phenomenon, describe your position in the research setting / field, and describe your academic and personal standpoints, assumptions and values (to the degree that they may shape how you approach this study). You don't need to repeat what you already describe in the items \"Conflicts of interest\" and \"Philosophy of Science\" (both in the Background section) and \"Expectations / hypotheses\" (in the Methods section). Instead you can use this item to enter information that wouldn't fit there but that might nonetheless potentially color your interpretations or otherwise shape your approach."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "stages": {
#> "section_id": ["background"],
#> "item_id": ["stages"],
#> "item_label": ["Study stages"],
#> "item_description": ["Indicate the stages in which you will conduct this study. Common stages are preparation, data collection, and analysis, specify the stages you will use using your own words."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "stage": {
#> "section_id": ["background"],
#> "item_id": ["stage"],
#> "item_label": ["Current study stage"],
#> "item_description": ["From the list you specified in the \"Study stages\" item, indicate in which stage you are at this moment (i.e., when you freeze this registration)."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "start_date": {
#> "section_id": ["background"],
#> "item_id": ["start_date"],
#> "item_label": ["Start date"],
#> "item_description": ["Indicate the planned start date, or if you already started, the actual start date."],
#> "item_valueTemplate": ["date"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "end_date": {
#> "section_id": ["background"],
#> "item_id": ["end_date"],
#> "item_label": ["End date"],
#> "item_description": ["Indicate the planned end date, or if you already completed the study, the actual end date."],
#> "item_valueTemplate": ["date"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "primary_research_question": {
#> "section_id": ["methods"],
#> "item_id": ["primary_research_question"],
#> "item_label": ["Primary research question(s)"],
#> "item_description": ["List the specific questions this study is meant to answer (i.e., the questions that ultimately informed the decisions made when designing the study plans you are registering). Note that all analyses pertaining to primary research questions should normally be reported in the final report."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "secondary_research_question": {
#> "section_id": ["methods"],
#> "item_id": ["secondary_research_question"],
#> "item_label": ["Secondary research question(s)"],
#> "item_description": ["List additional research questions that you will examine, but that took less central roles in informing the study's design. Note that all analyses pertaining to secondary research questions should normally be reported in the final report (the difference is that the study's design is mainly geared towards answering the primary research questions)."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "expectations_hypotheses": {
#> "section_id": ["methods"],
#> "item_id": ["expectations_hypotheses"],
#> "item_label": ["Expectations / hypotheses"],
#> "item_description": ["Describe any hypotheses and/or expectations you have. These can pertain to your research questions, the types of sources you will find, social and political contexts, and contextual information that you know may color your interpretations and decisions."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "main_vars": {
#> "section_id": ["methods"],
#> "item_id": ["main_vars"],
#> "item_label": ["Main variable(s) / outcome(s) / dependent variables"],
#> "item_description": ["List the concepts or main / dependent / outcome variables you are interested in. If this study concerns one or more associations, list the outcome variable(s) or dependent variables. If this study does not concern one or more associations, list the main variables of interest here."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "secondary_vars": {
#> "section_id": ["methods"],
#> "item_id": ["secondary_vars"],
#> "item_label": ["Secondary variable(s) / independent variable(s) / intervention(s) / treatment(s)"],
#> "item_description": ["If this study's research question(s) concerns one or more associations or effects, list the variable(s) that theoretically cause them or are assumed to otherwise explain the main variable(s) / dependent variable(s) / outcome(s). If this is a manipulation, treatment, or intervention, make sure to describe it in full: that means also describing all groups, including any control group(s) or comparator(s). If there are no secondary variables, you can just state that."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "additional_vars": {
#> "section_id": ["methods"],
#> "item_id": ["additional_vars"],
#> "item_label": ["Additional variable(s) / covariate(s)"],
#> "item_description": ["Here, list any additional variables you are interested in that were not included in the two lists above, such as covariates, moderators, or mediators. If there are no additional variables, you can just state that."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "data_origin": {
#> "section_id": ["methods"],
#> "item_id": ["data_origin"],
#> "item_label": ["Data origin"],
#> "item_description": ["Describe the origin of the data you will examine. Data here is meant as a broad term: it refers to primary or secondary data; data you will collect or data that already existed; data that are measurements, recordings, existing documents or reports. Basically, which bits of the world will you look at to answer your research question(s), and how will you obtain those bits? For example, will you study humans, animals, chemicals, laws? Which procedures do you plan to employ? If your study does not involve the analysis of data at all, you can also indicate that here (but in that case this form will probably mostly not be applicable)."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "data_sampling": {
#> "section_id": ["methods"],
#> "item_id": ["data_sampling"],
#> "item_label": ["Data sampling"],
#> "item_description": ["Describe whether you will sample your data from a larger population. If not (i.e. if you will study an entire population), you can also indicatie that here. If you do plan to sample from a larger set of potential research units, this is where you can describe your sampling procedure, explain why that procedure fits with your goals, and explain how you will minimize bias (e.g. various forms of selection bias). If you aim to obtain a sample with specific characteristics (e.g. stratified according to some variable or optimized for heterogeneity in some respects), you can also describe that here, explain why you strive for that, and explain why you believe that your procedure will achieve your aims."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "data_registration": {
#> "section_id": ["methods"],
#> "item_id": ["data_registration"],
#> "item_label": ["Data registration"],
#> "item_description": ["Describe how you will register your data. If you will obtain your data through measurement, state the measurement instruments that you will use and expain your basis for assuming that those measurement instruments are appropriate (e.g., given the sample and context of your study). If you will not use measurement to obtain your data, explain how you will register the data you will use. Here, you can also explain what the data will look like after registration, for example by describing the columns in the dataset you will analyze, or the media you will use to store your data (e.g. bitrates)."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "data_bias_minimization": {
#> "section_id": ["methods"],
#> "item_id": ["data_bias_minimization"],
#> "item_label": ["Data bias minimization"],
#> "item_description": ["Describe whether any procedures are in place to minimize bias that may be introduced as data are obtained. For example, will masking be applied? If data will be collected by people, will they be masked from the implications of patterns in the data for the research questions? If data will be collected from people (e.g., archivists, clerks, or research participants), will they be masked from the researchers' expectations regarding those data? If data are collected by an automated procedure (e.g., scraping websites), will the algorithms performing the data collection be vetted by others to try to identify biases? If no procedures will be implemented to minimize bias, you can also indicate and explain that here."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "data_amount": {
#> "section_id": ["methods"],
#> "item_id": ["data_amount"],
#> "item_label": ["Amount of data to be collected"],
#> "item_description": ["Describe how much data you plan to collect. For example, here you can explain whether you will study one research unit (often referred to as a case study), study the entire population, or for anything in between, how much data you plan to collect and why. If your data consists of archival records, social media data, case law, or chat logs, you can explain how many data sources you will analyse. If you will collect qualitative data, you can describe how much you plan to collect, and if you use saturation as a stopping rule, how you operationalize saturation. If you will conduct quantitative analyses, you can describe your sample size computations and which parameters you use (e.g. SESOI, alpha, power). In all cases, this is also where you explain why that amount of data is appropriate given your aims. If you have no specific plans for how much data you will collect, you can also explain that here."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "anyware": {
#> "section_id": ["methods"],
#> "item_id": ["anyware"],
#> "item_label": ["Anyware"],
#> "item_description": ["List the software and hardware you plan to use for the study. Include model/version numbers, producers, and operating systems, if applicable."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "repositories": {
#> "section_id": ["methods"],
#> "item_id": ["repositories"],
#> "item_label": ["Repositories"],
#> "item_description": ["List the repositories you will use to publish your data, analyses, materials, and documentation. If you do not plan to publish one or more of these, you can indicate and explain that here."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "preprint": {
#> "section_id": ["methods"],
#> "item_id": ["preprint"],
#> "item_label": ["Preprint server"],
#> "item_description": ["Indicate which preprint server you plan to use to publish the preprint(s) from this project. If you do not plan to publish a preprint, you can indicate and explain that here."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "misc_methods_details": {
#> "section_id": ["methods"],
#> "item_id": ["misc_methods_details"],
#> "item_label": ["Miscellaneous methods details"],
#> "item_description": ["Here, you can describe any details that are not captured in the other fields in this section."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "missing_data": {
#> "section_id": ["analyses"],
#> "item_id": ["missing_data"],
#> "item_label": ["Missing data"],
#> "item_description": ["Describe how you plan to deal with missing data (e.g. observations that cannot go through as planned, archive materials that cannot be obtained, problems with recordings, missing data points, participants who drop out, etc)."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "data_validation": {
#> "section_id": ["analyses"],
#> "item_id": ["data_validation"],
#> "item_label": ["Data validation"],
#> "item_description": ["Describe your process of ensuring that the data are correct and useful (e.g., identifying outliers, establishing correct and valid application of measurement instruments, triangulating with other sources, or other methods of verifying data integrity). Also describe your criteria for assessing data validity and how you will deal with data violating those criteria. Or, if you will not assess the correctness, usefulness, or validity of your data, you can explain that here."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "analysis_plan": {
#> "section_id": ["analyses"],
#> "item_id": ["analysis_plan"],
#> "item_label": ["Analysis plan"],
#> "item_description": ["Describe the specific procedure you will apply to arrive at an answer to the research question(s). If you distinguish analysis tiers (e.g., primary and secondary analyses, or confirmatory and exploratory analyses), list them and indicate which procedures you plan to use for each. Also specify what you will do if parts of the plan cannot be properly executed. This is also where you can explain your reasons for assuming that your chosen procedure is appropriate to arrive at the answers you seek."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "criteria_for_conclusions": {
#> "section_id": ["analyses"],
#> "item_id": ["criteria_for_conclusions"],
#> "item_label": ["Criteria for conclusions / inference criteria"],
#> "item_description": ["If you plan to draw your conclusions based on pre-specified criteria (e.g., a minimal effect size of interest, a significance level, or a saturation point), list these here, explain what they were based on, and explain your reasoning. If you plan to draw conclusions but will not use pre-specified criteria, you can explain why you will establish criteria later, by what procedure, and how you plan to ameliorate the risk of bias. Finally, if you will not draw any inferences (e.g., about theories or hypotheses), you can also explain that here."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "analyst_masking": {
#> "section_id": ["analyses"],
#> "item_id": ["analyst_masking"],
#> "item_label": ["Analyst masking"],
#> "item_description": ["Describe the procedure, if any, used to mask analysts (i.e., the person(s) analyzing the extracted data to arrive at answers to your research question(s)) from the research questions, expectations, hypotheses, and/or specific roles of each variable in this study. If you decide to not use masked analysists, you can state that decision here."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> },
#> "misc_analysis_details": {
#> "section_id": ["analyses"],
#> "item_id": ["misc_analysis_details"],
#> "item_label": ["Miscellaneous analysis details"],
#> "item_description": ["Here, you can describe any details that are not captured in the other fields in this section."],
#> "item_valueTemplate": ["string"],
#> "item_validValues": [null],
#> "item_validation": [null]
#> }
#> },
#> "sections": {
#> "metadata": {
#> "section_id": ["metadata"],
#> "section_label": ["Metadata"],
#> "section_description": ["This section includes some metadata about the study."]
#> },
#> "background": {
#> "section_id": ["background"],
#> "section_label": ["Background"],
#> "section_description": ["In this section, you can explain why you do this study."]
#> },
#> "methods": {
#> "section_id": ["methods"],
#> "section_label": ["Methods"],
#> "section_description": ["In this section, you register your plans: you describe what your data looks like and how you plan to obtain it."]
#> },
#> "analyses": {
#> "section_id": ["analyses"],
#> "section_label": ["Analyses"],
#> "section_description": ["In this section, you register the analyses you plan to conduct on the data to learn something."]
#> }
#> },
#> "valueTemplates": {
#> "numeric": {
#> "identifier": ["numeric"],
#> "description": ["Any valid number"],
#> "validValues": [null],
#> "default": ["NA"],
#> "examples": ["2.3 || 643.2"],
#> "validation": ["is.na(VALUE) || (is.numeric(VALUE) && (length(VALUE) == 1))"],
#> "error": ["NAME is not numeric, or contains more than one value."]
#> },
#> "integer": {
#> "identifier": ["integer"],
#> "description": ["Any valid whole number"],
#> "validValues": [null],
#> "default": ["NA"],
#> "examples": ["30 || 8762"],
#> "validation": ["is.na(VALUE) || (is.numeric(VALUE) && (VALUE%%1==0) && (length(VALUE) == 1))"],
#> "error": ["Error about NAME here."]
#> },
#> "string": {
#> "identifier": ["string"],
#> "description": ["A single character value"],
#> "validValues": [null],
#> "default": ["\"\""],
#> "examples": ["\"Example\" || \"Another example\""],
#> "validation": ["is.na(VALUE) || (is.character(VALUE) && length(VALUE) == 1)"],
#> "error": ["Error about NAME here."]
#> },
#> "identifier": {
#> "identifier": ["identifier"],
#> "description": ["A single character value that must start with a letter and can only contain alphanumeric characters and underscores"],
#> "validValues": [null],
#> "default": ["\"\""],
#> "examples": ["\"example1\" || \"example_2\""],
#> "validation": ["grepl(\"[A-Za-z][A-Za-z0-9_]*\", VALUE)"],
#> "error": ["Identifiers must start with a letter and consist only of alphanumeric characters and underscores."]
#> },
#> "countrycode": {
#> "identifier": ["countrycode"],
#> "description": ["An ISO 3166-1 alpha-2 country code"],
#> "validValues": [null],
#> "default": ["NA"],
#> "examples": ["\"NL\" || \"HU\""],
#> "validation": ["is.na(VALUE) || (VALUE %in% countryCodeList())"],
#> "error": ["Error about NAME here."]
#> },
#> "categorical": {
#> "identifier": ["categorical"],
#> "description": ["A string that has to exactly match one of the values specified in the \"items_validValues\" column of the items sheet"],
#> "validValues": [null],
#> "default": ["NA"],
#> "examples": ["{{validValues}}"],
#> "validation": ["is.na(VALUE) || (VALUE %in% {{validValues}})"],
#> "error": ["Error about NAME here."]
#> },
#> "date": {
#> "identifier": ["date"],
#> "description": ["An ISO 8601 date."],
#> "validValues": [null],
#> "default": ["NA"],
#> "examples": ["2021-03-03"],
#> "validation": ["grepl(\"^[0-9]{4}-[0-9]{2}-[0-9]{2}$\", VALUE)"],
#> "error": ["The specified date does not conform to the ISO 8601 standard (YYYY-MM-DD)."]
#> },
#> "string_mandatory": {
#> "identifier": ["string_mandatory"],
#> "description": ["A single character value that cannot be empty"],
#> "validValues": [null],
#> "default": ["\"\""],
#> "examples": ["\"Example\" || \"Another example\""],
#> "validation": ["(is.character(VALUE) && length(VALUE) == 1)"],
#> "error": ["Error about NAME here."]
#> }
#> }
#> },
#> "config": {
#> "initialText": ["Unspecified"]
#> }
#> }
### Load an example (pre)registration specification
data("examplePrereg_1", package = "preregr");
### Export to YAML
preregr::prereg_spec_to_yaml(
examplePrereg_1
);
#> specs:
#> discipline:
#> text: Thaumatology
#> title:
#> text: 'Cabbages cast in moderation: a comparative analysis'
#> authors:
#> text: Littlebottom, C., Dibbler, C., & Aching, T.
#> tasks_and_roles:
#> text: Unspecified
#> funding:
#> text: Unspecified
#> cois:
#> text: Unspecified
#> type_of_study:
#> text: Unspecified
#> background:
#> text: Unspecified
#> philsci:
#> text: Unspecified
#> positionality:
#> text: Unspecified
#> stages:
#> text: Unspecified
#> stage:
#> text: Unspecified
#> start_date:
#> text: Unspecified
#> end_date:
#> text: Unspecified
#> primary_research_question:
#> text: Unspecified
#> secondary_research_question:
#> text: Unspecified
#> expectations_hypotheses:
#> text: Unspecified
#> main_vars:
#> text: Unspecified
#> secondary_vars:
#> text: Unspecified
#> additional_vars:
#> text: Unspecified
#> data_origin:
#> text: Unspecified
#> data_sampling:
#> text: Unspecified
#> data_registration:
#> text: Unspecified
#> data_bias_minimization:
#> text: Unspecified
#> data_amount:
#> text: Unspecified
#> anyware:
#> text: Unspecified
#> repositories:
#> text: Unspecified
#> preprint:
#> text: Unspecified
#> misc_methods_details:
#> text: Unspecified
#> missing_data:
#> text: Unspecified
#> data_validation:
#> text: Unspecified
#> analysis_plan:
#> text: Unspecified
#> criteria_for_conclusions:
#> text: Unspecified
#> analyst_masking:
#> text: Unspecified
#> misc_analysis_details:
#> text: Unspecified
#> jstf:
#> sources: []
#> assertions: []
#> justifications: []
#> decisions: []
#> justifier: []
#> form:
#> instructions:
#> Intended Use:
#> heading: Intended Use
#> description: This Inclusive General-Purpose Registration Form is designed to
#> be applicable across disciplines (i.e., psychology, economics, law, physics,
#> or any other field) and across study types (i.e., qualitative studies, quantitative
#> studies, 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 if no specialized form or registration
#> platform is available. As such, if at all possible, it is recommended to avoid
#> using this form and instead use a specialized form. This inclusive general-purpose
#> registration form achieves that inclusiveness and general-purposeness at the
#> cost of specificity and comprehensiveness. Still, if specialized forms don't
#> fit for your study, this form may be a good backup.
#> metadata:
#> title:
#> field: title
#> content: Inclusive General-Purpose Registration Form
#> author:
#> field: author
#> content: Gjalt-Jorn Peters & Szilvia Zörgő
#> date:
#> field: date
#> content: '2022-01-11'
#> comments:
#> field: comments
#> content: This form was heavily based on the Inclusive Systematic Review Form
#> by Van den Akker et al. (2020).
#> version:
#> field: version
#> content: '1.1'
#> items:
#> discipline:
#> section_id: metadata
#> item_id: discipline
#> item_label: Discipline
#> item_description: Here you can specify your discipline (e.g. law, chemistry,
#> anthropology, etc).
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> title:
#> section_id: metadata
#> item_id: title
#> item_label: Title
#> item_description: The title of this study (at this stage, anyway).
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> authors:
#> section_id: metadata
#> item_id: authors
#> item_label: Author(s) / contributor(s)
#> item_description: The authors of / contributors to this study.
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> tasks_and_roles:
#> section_id: metadata
#> item_id: tasks_and_roles
#> item_label: Tasks and roles
#> item_description: Describe the expected tasks and roles of each author/contributor,
#> for example using the Contributor Roles Taxonomy (CRediT).
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> funding:
#> section_id: metadata
#> item_id: funding
#> item_label: Funding
#> item_description: List the funding sources for everybody that is involved in
#> this study at this stage. If the work is not funded, please state this as
#> such.
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> cois:
#> section_id: metadata
#> item_id: cois
#> item_label: Conflicts of interest
#> item_description: List any potential conflicts of interest (e.g., if there is
#> a potential outcome of this study that can in any way have negative or positive
#> effects for anybody involved in this study in terms of funding, prestige,
#> or opportunities). If there are no conflicts of interest, please state this
#> as such.
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> type_of_study:
#> section_id: background
#> item_id: type_of_study
#> item_label: Type of study
#> item_description: How would you describe the type of study you are (pre)registering
#> (examples are "systematic review", "cost-effectiveness trial", or "observational
#> study", but use your own words)?
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> background:
#> section_id: background
#> item_id: background
#> item_label: Background
#> item_description: Introduce the topic of your study, its aims, and/or provide
#> a short summary of known literature and what you want to add to this literature
#> with your study.
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> philsci:
#> section_id: background
#> item_id: philsci
#> item_label: Philosophy of Science
#> item_description: Describe the relevant elements of your ontological perspective
#> (e.g. realism, relativism, pragmatism) and your epistemological perspective
#> (e.g. empiricism, constructivism, skepticism), that is, those elements that
#> are most relevant as a basis for the methodological choices you make in this
#> study.
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> positionality:
#> section_id: background
#> item_id: positionality
#> item_label: Positionality
#> item_description: Describe how you (as a person) see your association with the
#> studied phenomenon, describe your position in the research setting / field,
#> and describe your academic and personal standpoints, assumptions and values
#> (to the degree that they may shape how you approach this study). You don't
#> need to repeat what you already describe in the items "Conflicts of interest"
#> and "Philosophy of Science" (both in the Background section) and "Expectations
#> / hypotheses" (in the Methods section). Instead you can use this item to enter
#> information that wouldn't fit there but that might nonetheless potentially
#> color your interpretations or otherwise shape your approach.
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> stages:
#> section_id: background
#> item_id: stages
#> item_label: Study stages
#> item_description: Indicate the stages in which you will conduct this study.
#> Common stages are preparation, data collection, and analysis, specify the
#> stages you will use using your own words.
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> stage:
#> section_id: background
#> item_id: stage
#> item_label: Current study stage
#> item_description: From the list you specified in the "Study stages" item, indicate
#> in which stage you are at this moment (i.e., when you freeze this registration).
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> start_date:
#> section_id: background
#> item_id: start_date
#> item_label: Start date
#> item_description: Indicate the planned start date, or if you already started,
#> the actual start date.
#> item_valueTemplate: date
#> item_validValues: .na.character
#> item_validation: .na.character
#> end_date:
#> section_id: background
#> item_id: end_date
#> item_label: End date
#> item_description: Indicate the planned end date, or if you already completed
#> the study, the actual end date.
#> item_valueTemplate: date
#> item_validValues: .na.character
#> item_validation: .na.character
#> primary_research_question:
#> section_id: methods
#> item_id: primary_research_question
#> item_label: Primary research question(s)
#> item_description: List the specific questions this study is meant to answer
#> (i.e., the questions that ultimately informed the decisions made when designing
#> the study plans you are registering). Note that all analyses pertaining to
#> primary research questions should normally be reported in the final report.
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> secondary_research_question:
#> section_id: methods
#> item_id: secondary_research_question
#> item_label: Secondary research question(s)
#> item_description: List additional research questions that you will examine,
#> but that took less central roles in informing the study's design. Note that
#> all analyses pertaining to secondary research questions should normally be
#> reported in the final report (the difference is that the study's design is
#> mainly geared towards answering the primary research questions).
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> expectations_hypotheses:
#> section_id: methods
#> item_id: expectations_hypotheses
#> item_label: Expectations / hypotheses
#> item_description: Describe any hypotheses and/or expectations you have. These
#> can pertain to your research questions, the types of sources you will find,
#> social and political contexts, and contextual information that you know may
#> color your interpretations and decisions.
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> main_vars:
#> section_id: methods
#> item_id: main_vars
#> item_label: Main variable(s) / outcome(s) / dependent variables
#> item_description: List the concepts or main / dependent / outcome variables
#> you are interested in. If this study concerns one or more associations, list
#> the outcome variable(s) or dependent variables. If this study does not concern
#> one or more associations, list the main variables of interest here.
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> secondary_vars:
#> section_id: methods
#> item_id: secondary_vars
#> item_label: Secondary variable(s) / independent variable(s) / intervention(s)
#> / treatment(s)
#> item_description: 'If this study''s research question(s) concerns one or more
#> associations or effects, list the variable(s) that theoretically cause them
#> or are assumed to otherwise explain the main variable(s) / dependent variable(s)
#> / outcome(s). If this is a manipulation, treatment, or intervention, make
#> sure to describe it in full: that means also describing all groups, including
#> any control group(s) or comparator(s). If there are no secondary variables,
#> you can just state that.'
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> additional_vars:
#> section_id: methods
#> item_id: additional_vars
#> item_label: Additional variable(s) / covariate(s)
#> item_description: Here, list any additional variables you are interested in
#> that were not included in the two lists above, such as covariates, moderators,
#> or mediators. If there are no additional variables, you can just state that.
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> data_origin:
#> section_id: methods
#> item_id: data_origin
#> item_label: Data origin
#> item_description: 'Describe the origin of the data you will examine. Data here
#> is meant as a broad term: it refers to primary or secondary data; data you
#> will collect or data that already existed; data that are measurements, recordings,
#> existing documents or reports. Basically, which bits of the world will you
#> look at to answer your research question(s), and how will you obtain those
#> bits? For example, will you study humans, animals, chemicals, laws? Which
#> procedures do you plan to employ? If your study does not involve the analysis
#> of data at all, you can also indicate that here (but in that case this form
#> will probably mostly not be applicable).'
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> data_sampling:
#> section_id: methods
#> item_id: data_sampling
#> item_label: Data sampling
#> item_description: Describe whether you will sample your data from a larger population.
#> If not (i.e. if you will study an entire population), you can also indicatie
#> that here. If you do plan to sample from a larger set of potential research
#> units, this is where you can describe your sampling procedure, explain why
#> that procedure fits with your goals, and explain how you will minimize bias
#> (e.g. various forms of selection bias). If you aim to obtain a sample with
#> specific characteristics (e.g. stratified according to some variable or optimized
#> for heterogeneity in some respects), you can also describe that here, explain
#> why you strive for that, and explain why you believe that your procedure will
#> achieve your aims.
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> data_registration:
#> section_id: methods
#> item_id: data_registration
#> item_label: Data registration
#> item_description: Describe how you will register your data. If you will obtain
#> your data through measurement, state the measurement instruments that you
#> will use and expain your basis for assuming that those measurement instruments
#> are appropriate (e.g., given the sample and context of your study). If you
#> will not use measurement to obtain your data, explain how you will register
#> the data you will use. Here, you can also explain what the data will look
#> like after registration, for example by describing the columns in the dataset
#> you will analyze, or the media you will use to store your data (e.g. bitrates).
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> data_bias_minimization:
#> section_id: methods
#> item_id: data_bias_minimization
#> item_label: Data bias minimization
#> item_description: Describe whether any procedures are in place to minimize bias
#> that may be introduced as data are obtained. For example, will masking be
#> applied? If data will be collected by people, will they be masked from the
#> implications of patterns in the data for the research questions? If data will
#> be collected from people (e.g., archivists, clerks, or research participants),
#> will they be masked from the researchers' expectations regarding those data?
#> If data are collected by an automated procedure (e.g., scraping websites),
#> will the algorithms performing the data collection be vetted by others to
#> try to identify biases? If no procedures will be implemented to minimize bias,
#> you can also indicate and explain that here.
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> data_amount:
#> section_id: methods
#> item_id: data_amount
#> item_label: Amount of data to be collected
#> item_description: Describe how much data you plan to collect. For example, here
#> you can explain whether you will study one research unit (often referred to
#> as a case study), study the entire population, or for anything in between,
#> how much data you plan to collect and why. If your data consists of archival
#> records, social media data, case law, or chat logs, you can explain how many
#> data sources you will analyse. If you will collect qualitative data, you can
#> describe how much you plan to collect, and if you use saturation as a stopping
#> rule, how you operationalize saturation. If you will conduct quantitative
#> analyses, you can describe your sample size computations and which parameters
#> you use (e.g. SESOI, alpha, power). In all cases, this is also where you explain
#> why that amount of data is appropriate given your aims. If you have no specific
#> plans for how much data you will collect, you can also explain that here.
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> anyware:
#> section_id: methods
#> item_id: anyware
#> item_label: Anyware
#> item_description: List the software and hardware you plan to use for the study.
#> Include model/version numbers, producers, and operating systems, if applicable.
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> repositories:
#> section_id: methods
#> item_id: repositories
#> item_label: Repositories
#> item_description: List the repositories you will use to publish your data, analyses,
#> materials, and documentation. If you do not plan to publish one or more of
#> these, you can indicate and explain that here.
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> preprint:
#> section_id: methods
#> item_id: preprint
#> item_label: Preprint server
#> item_description: Indicate which preprint server you plan to use to publish
#> the preprint(s) from this project. If you do not plan to publish a preprint,
#> you can indicate and explain that here.
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> misc_methods_details:
#> section_id: methods
#> item_id: misc_methods_details
#> item_label: Miscellaneous methods details
#> item_description: Here, you can describe any details that are not captured in
#> the other fields in this section.
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> missing_data:
#> section_id: analyses
#> item_id: missing_data
#> item_label: Missing data
#> item_description: Describe how you plan to deal with missing data (e.g. observations
#> that cannot go through as planned, archive materials that cannot be obtained,
#> problems with recordings, missing data points, participants who drop out,
#> etc).
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> data_validation:
#> section_id: analyses
#> item_id: data_validation
#> item_label: Data validation
#> item_description: Describe your process of ensuring that the data are correct
#> and useful (e.g., identifying outliers, establishing correct and valid application
#> of measurement instruments, triangulating with other sources, or other methods
#> of verifying data integrity). Also describe your criteria for assessing data
#> validity and how you will deal with data violating those criteria. Or, if
#> you will not assess the correctness, usefulness, or validity of your data,
#> you can explain that here.
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> analysis_plan:
#> section_id: analyses
#> item_id: analysis_plan
#> item_label: Analysis plan
#> item_description: Describe the specific procedure you will apply to arrive at
#> an answer to the research question(s). If you distinguish analysis tiers (e.g.,
#> primary and secondary analyses, or confirmatory and exploratory analyses),
#> list them and indicate which procedures you plan to use for each. Also specify
#> what you will do if parts of the plan cannot be properly executed. This is
#> also where you can explain your reasons for assuming that your chosen procedure
#> is appropriate to arrive at the answers you seek.
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> criteria_for_conclusions:
#> section_id: analyses
#> item_id: criteria_for_conclusions
#> item_label: Criteria for conclusions / inference criteria
#> item_description: If you plan to draw your conclusions based on pre-specified
#> criteria (e.g., a minimal effect size of interest, a significance level, or
#> a saturation point), list these here, explain what they were based on, and
#> explain your reasoning. If you plan to draw conclusions but will not use pre-specified
#> criteria, you can explain why you will establish criteria later, by what procedure,
#> and how you plan to ameliorate the risk of bias. Finally, if you will not
#> draw any inferences (e.g., about theories or hypotheses), you can also explain
#> that here.
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> analyst_masking:
#> section_id: analyses
#> item_id: analyst_masking
#> item_label: Analyst masking
#> item_description: Describe the procedure, if any, used to mask analysts (i.e.,
#> the person(s) analyzing the extracted data to arrive at answers to your research
#> question(s)) from the research questions, expectations, hypotheses, and/or
#> specific roles of each variable in this study. If you decide to not use masked
#> analysists, you can state that decision here.
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> misc_analysis_details:
#> section_id: analyses
#> item_id: misc_analysis_details
#> item_label: Miscellaneous analysis details
#> item_description: Here, you can describe any details that are not captured in
#> the other fields in this section.
#> item_valueTemplate: string
#> item_validValues: .na.character
#> item_validation: .na.character
#> sections:
#> metadata:
#> section_id: metadata
#> section_label: Metadata
#> section_description: This section includes some metadata about the study.
#> background:
#> section_id: background
#> section_label: Background
#> section_description: In this section, you can explain why you do this study.
#> methods:
#> section_id: methods
#> section_label: Methods
#> section_description: 'In this section, you register your plans: you describe
#> what your data looks like and how you plan to obtain it.'
#> analyses:
#> section_id: analyses
#> section_label: Analyses
#> section_description: In this section, you register the analyses you plan to
#> conduct on the data to learn something.
#> valueTemplates:
#> numeric:
#> identifier: numeric
#> description: Any valid number
#> validValues: .na.character
#> default: NA
#> examples: 2.3 || 643.2
#> validation: is.na(VALUE) || (is.numeric(VALUE) && (length(VALUE) == 1))
#> error: NAME is not numeric, or contains more than one value.
#> integer:
#> identifier: integer
#> description: Any valid whole number
#> validValues: .na.character
#> default: NA
#> examples: 30 || 8762
#> validation: is.na(VALUE) || (is.numeric(VALUE) && (VALUE%%1==0) && (length(VALUE)
#> == 1))
#> error: Error about NAME here.
#> string:
#> identifier: string
#> description: A single character value
#> validValues: .na.character
#> default: '""'
#> examples: '"Example" || "Another example"'
#> validation: is.na(VALUE) || (is.character(VALUE) && length(VALUE) == 1)
#> error: Error about NAME here.
#> identifier:
#> identifier: identifier
#> description: A single character value that must start with a letter and can
#> only contain alphanumeric characters and underscores
#> validValues: .na.character
#> default: '""'
#> examples: '"example1" || "example_2"'
#> validation: grepl("[A-Za-z][A-Za-z0-9_]*", VALUE)
#> error: Identifiers must start with a letter and consist only of alphanumeric
#> characters and underscores.
#> countrycode:
#> identifier: countrycode
#> description: An ISO 3166-1 alpha-2 country code
#> validValues: .na.character
#> default: NA
#> examples: '"NL" || "HU"'
#> validation: is.na(VALUE) || (VALUE %in% countryCodeList())
#> error: Error about NAME here.
#> categorical:
#> identifier: categorical
#> description: A string that has to exactly match one of the values specified
#> in the "items_validValues" column of the items sheet
#> validValues: .na.character
#> default: NA
#> examples: '{{validValues}}'
#> validation: is.na(VALUE) || (VALUE %in% {{validValues}})
#> error: Error about NAME here.
#> date:
#> identifier: date
#> description: An ISO 8601 date.
#> validValues: .na.character
#> default: NA
#> examples: '2021-03-03'
#> validation: grepl("^[0-9]{4}-[0-9]{2}-[0-9]{2}$", VALUE)
#> error: The specified date does not conform to the ISO 8601 standard (YYYY-MM-DD).
#> string_mandatory:
#> identifier: string_mandatory
#> description: A single character value that cannot be empty
#> validValues: .na.character
#> default: '""'
#> examples: '"Example" || "Another example"'
#> validation: (is.character(VALUE) && length(VALUE) == 1)
#> error: Error about NAME here.
#> config:
#> initialText: Unspecified
#>