- You have code that you want to share with others
- Bundling your code into a package makes it easy for other people to use it
- If R code is in a package, any R user can easily download it, install it, and learn how to use it.
May 22, 2015
Seriously, it doesn't have to be about sharing your code (although that is an added benefit!). It is about saving yourself time. - Hilary Parker
Conventions are helpful because:
Hadley Wickham, R packages
You can see the vignette for a specific package by using
Sometimes if a package has many vignettes they are connected into a website
knitrstyles and templates
knitr package offers a vide variety of vignettes' templates
If you're thinking without writing, you only think you're thinking. - Leslie Lamport.
Literate programming is an approach to programming introduced by Donald Knuth in which a program is given as an explanation of the program logic in a natural language, such as English, interspersed with snippets of macros and traditional source code, from which a compilable source code can be generated.
Interestingly, the most popular application of the LP paradigm seems to be documenting software (using a special form of comments) for users instead of “programming” for authors. In other words, we use LP to document the usage of software, instead of documenting the source code.
In literate programming code is embedded in documentation, with the code following the structure of the documentation.
LP has at least two advantages: http://yihui.name/rlp/
install.packages( c("roxygen2", "Rd2roxygen", "rlp") ) devtools::install_github("yihui/rlp") update.packages( type = "source", repos = "http://yihui.name/xran") )
purl=Rscript -e "knitr::purl('$(1)', '$(2)', quiet=TRUE, documentation=0)" rfiles:=$(patsubst vignettes/LP-%.Rmd,R/%-GEN.R,$(wildcard vignettes/LP-*.Rmd)) all: $(rfiles) R/%-GEN.R: vignettes/LP-%.Rmd $(call purl,$^,$@)
Now we have three things to do to fully build this package:
roxygen2to generate R documentation to
NAMESPACE, and other stuff;
R CMD buildto build the package as well as the vignettes.
Want to do this in 1 click?
I have been secretly hacking the Build & Reload button in my RStudio IDE for a long time.
If you open RStudio, and go to
Project Options ->
Build Tools, you will need to specify a weird configuration:
-v && Rscript -e "Rd2roxygen::rab(install=TRUE, before=system('make'))"
Let's practise LP-like package development on
extremeMetrics package which is an
Extreme and incredibly crazy set of metrics.
vignettesdirectory with an implementation of an incredibly crazy metric function. The more
LaTeXcode, plots and images - the better!