How to submit a new protocol

This protocol template was contributed by L. Collado-Torres.

Overview

At Leek group we have a diverse group of members with expertise in different areas. To make it easier for others in the group to accomplish some recurrent tasks, Jeff loves it when members of the group write a short protocol for others to follow. This document is a short guide on how to submit a new protocol.

Introduction

The first thing you should know is that this website is version controlled by git and hosted at GitHub. Learning how to use git is a bit outside the scope of this protocol. However, to start

GitHub is pretty cool because it automatically serves HTML documents that are in a gh-pages branch. GitHub Pages shows how to create one such website from scratch. In this case, we have already created the protocols repository and its main branch is gh-pages. That means, that all HTML files in the repository can be seen live at jtleek.com/protocols.

We organize the protocols by creating a new directory for each protocol and including a index.html inside of them. For example, we have a protocol about testing packages with Travis which lives at protocols/travis_bioc_devel/index.html and can be seen at jtleek.com/protocols/travis_bioc_devel/.

In order to create the HTML files without much work from our side, we use R Markdown via the rmarkdown package (Allaire, Cheng, Xie, McPherson, et al., 2015). You might want to check this short presentation I made covering the basics of R Markdown. R Markdown uses Markdown syntax (see basics here) and allows you to embed R code with its results. Another cool feature, is that R Markdown uses Pandoc behind the scenes which takes Markdown files and creates HTMLs, PDFs, Word documents, etc. What we care about in this case are the HTML files.

Instructions

Know what we have covered the basics, lets gets started.

For more information about pull requests, check creating a pull request.

You might be interested in exploring how some of the other protocols were made before contributing yours.

Code

Here is some code, assuming that you have created the fork and are under Linux or Mac OS.

## Enter your favorit directory
$ cd my_code_directory

## Cloene your fork (ssh, there's also https if you want)
$ git clone git@github.com:yourGithub/protocols.git

## Enter the main directory
$ cd protocols

## Copy the template directory and rename it
$ cp -R protocol_template my_protocol

## Open the protocol index file and edit it
$ open my_protocol/index.Rmd
## Edit the file, then save it

## Render the html version, if you have the packages installed
$ Rscript -e "rmarkdown::render('my_procotol/index.Rmd')"

## Open the main index and add a link to your protocol
$ open index.Rmd
## Once you added the link, save the file.

## Render the html version of the main index.
$ Rscript -e "rmardown::render('index.Rmd')"

## Add all the files
$ git add index.Rmd index.html my_protocol/*

## Make the commit and describe the new protocol
$ git ci -am "Contributing a new protocol about abcdefg"

## Push them to your fork
$ git push

## Complete the pull request at Github.com

More than one

Note that if your pull request got accepted and some days/weeks/months/years later you want to submit a second protocol, you will need to sync your fork with the main repository before making changes. Follow the instruction at syncing a fork.

Some details

The file protocols/procotol_template/index.Rmd suggests using

  • devtools (Wickham and Chang, 2015) for the session information. It’s the most precise one when you have installed GitHub packages.
  • knitcitations (Boettiger, 2015) for creating citations and the corresponding bibliography.
  • knitrBootstrap (Hester, 2014) for formatting the HTML file. It’s specially useful if your protocol includes R code. However, at the time of writing this protocol, the best version is only available at GitHub. You can install it via devtools::install_github('jimhester/knitrBootstrap').

References

[1] J. Allaire, J. Cheng, Y. Xie, J. McPherson, et al. rmarkdown: Dynamic Documents for R. R package version 0.7. 2015. URL: http://CRAN.R-project.org/package=rmarkdown.

[2] C. Boettiger. knitcitations: Citations for Knitr Markdown Files. R package version 1.0.6. 2015. URL: http://CRAN.R-project.org/package=knitcitations.

[3] J. Hester. knitrBootstrap: Knitr Bootstrap framework. R package version 1.0.0. 2014. URL: https://github.com/jimhester/.

[4] H. Wickham and W. Chang. devtools: Tools to Make Developing R Packages Easier. R package version 1.8.0. 2015. URL: http://CRAN.R-project.org/package=devtools.

Date this protocol was last modified: 2015-06-22 16:59:20.