Skip to main content

Writing A Reproducible Manuscript In R With WORCS

Phase 1: Study Design

Notes for cautious researchers

Some researchers might want to share their work only once the paper is accepted for publication. In this case, we recommend creating a “Private” repository in Step 1, and completing Steps 13-18 in Phase 3 upon acceptance by the journal.

  1. Create a new remote repository on a ‘Git’ hosting service, such as “GitHub”

    • For inexperienced users, we recommend making this repository “Private”, which means only you and selected co-authors can access it. You can set it to “Public” later - for example, when the paper goes to print - and the entire history of the Repository will be public record. We recommend making the repository “Public” from the start only if you are an experienced user and know what you are doing.
    • Copy the repository’s SSH link to clipboard; this link should look something like git@github.com:username/repository.git

  2. In Rstudio, click File > New Project > New directory > WORCS Project Template

    1. Paste the remote Repository address in the textbox. This address should look like git@github.com:username/repository.git
    2. Keep the checkbox for renv checked if you want to use dependency management (recommended)
    3. Select a preregistration template, or add a preregistration later using add_preregistration()
    4. Select a manuscript template, or add a manuscript later using add_manuscript()
    5. Select a license for your project (we recommend a CC-BY license, which allows free use of the licensed material as long as the creator is credited)

  3. A template README.md file will be automatically generated during project creation. Edit this template to explain how users should interact with the project. Based on your selections in the New Project dialog, a LICENSE will also be added to the project, to explain users’ rights and limit your liability. We recommend a CC-BY license, which allows free use of the licensed material as long as the creator is credited.

  4. For this workshop, we will already do a round of committing and pushing local changes to GitHub before proceeding further.

    1. Click the “Git” tab in the upper right pane
    2. Check the ‘Staged’ box for all the files
    3. If you’re not already in the Git pop-up window, click ‘Commit’
    4. Type a simple, but meaningful message in the “Commit message” box such as initial commit with WORCS project structure
    • Click the ‘Push’ button (with the green upwards arrow) to upload your changes to GitHub. Note that you might be prompted to enter your GitHub username and password
    • Go to the project repository on GitHub and refresh the page, the local changes should now be visible online. You should see all the files you staged and the commit message you provided will be noted in the history of the repository.

  5. Optional: Preregister your analysis by committing a plain-text preregistration and tag this commit with the label “preregistration”:

    • Document study plans in a preregistration.Rmd file, and optionally, planned analyses in a .R file.
    • In the top-right panel of ‘RStudio’, select the ‘Git’ tab
    • Select the checkbox next to the preregistration file(s)
    • Click the Commit button.
    • In the pop-up window, write an informative “Commit message”, e.g., “Preregistration”
    • Click the Commit button below the message dialog
    • Click the green arrow labeled “Push” to send your commit to the ‘Git’ remote repository
    • Tag this commit as a release on the remote repository, using the label “preregistration”. A tagged release helps others retrieve this commit.
    • Instructions for ‘GitHub’ are explained here

  6. Optional: Render the preregistration to PDF, and upload it as an attachment to a dedicated preregistration server like AsPredicted.org or OSF.io

    • In ‘RStudio’, with the file ‘preregistration.Rmd’ open, click the “Knit” button above the top left panel
    • When the PDF is generated, go to one of the recognized preregistration services’ websites, create a new preregistration, and upload it as an attachment.
    • Optional: Generate a DOI for the preregistration through the OSF or a service like Zenodo

  7. Optional: Add study materials to the repository.

    • Only do this for study materials to which you own the rights, or when the materials’ license allows it
    • You can solicit feedback and outside contributions on a ‘Git’ remote repository by opening an “Issue” or by accepting “Pull requests”