Ce post n’existe pas en Français… This post is just “Yet Another Tutorial on Creating R Packages” (on Linux). It should not be seen as a real tutorial, merely as a very short overview on the process of building packages. For more complete tutorials, see

The functions described in this post are used as a simple case example to explain the full process of creating R packages on Linux. As a result, we will obtain this graphical interface

that allows the user to read a CSV file and obtain basic statistics on the numeric variables included in. People (i.e., lazy students) only interested in using this package named “wnaetw” can skip the technical part and directly download the package at the bottom of this page.

Menu

Prepare the package

Start a fresh R session and source all functions that you want to include in the package. You can also include datasets in your package by loading them in the workspace. Once this is done, use the function 

package.skeleton(name="wnaetw")

that will create a folder wnaetw in R working directory. This folder contains everything needed to build a package:

  • a file DESCRIPTION that contains the package description. Edit it to provide information on your package. In particular, the field Maintainer has to be fullfiled with care (and with a valid email address in case you want to use the Windows compiler to build a Windows version of your package). The description file of the package wneatwis: 
    Package: wnaetw
Type: Package
Title: What Nicolas's Teacher Wants
Version: 1.0
Date: 2012-08-31
Author: Nicolas A. Edwards, Arthur Gomez, Jonathan Mahe and Nathalie Villa-Vialaneix
Maintainer: Nathalie Villa-Vialaneix 
Description: This package does what Nicolas's teacher wants with numerical variables. It seems pretty clear with just the title
License: WTFPL (>=2.0)
Depends: e1071, ineq, graphics, stats, RGtk2
SystemRequirements: Cairo (>= 1.0.0), ATK (>= 1.10.0), Pango (>= 1.10.0), GTK+ (>= 2.8.0), GLib (>= 2.8.0)
  • a file NAMESPACE that you have to edit to add package dependencies. In my case, the package requires the packages e1071, ineq and RGtk2. Also, as the functions plot and mean are used so the standard packages stats and graphicsare needed. Packages dependencies are specified by the following line: 
    import(ineq,e1071,graphics,stats,RGtk2)
  • a folder R with the functions’ scripts. In this folder, I added a script init.Rthat contains a welcome message printed on screen when the package is loaded. This script contains: 
    .onAttach = function(libname, pkgname){
    packageStartupMessage("")
    packageStartupMessage("###############################")
    packageStartupMessage("")
    packageStartupMessage("      Welcome Lazy Student!! This is 'wnaetw' package")
    packageStartupMessage("      (http://tuxette.nathalievialaneix.eu/?p=866&lang=en)")
    packageStartupMessage("")
    packageStartupMessage("Use calculateGUI() to start the Graphical User Interface.")
    packageStartupMessage("Use demo(wmtw) for a demo of the WhatMyTeacherWants function")
    packageStartupMessage("More details are provided with help(wnaetw)")
    packageStartupMessage("")
    packageStartupMessage("This package comes with ABSOLUTELY NO WARRANTY.")
    packageStartupMessage("In particular, the dev team is not responsible if a lazy student is not")
    packageStartupMessage("      able to interpret the function's results properly!!")
    packageStartupMessage("")
    packageStartupMessage("###############################")
}
  • a folder data where the data are saved as separated rda files;
  • a folder man with the functions’, the datasets’ and the package’s help pages. All these files must be edited and filled in to describe the package, the functions and the datasets. Example of such documentation files can be found in the folder man by uncompressing the archive of the package source.

Additionally,

  • the folder inst can be used to put whatever you want. I used it to provide the “student” dataset (coming from my yearly student surveys) as a CSV file in a sub-folder named csv-data/;
  • a folder demo can be used to put demos: demos are provided as script files that will be run and printed on screen altogether. This folder must contain a file named 00Index with the demo’s names and descriptions (see also the package source);
  • a NEWS file can be added to describe the versions history.

Build and check the package

Once your package is ready, it has to be built. This is done by using the following command line in the directory that contains your package’s folder: 

R CMD build wnaetw

A filewnaetw_1.0.tar.gzshould be created. You can then check that your package contains no major mistake by 

