TEMPLATES

README Template
Codebook Template
Data Citation Format

README Template

Instructions: This template provides content and structure suggestions that will meet the requirements of the SPPQ Verification Policy. Authors can tailor this README to fit their research and Dataverse package circumstances. The template is available in this html version or a .TXT version for download. Please save your README as a .TXT file for long-term preservation.

Review README Checklist

If you have any questions, please contact the SPPQ Editors.

------ README TEMPLATE BEGINS ------ 

I. SPPQ DATA PACKAGE INFORMATION

[Article Title]
[Author(s)] — [Affiliation] — [E-mail] — [ORCID (optional)]
[Author(s)] — [Affiliation] — [E-mail] — [ORCID (optional)]
[Date or version]

EXAMPLE
Date: 2020-01-10
Title: SPPQ Data Verification and Reproducibility Guidance
Authors: 
Jane Smith, University of North Carolina at Chapel Hill, <smithjane@edu.unc>
John Doe, University of North Carolina at Chapel Hill, <doejohn@edu.unc>

II. COMPUTE ENVIRONMENT
Instructions: Please list all the software, packages, operating system, versions, and any dependencies in your compute environment that are required to replicate your results. 

[Operating system]
[Software and versions]
[Packages and their versions used in analysis]
[Estimated run time for all analyses]
[HPC: If you are using an HPC system, include the submission script(s) and additional information on the HPC scheduler, required modules, memory needed, run time needed, number of processes to run (nodes, tasks), etc.]

EXAMPLE

R version 3.6.1 (2019-07-05)
Platform: x86_64-w64-mingw32/x64 (64-bit)
Running under: Windows 10 x64 (build 17134)

Attached packages:
 [1] sandwich_2.5-1   MatchIt_3.0.2    pBrackets_1.0    reshape2_1.4.3  
 [5] psych_1.9.12.31  xtable_1.8-4     stargazer_5.2.2  lmtest_0.9-37   
 [9] zoo_1.8-6        lme4_1.1-23      Matrix_1.2-17    plm_2.2-3       
[13] memisc_0.99.17.2 MASS_7.3-51.4    lattice_0.20-38  plyr_1.8.4      
[17] car_3.0-7        carData_3.0-2    foreign_0.8-71   rio_0.5.16  

Estimated Run Time: 2 hours

III. FILE LIST
Instructions: Please list all the files in your SPPQ Dataverse package as well as any files that you are not able to post in SPPQ Dataverse due to restrictions. If there is a folder hierarchy in your Dataverse package, you can list the files and folder structure here.

Data
1. [Filename] — [Brief file description]

Code
2. [Filename] — [Brief file description]
3. [Filename] — [Brief file description]

Documentation:
4. [README Filename] — [Brief file description]
5. [Codebook Filename] — [Brief file description]

EXAMPLE

DATA	
1. partypositionssrvy.csv - responses to party positions survey.
2. followup_srvy.csv - responses to follow-up survey.

CODE
3. build_data.R - script that generates the analysis data file from the original survey data files.
4. main_analysis.R - script that reproduces all results and figures reported in the main article and appendices.

DOCUMENTATION
5. README.txt - description of the SPPQ Dataverse package, files, compute environment, and data sources.
6. codebook.pdf - description of variables contained in "partypositionssrvy.csv" and "followup_srvy.csv".
7. questionnaires.pdf - first and follow-up questionnaires with telephone scripts and prompts.

IV. DATA SOURCES (IF REQUIRED)
Instructions: If you created your analysis data from original data sources (not produced by the authors), you are required to provide formal citations and access instructions for obtaining the data that you used in your analysis. If the original data cannot be shared within Dataverse due to restrictions, please provide the data citation, reason for exclusion, and in-depth instructions for requesting access to data along with the exact file names you requested. Please make sure to inform the editors that you cannot share specific data due to data producer's restrictions.

1. [Title of Data Source]
[Formal citation - Author, Year Published, "Title of Data," Data Holder, Version, Persistent identifier, URL, Date Accessed.]
[Additional access instructions]

2. [Title of Data Source]
[Formal citation - Author, Year Published, "Title of Data," Data Holder, Version, Persistent identifier, URL, Date Accessed.]
[Additional access instructions]

EXAMPLE

1. Jolly, Seth, Ryan Bakker, Liesbet Hooghe, Gary Marks, Jonathan Polk, Jan Rovny, Marco Steenbergen, and Milada Anna Vachudova. 2022. “Chapel Hill Expert Survey Trend File, 1999-2019.” Electoral Studies 75 (February). https://doi.org/10.1016/j.electstud.2021.102420 Accessed 2022-09-01.

2. Bureau van Dijk, 2019, Orbis database. https://oldorbis.bvdinfo.com/ Accessed 2022-09-01.

Reason for Exclusion: The Orbis database cannot be posted in SPPQ Dataverse due to their proprietary nature. Below are data access instructions to discover and obtain the same data as used in this study. 

Access Instructions:The Orbis data are located at https://oldorbis.bvdinfo.com/. Please note a subscription is required to access these data. To access the Orbis data, go to the website and navigate to the search tab. I have included a file of Identification numbers (bvdids) that I used in my study: randombvdids.csv. Click on Identification numbers > BvD ID number. You can upload the file of bvdids that I provided, and Orbis will search for these identification numbers. The results will report all matching firms on the Home > List page. (You may need to click on View list of results on the Home page to see this.) 

