workflowr

workflowr: organized + reproducible + shareable data science in R

The workflowr R package helps researchers organize their analyses in a way that
promotes effective project management, reproducibility, collaboration, and
sharing of results. Workflowr combines literate programming (knitr and
rmarkdown) and version control (Git, via git2r) to generate a website containing
time-stamped, versioned, and documented results. Any R user can quickly and
easily adopt workflowr.

For more details, see the online documentation. For an
example, see the Divvy data exploration project. To explore
reproducible research projects facilitated by workflowr, browse the projects
registered at workflowr.io. To keep up-to-date with the latest workflowr
developments, please join the workflowr-announce mailing list (low-volume,
read-only). For bugs reports, feature requests, and questions, please open an
Issue.

• Features
• Installation
• Quick start
• Attribution
• Contributing

Features

• Organized
  • Provides a project template with organized subdirectories
  • Mixes code and results with R Markdown
  • Uses Git to version both source code and results
• Reproducible
  • Displays the code version used to create each result
  • Runs each analysis in an isolated R session
  • Records the session information of each analysis
  • Sets the same seed for random number generation for each analysis
• Shareable
  • Creates a website to present your research results
  • Documents how to host your website for free via GitHub Pages or
    GitLab Pages
  • Creates links to past versions of results

To see a workflowr website in action, see this video demonstration.

For related tools, see r-project-workflows.

Installation

1. Install R

   • (Recommended) Install RStudio

   • (Optional) Install pandoc (Instructions)

   • (Optional) Install Git

2. Install workflowr from CRAN:

   install.packages(\"workflowr\")

3. Create an account on GitHub or GitLab

Quick start

library(\"workflowr\")

# Configure Git (only need to do once per computer)
wflow_git_config(user.name = \"Full Name\", user.email = \"email@domain\")

# Start a new workflowr project
wflow_start(\"myproject\")

# Build the site
wflow_build()

# Customize your site!
#   1. Edit the R Markdown files in analysis/
#   2. Edit the theme and layout in analysis/_site.yml
#   3. Add new or copy existing R Markdown files to analysis/

# Preview your changes
wflow_build()

# Publish the site, i.e. version the source code and HTML results
wflow_publish(\"analysis/*\", \"Start my new project\")

Next steps:

1. Read the full Getting started vignette to learn how to share
   your results online. Alternatively, you could read the Reproducible research
   workshop vignette. It covers the same steps, but includes example
   code and data to demonstrate some of workflowr\’s reproducibility features

2. Read the customization vignette for ideas on how to customize
   your research website

3. Read the migrating vignette for how to integrate workflowr
   into your existing project

Attribution

Workflowr was developed, and is maintained, by John Blischak, a postdoctoral
researcher in the laboratory of Matthew Stephens at The University
of Chicago. He is funded by a grant from the Gordon and Betty Moore
Foundation to MS. Peter Carbonetto and Matthew
Stephens are co-authors.

We are very thankful to workflowr contributors for helping improve the
package. We are also grateful for workflowr users for testing the package and
providing feedback—thanks especially to Lei Sun, Xiang
Zhu, Wei Wang, and other members (past and present) of
the Stephens lab.

The workflowr package uses many great open source packages. Especially critical
for this project are the R packages git2r, knitr, and rmarkdown.
Please see the vignette How the workflowr package works to learn
about the software that makes workflowr possible.

Workflowr is available under the MIT license. For proper attribution,
please cite our manuscript that describes the software:

Blischak JD, Carbonetto P, and Stephens M. Creating and sharing reproducible
research code the workflowr way [version 1; peer review: 3 approved].
F1000Research 2019, 8:1749 (https://doi**.or*g/10.12688/f1000research.20843.1)

To obtain a BibTeX entry, please run citation(\"workflowr\"). Note that
F1000Research publishes not only the original version but also any revisions. To
check for the latest version, please go to the paper\’s URL.

Contributing

We welcome community contributions, especially improvements to documentation. To
get started, please read the contributing guidelines.
Also, please note that this project is released with a Contributor Code of
Conduct. By participating in this project you agree to
abide by its terms.