Module:Building R Packages Part I

(1)

Paper:Advanced R

Module:Building R Packages Part I

1 / 34

(2)

Development Team

Principal investigator: Prof. Bhaswati Ganguli, Professor, Department of Statistics, University of Calcutta Paper co-ordinator: Dr. Abhra Sarkar,Duke University Content writer: Rimli Sengupta

Content writer: Moumita Chatterjee,West Bengal State University Content reviewer: Dr. Santu Ghosh,Shri Ramachandra University

2 / 34

(3)

Thank You

I A big Thank you to those people who have contributed a lot to make the necessary tools and documentations for building packages.

I As per the record of July 2013, there are 4714 packages on CRAN and another 671 on Bioconductor.

I A famous package is Hadley Wickham’s devtools package.

3 / 34

(4)

R Folder Structure

I Before getting into the main point it is important to know about folder structure.

4 / 34

(5)

R Package : A R Folder

I An R package is actually a folder of folders.

I Each folder contains specific files.

I There must be at least two folders :

I R : The place where the included functions go.

I Man : The place where the documentation files are kept.

I At first all the documentations were done manually.

I But roxygen2 has easded the process.

5 / 34

(6)

Building Packages in R

I roxygen2 is a CRAN package.

I You may click on the following link to know more about roxygen2 package :

https://cran.r-project.org/web/packages/roxygen2/

index.html

I Each file of the folder must end with a blank line.

I Code must be shorter than 105 characters.

6 / 34

(7)

Building Packages in R

I There are some other common folders.

I src : which contain the codes of C++ and FORTRAN.

I data : which contains data that is contained in the package.

I inst : includes files that should be available to the final user.

I When a package is installed these files are not human-readable though there are some exceptions.

7 / 34

(8)

R Package

I All packages submitted to CRAN (or Bioconductor) must follow specific guidelines, including the folder structure of the package, inclusion of DESCRIPTION and NAMESPACE files and proper help files.

8 / 34

(9)

What does your package do?

I Title : It is a one line description of the package.

It is often noticed in package listing.

I Characteristics : It should be plain text (no markup).

It should be capitalised like a title.

It should not end in a period and should be short.

I listings : It often truncates the title to 65 characters.

9 / 34

(10)

What does your package do?

I Description: It is more detailed than the title.

We can write multiple sentences but we are limited to one paragraph.

Each line must be no more than 80 characters wide.

10 / 34

(11)

Building Package under windows

I There are few steps to build an R package under Windows.

11 / 34

(12)

Steps to follow

I Step One: Update R and other Tools.

I Step Two: Know your Windows System.

I Step Three: Decide what kind of package you want to build.

I Step Four: Get the necessary tools.

I Step Five: Install the tools.

12 / 34

(13)

Steps to follow

I Step Six: Fix your Path.

I Step Seven: Reboot and do some study.

I Step Eight: Sample Package.

I Step Nine: Edit some files if required.

I Step Ten: Finally Build.

13 / 34

(14)

Update R and other Tools

I First update the version of R to the current version and use R Studio instead of R.

I R Studio includes various options like:

I Source editor enhancements.

I Options for customizing pane layout and appearance.

I An interactive plotting package.

I Improved handling of different characters.

I And many more options and bug fixes.

14 / 34

(15)

Know your Windows System

I You should know about your windows system specially when you are coming from a different platform like MAC.

I Get familiar with three things first : 1. Location of your R Program.

2. R Console.

3. Path.

I My R is in this path :

C:\ProgramFiles\R\R-3.2.0.

15 / 34

(16)

What kind of Package want to build

I Two kinds of packages are:

1. Packages where the source is R code.

2. Packages where you have code in C, or Fortran, or C++.

I This choice makes you determine what kind of package you need. Then you can also determine which tool you need.

I In fact, to build packages that include only R source you do not need any of the compiler tools.

16 / 34

(17)

What kind of Package want to build

I The tools are related to documentation.

I If you want to build packages that have source code in a language OTHER THAN R, you need the compiler tools.

I If you want to build packages that only contain R source code, then you do not need the compilers.

17 / 34

(18)

Building packages that have only R source code

I First you need a program which will create the help files for your package.

I It is better to use MikTeX in this context.

I MikTeX is available at www.miktex.org/. Download that tool.

