Contributing to the LIBD rstats club
In this blog post Leonardo Collado-Torres explains how to contribute posts to the LIBD rstats club. While some parameters are specific to this blog, you could also use this for creating your own community blog.
Install necessary tools
We first need to get the appropriate tools installed in our computer.
1. R
Lets start by installing the latest version of R. At the time of writing this post, that would be R 3.4.3 but in reality this should work with any R 3.4.x version. It might even work with earlier versions, but it’d be a bummer to find out that we have an R version problem later on.
2. RStudio
Once we have an up to date R version, lets install RStudio. By using the latest version we will have access to RStudio addin menus, which will make our life much easier. Since we will be using RStudio quite a bit, it’s best to work from your laptop/computer than any server or cluster where you might not have the flexibility to install/update RStudio and R.
3. blogdown
We next need to install the main package that we will be using for creating our blog posts, that is blogdown (Xie, Hill, and Thomas, 2017). At the time of writing this post, the version that we need to use is only available in the development branch. So we need to install blogdown via devtools (Wickham, Hester, and Chang, 2018).
## If needed install devtools first:
install.packages('devtools')
## Install development version
devtools::install_github('rstudio/blogdown')
## If you are reading this in the fiture, you might only need
install.packages('blogdown')At some point we might need two other extra packages that blogdown uses. It will show you a message when that happens, so you can install them when you need them or you could go ahead and get them anyway.
install.packages(c('later', 'processx'))4. hugo
We are almost there! blogdown uses hugo which they claim is the world’s fastest framework for building websites. hugo is a bit complicated, but it makes maintaining a complicated website such as a blog super easy. Basically, we will be working in the rstatsclubsource directory and hugo will create the final version we can share around in the directory rstatsclubsource/public.
Ok, lets go head and install it with
blogdown::install_hugo()5. git
To get the files and interact with other LIBD rstats club members you will need to use git, which you can install following these instructions from the happygitwithr website. A note for Windows users: get git for windows because it includes git bash and will enable you to run some commands that we will need later on. Even more advanced for Windows users, when installing git bash choose the use git and optional Unix tools from the Windows Command Prompt as described in detail here.
Also get a GitHub account if you don’t have one already. Optionally set up ssh keys for password-less login, though it’s not needed.
Access blog source files
The file structure of our blog involves a total of 3 GitHub repositories that are related to each other as shown below. However, you will only need to interact with one of them.
rstatsclubsource
## From https://github.com/LieberInstitute/rstatsclubsource
content/
post/
...
static/
post/
img/
...
themes/
hugo-academic/
## From https://github.com/gcushen/hugo-academic
## linked as a git submodule
public/
## https://github.com/LieberInstitute/rstatsclub
## Hosts the files that make up the website
## http://LieberInstitute.github.io/rstatsclub/The main directory for the blog is rstatsclubsource and you can access it at github.com/LieberInstitute/rstatsclubsource if you are a member of the LIBD rstats club and have logged in to your GitHub account. This directory contains many files that blogdown understands and that you don’t really need to change. The main sub-directory that you will be interacting with is rstatsclubsource/content/post where your new post files will get saved by blogdown. If you insert images, blogdown will automatically create the directory rstatsclubsource/static/post/2018-03-09_postTitle_files (example), but don’t worry about it.
Ok, lets get the files. Open your terminal or git bash (Windows) and navigate to the directory where you will store your copy of the source files.
## Works in Mac and Windows (with git bash)
cd ~/Desktop
## Windows example command if you have more than 1 disk
cd /f/DesktopNext clone github.com/LieberInstitute/rstatsclubsource. Here we use https since that doesn’t require extra setup, but cloning by ssh also works.
git clone https://github.com/LieberInstitute/rstatsclubsource.git
After a successful clone, we should have created the directory ~/Desktop/rstatsclubsource. Lets change to this new directory.
cd rstatsclubsourceOur cloning process also created a placeholder for our hugo theme (hugo-academic) but it’s contents are empty.
$ ls -lh themes/hugo-academic/
total 0Lets fill them up by running the following git command.
git submodule update --init --recursive
If we now check the contents of the themes/hugo-academic directory we should see several files now (here’s a screenshot from Windows using git bash).
ls -lh themes/hugo-academic
Preview website
Our setup is now complete! We can now start writing blog posts using blogdown. Open the ~/Desktop/rstatsclubsource/rstatsclubsource.Rproj file, which should open a new RStudio window automatically. Find the Addins menu on the top of your window, and select the Serve Site option in the drop-down menu.
This addin will create a local version of the website you can preview in the RStudio Viewer pane.
If you click in the show in new window symbol as shown below
you then can preview the website in your main browser:
This will be super useful when you are writing a new blog post because any changes you make will automatically refresh the local preview version after a second of two (only after you save the file you are editing). Sometimes you might have to manually refresh your browser (like when you make too many updates in a row). The preview website works as long as you have the Serve Site addin running on the background.
All our files
By running Serve Site blogdown actually populated automatically our rstatsclubsource/public directory. So our full list of files look somewhat like this:
## Found about tree from
## https://stackoverflow.com/questions/3455625/linux-command-to-print-directory-structure-in-the-form-of-a-tree
## Intall in a Mac with homebrew:
## brew install tree
$ tree -d rstatsclubsource
.
├── archetypes
├── content
│ ├── home
│ └── post
├── data
│ ├── fonts
│ └── themes
├── layouts
│ └── partials
├── public
│ ├── 2018
│ │ └── 03
│ │ ├── 06
│ │ │ └── test-post-for-checking-website
│ │ └── 09
│ │ └── welcome-to-the-libd-rstats-club
│ ├── categories
│ │ ├── page
│ │ │ └── 1
│ │ ├── rstats
│ │ │ └── page
│ │ │ └── 1
│ │ └── setup
│ │ └── page
│ │ └── 1
│ ├── home
│ ├── img
│ ├── js
│ ├── post
│ │ ├── 2018-03-06-test-post-for-checking-website_files
│ │ │ └── figure-html
│ │ └── page
│ │ └── 1
│ ├── publication_types
│ │ └── page
│ │ └── 1
│ └── tags
│ ├── blog
│ │ └── page
│ │ └── 1
│ └── page
│ └── 1
├── static
│ ├── img
│ └── post
│ └── 2018-03-06-test-post-for-checking-website_files
│ └── figure-html
└── themes
└── hugo-academic
├── archetypes
├── data
├── exampleSite
├── i18n
├── images
├── layouts
└── staticSome of the structure looks redundant right? Well, that’s because hugo and blogdown tried to keep everything super organized and re-use some of the file structure for the final version of the website (the one inside rstatsclubsource/public).
Write a blog post
We now have a working full preview version of the website in our computer. It’s finally time to write a blog post. The good thing is that we don’t need to do all the setup steps again!
Update if necessary
If you paused midway for a few days, it’s likely that your files are not the latest ones. So please git pull the latest files from github.com/LieberInstitute/rstatsclubsource.
cd ~/Desktop/rstatsclubsource
git pullStart a blog post
To start a new blog post, use the New Post blogdown addin.
This will open up a window where you can specify the blog post title. The title will automatically fill out the slug which is used in the final URL of the post. It also lets you choose a date, when is when the blog post will be made publicly visible.
Author and extension
Lets start by entering the author information (leave blank if you want it to be anonymous) and selecting the post format. We highly recommend you use the .Rmd format for your blog posts, even to the point that you should just make it our default option. To do so you have to edit/create an .Rprofile file in your computer at your home directory, that is ~/.Rprofile. Then use these options (with how you prefer the author information to be).
# https://bookdown.org/yihui/blogdown/global-options.html
options(blogdown.author = 'L. Collado-Torres')
options(blogdown.ext = '.Rmd')The next time you write a blog post, blogdown will know what options you prefer.
Use a blog template
Next lets choose the blog archetype (template) that for posts, that is post under Archetype.
The reasons why a blog template is useful are described in full detail in this blog post by L. Collado-Torres. The quick version is that it will pre-populate your new blog post with helpful information and reminders on how to do \(X\) or \(Y\). For example, how to insert external images, how to control the figure height and width for images generated by R, how to cite packages, and including the R reproducibility information by default.
Use appropriate post categories
Most of our blog posts will likely be about R. For those blog posts, select the rstats category as shown below.
If your blog post covers a topic that might be useful to new LIBD members use the setup category. If it involves using the JHPCE cluster, use jhpce as a category, etc. The New Post blogdown addin lets you see which categories and tags have been used before to classify posts. In general, we should aim to have a handful of categories while having as many tags as necessary. These will be useful for filtering our blog posts.
Hit done! (well check before)
We are now basically set to start our new blog post. Just double check:
- the categories,
- that the format is
.Rmd, - that the archetype is
post, - post title,
- post date,
- post author.
Aaaaand hit done!
Edit your blog post
You can now write your blog post using the R Markdown syntax. Note that you won’t be using the knit button from RStudio since the Serve Site blogdown addin should be doing all the work for you and updating your local website preview.
When writing your blog post keep in mind our Code of Conduct and that your our blog posts have to comply with the confidentiality agreement we signed at LIBD.
Share your blog post
Once you are happy with the final version of your blog post and have used the spell check from RStudio, add your blog post files to github.com/LieberInstitute/rstatsclubsource. First, remember to git pull in case that there are new files in the repository that you don’t have. Next check which files you modified by running git status
cd ~/Desktop/rstatsclubsource
git statusTypically, you should see that you have untracked files under rstatsclubsource/content/post and maybe rstatsclubsource/static/post/. If so, add them to the github repository with the following sequence of commands.
git add content/post/*
git add static/post/*
git commit -m "Short description of your new blog post"
git pushYou could also do this with a git GUI such as the git tools in RStudio, SourceTree (works for both Mac and Windows), the gitk command, etc.
After a quick review we will update the files at github.com/LieberInstitute/rstatsclub and deploy the changes to GitHub.
Good luck with your first of many blogdown posts!!!
Details
We are keeping both github.com/LieberInstitute/rstatsclubsource and github.com/LieberInstitute/rstatsclub as private repositories to enable contributors to write posts anonymously.
The default license for our blog posts is (CC) BY-NC-SA 4.0 which you can read more about here. If you write a blog post under a different license, please make it clear. Also please attribute the sources of the material you use.
Further reading
If you want to learn even more, check the blogdown book and the hugo-academic theme. Maybe you can help with this currently unresolved issue.
If you want to check a public version equivalent to the one described here, check:
- github.com/lcolladotor/hugoblog which is the equivalent of github.com/LieberInstitute/rstatsclubsource
- github.com/lcolladotor/lcolladotor.github.com which is the equivalent of github.com/LieberInstitute/rstatsclub
hugoblog
## From https://github.com/lcolladotor/hugoblog
content/
post/
...
static/
post/
img/
...
themes/
hugo-academic/
## From https://github.com/gcushen/hugo-academic
## linked as a git submodule
public/
## https://github.com/lcolladotor/lcolladotor.github.com
## Hosts the files that make up the website
## http://lcolladotor.github.io/Acknowledgments
This blog post was made possible thanks to:
References
[1] C. Boettiger. knitcitations: Citations for ‘Knitr’ Markdown Files. R package version 1.0.8. 2017. URL: https://CRAN.R-project.org/package=knitcitations.
[2] A. Oleś, M. Morgan and W. Huber. BiocStyle: Standard styles for vignettes and other Bioconductor documents. R package version 2.6.1. 2017. URL: https://github.com/Bioconductor/BiocStyle.
[3] H. Wickham, J. Hester and W. Chang. devtools: Tools to Make Developing R Packages Easier. R package version 1.13.5. 2018. URL: https://CRAN.R-project.org/package=devtools.
[4] Y. Xie, A. P. Hill and A. Thomas. blogdown: Creating Websites with R Markdown. ISBN 978-0815363729. Boca Raton, Florida: Chapman and Hall/CRC, 2017. URL: https://github.com/rstudio/blogdown.
Reproducibility
## Session info ----------------------------------------------------------------------------------------------------------## setting value
## version R version 3.4.3 (2017-11-30)
## system x86_64, darwin15.6.0
## ui X11
## language (EN)
## collate en_US.UTF-8
## tz America/New_York
## date 2018-03-10## Packages --------------------------------------------------------------------------------------------------------------## package * version date source
## backports 1.1.2 2017-12-13 CRAN (R 3.4.3)
## base * 3.4.3 2017-12-07 local
## bibtex 0.4.2 2017-06-30 CRAN (R 3.4.1)
## BiocStyle * 2.6.1 2017-11-30 Bioconductor
## blogdown 0.5.9 2018-03-08 Github (rstudio/blogdown@dc1f41c)
## bookdown 0.7 2018-02-18 cran (@0.7)
## colorout * 1.2-0 2018-02-19 Github (jalvesaq/colorout@2f01173)
## compiler 3.4.3 2017-12-07 local
## datasets * 3.4.3 2017-12-07 local
## devtools * 1.13.5 2018-02-18 CRAN (R 3.4.3)
## digest 0.6.15 2018-01-28 CRAN (R 3.4.3)
## evaluate 0.10.1 2017-06-24 CRAN (R 3.4.1)
## graphics * 3.4.3 2017-12-07 local
## grDevices * 3.4.3 2017-12-07 local
## htmltools 0.3.6 2017-04-28 CRAN (R 3.4.0)
## httr 1.3.1 2017-08-20 CRAN (R 3.4.1)
## jsonlite 1.5 2017-06-01 CRAN (R 3.4.0)
## knitcitations * 1.0.8 2017-07-04 CRAN (R 3.4.1)
## knitr 1.20 2018-02-20 cran (@1.20)
## lubridate 1.7.3 2018-02-27 CRAN (R 3.4.3)
## magrittr 1.5 2014-11-22 CRAN (R 3.4.0)
## memoise 1.1.0 2017-04-21 CRAN (R 3.4.0)
## methods * 3.4.3 2017-12-07 local
## plyr 1.8.4 2016-06-08 CRAN (R 3.4.0)
## R6 2.2.2 2017-06-17 CRAN (R 3.4.0)
## Rcpp 0.12.15 2018-01-20 CRAN (R 3.4.3)
## RefManageR 0.14.20 2017-08-17 CRAN (R 3.4.1)
## rmarkdown 1.9 2018-03-01 cran (@1.9)
## rprojroot 1.3-2 2018-01-03 CRAN (R 3.4.3)
## stats * 3.4.3 2017-12-07 local
## stringi 1.1.6 2017-11-17 CRAN (R 3.4.2)
## stringr 1.3.0 2018-02-19 cran (@1.3.0)
## tools 3.4.3 2017-12-07 local
## utils * 3.4.3 2017-12-07 local
## withr 2.1.1 2017-12-19 CRAN (R 3.4.3)
## xfun 0.1 2018-01-22 CRAN (R 3.4.3)
## xml2 1.2.0 2018-01-24 CRAN (R 3.4.3)
## yaml 2.1.17 2018-02-27 cran (@2.1.17)