R CMD check wnaetw_1.0.tar.gz

(this can take a while). In my case, this resulted in one warning: 

WARNING: There was 1 warning, see
  ‘..../wnaetw.Rcheck/00check.log’
for details

due to 

* checking DESCRIPTION meta-information ... WARNING
Non-standard license specification:
  WTFPL (>=2.0)
Standardizable: FALSE

because only GPL licence should be used to publish your package on CRAN (but this package is not supposed to be uploaded on CRAN so I used the famous Do What The Fuck You Want To Public License for this package. You can find in the directory wnaetw.Rcheck useful information such as, the PDF manual or the final form of the package (among other interesting files that you can check before installing the package).

At this step, if everything is ok, your package is ready to be installed on a linux computer: 

R CMD INSTALL wnaetw_1.0.tar.gz --html

(the option --html is used to install HTML documentation in case it is not your default documentation).

Mac users…

… can compile the package from source by the same command line if XCode is installed on their OS.

Windows users…

… can also probably compile the package from source but this post doesn’t explain how (RTFM). However, if you have a package built on a Linux system, you can obtain windows binary by uploading it on the CRAN windows builder.

Install the package

The package is now ready for use. Do you want to install it on your computer, lazy student?

wnaetw: What Nicolas’s Teacher Wants

This package does what Nicolas’s teacher wants with numerical variables. It seems pretty clear with just the title.

Version: 1.0
Date: 2012-08-31
Author: Nicolas A. Edwards, Arthur Gomez, Jonathan Mahe and Nathalie Villa-Vialaneix
Maintainer: Nathalie Villa-Vialaneix <nathalie@nathalievialaneix.eu>
License: WTFPL (>=2.0)
Depends: e1071, ineq, graphics, stats, RGtk2
SystemRequirements: Cairo (>= 1.0.0), ATK (>= 1.10.0), Pango (>= 1.10.0), GTK+ (>= 2.8.0), GLib (>= 2.8.0)
Installation: wnaetw installation info
CRAN checks: wnaetw results

Downloads:

Package source: wnaetw_1.0.tar.gz
MacOS X binary: wnaetw_1.0-mac.tar.gz
Windows binary: wnaetw_1.0.zip
Reference manual: wnaetw.pdf

Use the package on:

  • Linux

    a proper Gtk environment has to be installed, which is generally the case on most linux systems. Thus, you probably just have to install the RGtk2 package (and the other packages listed in Depends by the following command line: 

    sudo apt-get install r-cran-rgtk2

    (it will install the Gtk environment on your system as well, if you don’t already have it). Then use the package source above with the command 

    R CMD INSTALL --html wnaetw_1.0.tar.gz

  • Windows

    (thank you NiLeDAM for installing and testing another similar package on your computer, for checking the procedure and for pointing out a few bugs…)

    Installation on windows is a bit trickier (how surprising!…). You first have to download (exe, 6 Mo) the automatic installer for the GTK runtime. Then start R and install all required packages from CRAN, including RGtk2. Try to load RGtk2 

    library(RGtk2)

    at this step, you can have the following error 

    Error in inDL(x, as.logical(local), as.logical(now), ...) :
  unable to load shared object
'.../R/R-2.15.1/library/RGtk2/libs/i386/RGtk2.dll':
  LoadLibrary failure:  La procédure spécifiée est introuvable.

    (in French); if this happens accept what it asks to download and once it’s done (downloaded and installed), restart R and try again: you should not have this message anymore. Finally install the package wnaetw from windows binary above.</li>

  • Mac OS X

    (thank you Nicolas for building the package for Mac and for testing it on your computer)

    To install RGtk2 on Mac OS X, you first need to install a proper Gtk+ environment. Several methods exist but the simplest is certainly to use the pre-compiled Gtk+ framework that can be found here (requires Mac OS X 10.5 (Leopard) or higher). If your OS is Mac OS X Lion or higher, you first need to install X11 (see here). Then install all required packages from CRAN and finally, install the package wnaetw from Mac OS X binary provided above.</li> </ul>

    Finally, start R, write out 

    library(wnaetw)
calculateGUI()

    Happy? 😉

    </div>