18 / 34

(19)

Building packages that have only R source code

I Then you need a program for making HTML help files.

I Microsoft Help Workshop can guide you to download and install the appropriate tool.

I URL : http://go.microsoft.com/fwlink/?LinkId=14188.

I The last tool you require is Rtools.

URL :

http://www.murdoch-sutherland.com/Rtools/Rtools213.exe.

I Also read the documentation when you are downloading.

19 / 34

(20)

Installing the tools

I You can install MikTeX for all users.

I During this process take care for missing elements.

I Install to the default directory it offered.

C:\ProgramFiles(x86)\MiKTeX2.9

I If necessary you can modify our path variable.

I While installing HTML tool it may require you to create a HTML Help Workshop folder.

I Proceed with the install. The path is :

C:\ProgramFiles(x86)\HTMLHelpWorkshop.

20 / 34

(21)

Fix your path

I Go to your path variable and cut and paste it into a text editor.

I If you make any mistakes you can revert.

I There are two important things to remember:

First you have to fix a path to Rcmd.exe.

I RCMD is Remote Command Service. Rcmd.exe, from the Windows NT Resource Kit, helps to connect to a computer running Windows NT.

I You may receive one or more of the following errors:

Error - Failed to connect, system not found or service not active etc.

21 / 34

(22)

Fix your path

I On My system it is on this path :

C:\ProgramFiles\R\R-3.2.0\bin\x64

I Make sure you have fixed your path. Also, you need to add a path for Windows HTML Help workshop.

I Fix the path for Rtools.

22 / 34

(23)

REBOOT

I After fixing your path, read some documentations.

I Write or edit some documentation files to build the package.

I Then check properly.

23 / 34

(24)

Building Package detail

I Go to this link and get detail about building R package : https: //cran.r-project.org/doc/manuals/R-exts.html

24 / 34

(25)

REBOOT - Contd.

I Create Rd files.

I These files are the source files which are used to create R manuals and also help make documentation for your package.

I This process will create several files. So edit immediately, otherwise package will not be built.

I Check properly.

25 / 34

(26)

REBOOT - Contd.

I Please note that sometimes it is hard to understand what your documents will look like when you are editing them in the Rd format.

I Get a better tool for editing and creating them.

26 / 34

(27)

Creating Sample package

I Now create a sample package.

I Before creating sample package create a new directory from your working directory.

I Start your R session and change your working directory to the new directory you have created just now.

27 / 34

(28)

I setwd(”C:/Users/RS/Documents/TestPackage”) getwd(); require(stats)

f <- function(x,y) x+y

g <- function(x,y) x-y

sample df<- data.frame(a=1, b=2) sample norm <- rnorm(1000)

28 / 34

(29)

I package.skeleton(list=c(”f”,”g”,”sample df”,”sample norm”), name=”mypkg”)

I When you will execute this it will give:

Creating directories ...

Creating DESCRIPTION ...

Creating NAMESPACE ...

Creating Read-and-delete-me ...

Saving functions and data ...

Making help files ...

Done.

Further steps are described in ’./mypkg/Read-and-delete-me’.

29 / 34

(30)

What is package.skeleton ?

I package.skeleton sets up for a new source package. It creates directories, saves functions, data, and R code files to

appropriate places, and creates skeleton help files and a

’Read-and-delete-me’ file describing further steps in packaging.

30 / 34

(31)

I Check that the files were created.

I Use R Studio to get a look at that Read-and-delete-me file.

31 / 34

(32)

Editing help files

I Package: mypkg

I Type: Package

I Title: What the package does (short line)

I Version: 1.0

I Date: 2015-09-19

I Author: Who wrote it

I Maintainer: Who to complain to

<yourfault@somewhere.net>

I Description: More about what it does (maybe more than one line)

I License: What license is it under?

32 / 34

(33)

After editing the file

I Package: mypkg

I Type: Package

I Title: Sample Test Package

I Version: 1.0

I Date: 2015-09-19

I Author: R Sengupta

I Maintainer: R Sengupta <rsengupta@gmail.com>

I Description: This package performs a few functions

I License: GPL 2

33 / 34

(34)

Edit Description File

I Fill in your own information.

I Please look at the documentation guide for specific rules to write documentation.

I Next, edit some of the other files.

34 / 34