Gaston Sanchez www.gastonsanchez.com Creating an R package? What many of us go through f(T) = g(T, T) g(T, W) = tr(T' A(w) T) g(T, W) < h(T, W) Maximize tr(T' A(w) T) T' T = 1 revolutionary breakthrough, statistical method # core function fun_xy <- function(x, y) { n = nrow(x) p = ncol(x) q = ncol(y) mx = rowMeans(x) my = rowMeans(y) z = t(x) %*% y ... lots of functions and scripts Very Fancy Method for Analyzing and Visualizing Multivariate Data Your Name a,b , Graduate Student b , Intern Student b a Renowned Statistical Research Center b Department of Stuffmetrics and Computational Methods, Famous School (Pretty City) Abstract This paper depicts a new methodology devoted to analyze complex data generated from extremely expensive experiments in the field of Stuffmetrics. The ultimate goal is to bla, bla, bla One or more publications Dear colleague, Thank you for your deep interest in the super cool method that I've been working on for so many years. Unfortunately, I haven't had the time to implement any software. I'll let you know when I launch it. white lie Re: software request To: your.colleague@email.com People ask you for software, BUT... Dear colleague, Thank you for your deep interest in the super cool method that I've been working on for so many years. Unfortunately, I haven't had the time to implement any software. I'll let you know when I launch it. white lie Re: software request To: your.colleague@email.com L e t ' s
m a k e
i t
h a p p e n People ask you for software, BUT... Dear colleague, I finally found some time to implement an R package for my super cool method. You can now find "myawesomepkg" on CRAN: http://cran.r-project.org/web/packages/myawesomepkg/index.html white lie Subject: launching myawesomepkg Hopefully after finishing this workshop (and many working hours later) ... To: your.colleague@email.com useRs & creatoRs u s e R c r e a t o R useRs creatoRs package? So you want to create an You should know upfront (Getty Images / Robert Gray) ... for the first time? (Getty Images / Robert Gray) in Windows? (Getty Images / Robert Gray) Let's do it! x x x x x x G a m e
P l a n x 1 Setting up your PC 2 Anatomy of an R package 3 Standard -painful- Development 4 Building and Checking 5 Develop smarter, not harder Caveat learning R programming in R debugging your code writing more efficient code These slides are NOT about: There is more than one way to create an R package There's a learning curve to create R packages Windows is badly equipped for creating R packages 1 Setting up your PC 2 Anatomy of an R package 3 Standard -painful- Development 4 Building and Checking 5 Develop smarter, not harder Installing some stuff R http://www.r-project.org/ Rtools http://cran.r-project.org/bin/windows/Rtools/ Latex compiler (eg MiKTeX) http://miktex.org/download or http://www.tug.org/protext/ FTP Client (eg FileZilla) https://filezilla-project.org/ RStudio (strongly recommended) http://www.rstudio.com/ide/download/ Stuff you need to install Windows 7 Professional (2009) R-3.0.1 for Windows Rtools30.exe (R >2.15.1 to R 3.0.x) MiKTeX 2.9 RStudio 0.97.551 - Windows Xp/Vista/7 For this workshop I'm using: Modify your system's PATH After downloading and installing all the necessary software, you need to modify the PATH of your PC's system Meet the Windows command prompt (aka MS-DOS prompt) How to open the command prompt? Start Programs Accessories Command Prompt Comment lancer l'invite de commandes? Dmarrer Tous les programmes Accessoires Invite de commandes Type PATH in your command prompt This is the PATH (yours will be different) 1 2 One way to get your PATH 3 4 6 7 8 Here's the PATH (copy-and-paste it in a text editor) 5 c:\Rtools\bin;c:\Rtools\gcc-4.6.3\bin;c:\Program Files (x86)\Intel\iCLS Client\;c:\Program Files\Intel\iCLS Client\;C:\Windows\system32;C:\Windows;C: \Windows\System32\Wbem;C: \Windows\System32\WindowsPowerShell\v1.0\;C:\Program Files\Intel\Intel(R) Management Engine Components\DAL;C: \Program Files\Intel\Intel(R) Management Engine Components\IPT;C:\Program Files (x86)\Intel\Intel(R) Management Engine Components\DAL;C:\Program Files (x86) \Intel\Intel(R) Management Engine Components\IPT;c: \Program Files (x86)\Hewlett-Packard\HP ProtectTools Security Manager\Bin\ Checking the PATH PATH example (one single text line!) C:\Rtools\bin; C:\Rtools\gcc-4.6.3; C:\Program Files\R\R-3.0.1\bin; C:\Program Files\MiKTeX 2.9\miktex\bin\x64\; You MUST add these in your PATH: My PATH (one single text line!) Modifying the PATH c:\Rtools\bin;c:\Rtools\gcc-4.6.3\bin;C:\Program Files\R\R-3.0.1\bin;C:\Program Files\MiKTeX 2.9 \miktex\bin\x64\;c:\Program Files (x86)\Intel\iCLS Client\;c:\Program Files\Intel\iCLS Client\;C: \Windows\system32;C:\Windows;C:\Windows\System32\Wbem;C: \Windows\System32\WindowsPowerShell\v1.0\;C:\Program Files\Intel\Intel(R) Management Engine Components\DAL;C: \Program Files\Intel\Intel(R) Management Engine Components\IPT;C:\Program Files (x86)\Intel\Intel(R) Management Engine Components\DAL;C:\Program Files (x86) \Intel\Intel(R) Management Engine Components\IPT;c: \Program Files (x86)\Hewlett-Packard\HP ProtectTools Security Manager\Bin\; Test the PATH gcc --help TeX --help R CMD --help Type the following commands in the command prompt: If you get error messages, check your PATH again If you don't get errors... you're all set to go! Check that all works Anatomy of an R package Before jumping into the creation process, you need to learn how an R package is structured Download and open the tar file to check the package structure "plyr" CRAN page (repository) A set of text files (with no extension) A set of subdirectories You can also check the guts of plyr in its github repository. Recommendation: A good way to learn about the structure of R packages is to check those that are available in github There are some additional -not relevant- files These are the important files and subdirectories that form the structure of "plyr" What's in an R package? DESCRIPTION NAMESPACE NEWS README LICENSE INDEX R man data inst tests src demo subdirectories (ie folders) text files (no extension) DESCRIPTION NAMESPACE NEWS README LICENSE INDEX R man data inst tests src demo subdirectories (ie folders) text files (no extension) required optional DESCRIPTION NAMESPACE NEWS README LICENSE INDEX R man data inst tests src demo subdirectories (ie folders) text files (no extension) W h a t ' s t h e m e a n in g &
p u r p o s e o f a ll t h e s e f ile s
a n d s u b d ir e c t o r ie s ? R technical documentation Technical Documentation! http://cran.r-project.org/manuals.pdf An Introduction to R R Data Import / Export R Installation and Administration Writing R Extensions The R Language Definition R Internals Official Manuals (R Development Core Team) http://cran.r-project.org/manuals.html An Introduction to R R Data Import / Export R Installation and Administration Writing R Extensions The R Language Definition R Internals Official Manuals (R Development Core Team) Good News =) Everything is here Bad News =( Not beginner friendly Sooner or later you will have to read this ... and more (text) Files DESCRIPTION NAMESPACE NEWS README LICENSE INDEX R man data inst tests src demo subdirectories (ie folders) text files (no extension) DESCRIPTION Package: pkgname Version: 1.0.0 Date: 2013-06-01 Title: Toy package Author: Your Name <your.email@address.com> Maintainer: Your Name <your.email@address.com> Depends: R (>= 2.15), somepackage Suggests: otherpackage Description: This is a toy package License: GPL-3 URL: http://www.toypackage.com LazyData: true This is your package's business card R Licenses? The "GNU Affero General Public License" version 3 The "Artistic License" version 2.0 The "BSD 2-clause License" The "BSD 3-clause License" The "GNU General Public License" version 2 The "GNU General Public License" version 3 The "GNU Library General Public License" version 2 The "GNU Lesser General Public License" version 2.1 The "GNU Lesser General Public License" version 3 The "MIT License" http://www.r-project.org/Licenses/ NAMESPACE export(my_function1) export(my_function2) export(my_function3) S3method(print, class1) S3method(print, class2) S3method(plot, class3) import(package_A) importFrom(package_B, function_b1) useDynLib(C_code) NAMESPACE export(my_function1) export(my_function2) export(my_function3) S3method(print, class1) S3method(print, class2) S3method(plot, class3) import(package_A) importFrom(package_B, function_b1) useDynLib(C_code) These are your documented functions NAMESPACE export(my_function1) export(my_function2) export(my_function3) S3method(print, class1) S3method(print, class2) S3method(plot, class3) import(package_A) importFrom(package_B, function_b1) useDynLib(C_code) S3 methods for your S3 classes NAMESPACE export(my_function1) export(my_function2) export(my_function3) S3method(print, class1) S3method(print, class2) S3method(plot, class3) import(package_A) importFrom(package_B, function_b1) useDynLib(C_code) If you are using stuff from other packages NAMESPACE export(my_function1) export(my_function2) export(my_function3) S3method(print, class1) S3method(print, class2) S3method(plot, class3) import(package_A) importFrom(package_B, function_b1) useDynLib(C_code) If you have code in other languages (C, C++, Fortran) NAMESPACE export(my_function1) export(my_function2) export(my_function3) S3method(print, class1) S3method(print, class2) S3method(plot, class3) import(package_A) importFrom(package_B, function_b1) useDynLib(C_code) How R searches and finds stuff? With NAMESPACE's http://obeautifulcode.com/R/How-R-Searches-And-Finds-Stuff/ (by Suraj Gupta) f o r m o re in f o : README Toy Package This package is just an example of a toy package. It offers several dummy functions
Bla, bla, bla This workshop is so boring! Optional README file (ignored by R but useful for readers) NEWS Version 0.2 ------------------------------------------------------------------------- NEW FEATURES * created new functions fun1() and fun2(), which operate with vectors. BUG FIXES * fixed bug in bad_function(). Now can be successfully applied. Version 0.1 ------------------------------------------------------------------------- NEW FEATURES * added new parameter 'time' in function boring()
* added a plot method * user can specify several input files Optional NEWS file (helps for keeping track of changes) LICENSE This package is distributed under the XYZ license at http://www.xyz.org/publications/policies/software. In detail: 1. Fortran code (src/*.f): Copyrighted and Licensed by XYZ, 2. R interface (src/init.c src/cooler.h R/*.R man/*.Rd data/*): The R interface code has been developed as work based on the XYZ licensed code, hence it is also XYZ licensed, copyright is by Some Guy <some.guy@email.com>. In order to fulfill the XYZ copyright and license noted above, it is stated here that this work contains modified XYZ material, and to fulfill this, the modified work including the R interface is available free to secondary users, and no charge is associated with such copies. Optional LICENSE file with additional terms when a package license restricts a base license Subdirectories DESCRIPTION NAMESPACE NEWS README LICENSE INDEX R man data inst tests src demo subdirectories (ie folders) text files (no extension) Let's go back to the package plyr example Package Subdirectories Most important subdirectory This is where all the R functions live For example, let's check the function a_ply Another example with function r_ply use this if you have data files files you wish an end user to see manual (help) documentation for the package functions folder for files with code in C, C++, Fortran folder for files testing your code Writing R documentation (Getty Images / Gary Robert) Writing .Rd files? Probably the worst part about creating a package manual (help) documentation for the package functions manual (help) documentation for the package functions a_ply.Rd Rd file for function a_ply a_ply.Rd Rd file for function a_ply (cont) Remember the Official M anual "W riting R Extensions"