V. WORKFLOW (IF REQUIRED)
Instructions: For some analysis workflow, the script(s) may have dependencies and require a verifier to set up the environment in a certain way, load packages at certain points, or run scripts in a certain order. For instance, you execute only script 1 and, when script 1 finishes, you can execute scripts 2 and 3 concurrently. This section is to document any information that a verifier needs to know about executing your workflow. 

EXAMPLE

Note: Set the working directory to the folder where you placed the data and code on your machine. For figure generation, first run all the Stata code to generate estimates and then R files to plot them. 

VI. ADDITIONAL INFORMATION (IF REQUIRED)
Instructions: This section is really to provide information that a verifier would need to know to use or interpret your data that has not already been provided in a previous section. It might include data set up or formatting or database schema (tables, relationships, keys). This section will not be necessary in all situations.  

EXAMPLE

Note: The data files are not encoded in UTF-8, and some software programs assume UTF-8 encoding. You might need to re-save the files with UTF-8 encoding for the code to execute. To do so, open the files in RStudio by: File -> Reopen with Encoding -> Choose encoding -> UTF-8

------ TEMPLATE ENDS ------

Back to top

------ CODEBOOK TEMPLATE BEGINS ------ 

I. SPPQ DATA PACKAGE INFORMATION

[Article Title]
[Author(s)] — [Affiliation] — [E-mail] — [ORCID (optional)]
[Author(s)] — [Affiliation] — [E-mail] — [ORCID (optional)]
[Date or version]

EXAMPLE

Date: 2020-01-10
Title: SPPQ Data Verification and Reproducibility Guidance
Authors: 
Jane Smith, University of North Carolina at Chapel Hill, <smithjane@edu.unc>
John Doe, University of North Carolina at Chapel Hill, <doejohn@edu.unc>

II. VARIABLE DOCUMENTATION
Instructions: This section should describe your variables and provide enough information for a future user to interpret and use them correctly. A good question to ask is: Is there anything that a future user would need to know about the variable construction or set up to use these data?

If the codebook covers multiple datasets, please divide the codebook into sections where each section corresponds to one of the datasets. 

[Data file name]
[Variable Name - Brief Description - Values/Labels - Source]
[Variable Name - Brief Description - Values/Labels - Source]
[Variable Name - Brief Description - Values/Labels - Source]
[Variable Name - Brief Description - Values/Labels - Source]

[Data file name]
[Variable Name - Brief Description - Values/Labels - Source]
[Variable Name - Brief Description - Values/Labels - Source]
[Variable Name - Brief Description - Values/Labels - Source]
[Variable Name - Brief Description - Values/Labels - Source]
[Variable Name - Brief Description - Values/Labels - Source]

EXAMPLE
- A. Codebook for datafile.dta
[Variable | Variable Definition | Value & Value Label(s) | Source]
[Gender | Respondent is male or female | 1 = Male; 2 = Female | ]
[Age | Age of respondent | 1 = 18 — 25; 2 = 26 — 30; 3 = 31 — 35; 4 = 36 — 40; 5 = 40 & older; . = Missing | ]
[Female_labor | Percentage of women on the labor market | | The World Bank (2017)]
[ChRef (binary) | Whether the sponsor is Chair of the committees to which the bill is referred | 1 = Sponsor is Chair of one of the committees to which the bill is referred; 0 = Otherwise | ]

------ CODEBOOK TEMPLATE ENDS ------

Back to top

Data Citation Format

If your manuscript utilizes original, external data sources (i.e., not produced by the authors), you need to cite all data sources used in your research to ensure data producers receive proper scholarly acknowledgement. For crafting a formal data citation, please see the ICPSR’s Citing Data style guide.

Original data can come from a variety of sources: other researchers, online databases, government agencies, and even hand-copied from tables on web pages.

Below is a suggestion for the content of a data citation:

• Author or Data producer
• Year Published
• Title of the data
• Persistent identifier (DOI, ARK, etc)
• Data holder or distributor
• Version if applicable
• URL
• Date accessed

When we review data citations and access information, we need to be able to go to the resource and find the same data that you used.

Examples of Data Citations

1. Jolly, Seth, Ryan Bakker, Liesbet Hooghe, Gary Marks, Jonathan Polk, Jan Rovny, Marco Steenbergen, and Milada Anna Vachudova. 2022. “Chapel Hill Expert Survey Trend File, 1999-2019.” Electoral Studies 75 (February). https://doi.org/10.1016/j.electstud.2021.102420 Accessed 2022-09-01.
2. Greene, Kenneth. Mexico Panel Study, 2012. Ann Arbor, MI: Inter-university Consortium for Political and Social Research [distributor], 2016-03-11. https://doi.org/10.3886/ICPSR35024.v1 Accessed 2022-09-01.
3. Office of the Registrar General Census Commissioner, Government of India. 2022. Census of India, 1991 and 2001. Delhi, India. https://censusindia.gov.in/census.website/data/census-tables Accessed 2022-09-01.

Back to top