1 Packages

1.1 What and Why?

What?

  • A simple directory structure with text files.
  • DESCRIPTION: title, author, version, license, etc.
  • NAMESPACE: functions used by and made available by your package
  • R/: function defintions
  • man/: help pages
  • vignettes/: vignettes
  • tests/: code to test your package

Why?

  • Organize an analysis.
  • Share reproducible code with lab mates, colleagues, …

Minimal

$ tree MyPackage
MyPackage
└── DESCRIPTION

0 directories, 1 file
$ cat MyPackage/DESCRIPTION 
Package: MyPackage
Type: Package
Version: 0.0.1
Author: Martin Morgan
Maintainer: Martin Morgan <martin.morgan@roswellpark.org>
Title: A Minimal Package
Description: An abstract-like description of the package.
License: Artistic-2.0

Typical

$ tree
.
└── MyPackage
    ├── DESCRIPTION
    ├── man
    │   └── hi.Rd
    ├── NAMESPACE
    ├── R
    │   └── hi.R
    ├── tests
    │   ├── testthat
    │   │   └── test_hi.R
    │   └── testthat.R
    └── vignettes
        └── MyPackage.Rmd

6 directories, 7 files

1.2 Working with packages

Build

$ R CMD build MyPackage
* checking for file 'MyPackage/DESCRIPTION' ... OK
* preparing 'MyPackage':
* checking DESCRIPTION meta-information ... OK
* checking for LF line-endings in source and make files and shell scripts
* checking for empty or unneeded directories
* creating default NAMESPACE file
* building 'MyPackage_0.0.1.tar.gz'

Check

$ R CMD check MyPackage_0.0.1.tar.gz 
* using log directory '/home/mtmorgan/a/BiocIntro/vignettes/MyPackage.Rcheck'
* using R version 3.4.2 Patched (2017-10-12 r73550)
* using platform: x86_64-pc-linux-gnu (64-bit)
* using session charset: UTF-8
* checking for file 'MyPackage/DESCRIPTION' ... OK
* checking extension type ... Package
* this is package 'MyPackage' version '0.0.1'
* checking package namespace information ... OK
* checking package dependencies ... OK
* checking if this is a source package ... OK
* checking if there is a namespace ... OK
* checking for executable files ... OK
* checking for hidden files and directories ... OK
* checking for portable file names ... OK
* checking for sufficient/correct file permissions ... OK
* checking whether package 'MyPackage' can be installed ... OK
* checking installed package size ... OK
* checking package directory ... OK
* checking DESCRIPTION meta-information ... OK
* checking top-level files ... OK
* checking for left-over files ... OK
* checking index information ... OK
* checking package subdirectories ... OK
* checking whether the package can be loaded ... OK
* checking whether the package can be loaded with stated dependencies ... OK
* checking whether the package can be unloaded cleanly ... OK
* checking whether the namespace can be loaded with stated dependencies ... OK
* checking whether the namespace can be unloaded cleanly ... OK
* checking loading without being on the library search path ... OK
* checking examples ... NONE
* checking PDF version of manual ... OK
* DONE

Status: OK

Install

$ R CMD INSTALL MyPackage_0.0.1.tar.gz 
* installing to library '/home/mtmorgan/R/x86_64-pc-linux-gnu-library/3.4-Bioc-3.6'
* installing *source* package 'MyPackage' ...
** help
No man pages found in package  'MyPackage' 
*** installing help indices
** building package indices
** testing if installed package can be loaded
* DONE (MyPackage)

2 Package Development

2.1 Olde School

  • Add new functions in files R/foo.R
  • Update NAMESPACE to import functions or packages used by your function, and to export your functions that users will want to use.
  • Create man pages by hand
  • Write vignettes in LaTeX Sweave
  • Key reference: Writing R Extensions, RShowDoc("R-exts")

2.2 New School

  • devtools::create() a package skeleton. More flexible Authors@R instead of Author: / Maintainer: fields.
  • Use ‘roxygen’ to document functions

    • Lines starting with #' are documentation lines
    • @details, @param, @return, @examples document the function
    • @export indicates that the function should be visible to the user
    • @import and @importFrom indicate (non-base) functions that are used by this function, e.g,. @importFrom stats rnorm runif
    • devtools::document() to update documentation.
    #' Title, e.g., Say 'hi' to friends.
    #'
    #' Short description of this help page. `hi("Martin")` returns a greeting.
    #'
    #' @details A more extensive description of the functions or other objects
    #'    documented on this help page. Use `how=` to determine the