class: center, middle, inverse, title-slide # Project organisation & documentation ## 🗄
with workflowr ### Anna Krystalli (
@annakrystalli
) ### 2017/11/07
Sheffield R Users --- # outline ## Demo of **John Blischak's** ([@jdblischak](https://twitter.com/jdblischak)) awesome [`workflowr`](https://jdblischak.github.io/workflowr/index.html) package - background - demo of setting up a new project - demo of a populated project --- background-image: url(http://www.deucecitieshenhouse.com/images/2015/08.31/6.jpg) background-size: cover class: left, top, inverse # **Motivation: Tidy projects** - ## **Project organisation** - ## **Project management** - ## **Project documentation** --- # Project organisation - Encourages tidy practices (more at **Data Carpentry** [**File Organisation**](http://www.datacarpentry.org/rr-organization1/) lesson) ![](http://www.deucecitieshenhouse.com/images/2015/08.31/garage.gif) --- # A sensible starting file system setup ![](workflowr-pres_files/figure-html/file-system.png) --- # Customisable ### ** DO NOT TOUCH!** Project site depends on the following files: - **`analysis/`** - **`docs/`** - **`.Rproj` file** ### **Everything is else is game** <br> Adapt to suit your own project organisation needs/preferences --- # Project management ### buildis on **Git & GitHub version control system** - great for keeping track of changes through time - great for planning and discussing - great for collaboration --- # Project documentation Building on `knitr` & `rmarkdown` - Analyses documented in `.Rmd` and kept in **`analysis/`** dir ### Encourages literate programming: ie **making your analyses (your code, inputs and outputs) understandable to humans** - code can still be stored separately in dir **`code/`** and either: - **sourced** using **`source(code/script.R)`** - **read in** using **`read_chunk(code/script.R)`** and called using the chunk name --- # Project website - Share documentation easily on the web! - Develop content in `.Rmd` documents in the **`analysis/`** dir - `Rmd` automatically rendered to `html` in the **`docs/`** dir - When pushed to github [**`docs/` can be set as the publishing source for gh-pages**](https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/#publishing-your-github-pages-site-from-a-docs-folder-on-your-master-branch) folder --- # Elements of the website ### **_site.yml:** a master yaml header for the whole site - change the theme - modify the structure of the site `index` banner - modify the table of contents ### **index.Rmd** - landing page for the project - add links to further analysis pages here --- # Elements of the website ### **about.Rmd** - used to provide a description of yourself / your group ### **license.Rmd** - very important to include an appropriate license [(quick guide)](http://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1002598) ### **license.Rmd** - important for correct attribution and citation of your code (consider getting a DOI) <br> Again, customisable through **adding pages** and updating the **`_site.yml`** --- # Elements of an analysis page Begins with an **`.Rmd` template** <img src="workflowr-pres_files/figure-html/tmpl-chunks.png" width="450" > --- # Elements of an analysis page Calls default chunks in **`analysis/chunks.R`** using `knitr::read_chunk(chunks.R)` <img src="workflowr-pres_files/figure-html/chunk.png" width="450" > --- class: center, center, inverse # Key functions --- # Start a new project # [Before you start!](https://jdblischak.github.io/workflowr/index.html) **Requirements:** Need : - R (ideally also RStudio) installed - [Git installed](https://swcarpentry.github.io/workshop-template/#git) + GitHub account created - package **`workflowr`** installed - set the Git variables `user.name` and `user.email` to your **GitHub user name** and **login email** ``` git config --global user.name "your-github-username" git config --global user.email "youremail@domain" ``` (you can run `git config -l` in the shell to confirm). --- ## start a new `workflowr` project ```r wflow_start("path-to-project/name-of-project") ``` - creates directories and templates - initialises git <br> *TIP: Head to the project folder in Rstudio projects at this point, nicer to work from there* --- # build and view your project website ### build site ```r wflow_build() ``` ### view site ```r wflow_view() ``` --- # check status of site tracks unpublished and changes to published `.Rmd`s ```r wflow_status() ``` --- # publish your site ```r wflow_publish(c("analysis/index.Rmd", "analysis/about.Rmd", "analysis/license.Rmd"), "Publish the initial files for project") ``` ### 3 steps in the process: - **Step 1: Commits the 3 R Markdown files** using the custom commit message - **Step 2: Builds the HTML files** using `wflow_build()` - **Step 3: Commits the 3 HTML files** plus the files that specify the style of the website (e.g. CSS and Javascript files) Performing these 3 steps **ensures that the HTML files are always in sync with the latest versions of the R Markdown files**. --- # deploy site ## First link your local repository to a remote repository on github - **log into github** - **create a repository** ([instructions](https://help.github.com/articles/creating-a-new-repository/)) - *do not add an automatically-generated README, .gitignore, or license as `workflowr` has already taken care of that.* - In the terminal run: ``` git remote add origin https://github.com/myname/myproject.git ``` ## push your changes up to GitHub ``` git push -u origin master ``` --- # add a new analysis file ```r wflow_open("first-analysis.Rmd") ``` ### Does 3 things: - Creates a new file `analysis/first-analysis.Rmd` based on the workflowr R Markdown template (it doesn’t overwrite the file if it already exists) - Sets the working directory to the `analysis/` directory - If you are using RStudio, opens the file for editing --- class: center, middle, inverse # Examples in the wild: .left[ - live demo ([vignette](http://annakrystalli.me/workflowr-demo/files/workflowr-vignette.nb.html)) - populated [example](https://github.com/annakrystalli/news-scrape)] --- class: center, middle, inverse # Questions? <br> .left[presentation @ <br> http://annakrystalli.me/workflowr-demo/presentation/workflowr-pres.html] <br> .footnote[**github:** [@annakrystalli](https://github.com/annakrystalli) <br> **twitter:** [@annakrystalli](https://twitter.com/annakrystalli)]