In clarewest/RFQAmodelr: Random Forest Quality Assessment

knitr::opts_chunk$set(echo = TRUE, eval = FALSE)

RFQAmodel package

Today I am going to learn how to make a package.

This package will:

• read in at process the features
• get the features in a flexible way
• have a function to label models as correct/incorrect
• plot the ROC and ROC-like curves we use, flexibly
• have some kind of test

Resources

• R Packages, Hadley Wickham

Dependencies

• devtools
• roxygen2
• testthat

install.packages(c("devtools", "roxygen2", "testthat"))
devtools::install_github("r-lib/devtools")

library(devtools)
library(roxygen2)
library(testthat)

Elements of a package

• [ ] R code: R/ directory where the code lives
• [x] Package metadata: DESCRIPTION describes the package, license and contact information
• [ ] Documentation: documentation to describe each function; created using roxygen2
• [ ] Vignettes: long-form documents that show how to combine parts of the package to solve real problems; created using R markdown
• [ ] Tests: unit tests that define correct behaviour and alert you when functions break; uses testthat
• [ ] Namespace: NAMESPACE file defines functions made available to other packages and requirements from other packages; created using roxygen2
• [ ] External data: data/ directory (e.g. examples)
• [ ] Compiled code: src/ directory to include compiled C/C++ code
• [ ] Other components: including demo/ exec/ po/ and tools/
• [ ] Git and github (via Rstudio)
• [ ] Automated checking
• [ ] Release

Create the package

I found that lots of the devtools functions mentioned in the R Packages book are now part of the usethis package since a big update to devtools

usethis::create_package("~/clareR/RFQAmodelr")

This will create RFQAmodelr, DESCRIPTION and NAMESPACE file.

DESCRIPTION FILE:

Package: RFQAmodelr
Title: What the Package Does (One Line, Title Case)
Version: 0.0.0.9000
Authors@R:
    person(given = "First",
           family = "Last",
           role = c("aut", "cre"),
           email = "[e-mail]",
           comment = c(ORCID = "YOUR-ORCID-ID"))
Description: What the package does (one paragraph).
License: What license it uses
Encoding: UTF-8
LazyData: true

DESCRIPTION file can be edited manually or via more usethis functions.

For example, to add required packages:

usethis::use_package("dplyr")
#> Setting active project to '/homes/west/clareR/RFQAmodelr'
#> Adding 'dplyr' to Imports field in DESCRIPTION
#> Refer to functions with `dplyr::fun()`

Other useful things:

options(usethis.full_name = "Clare E. West")
usethis::use_mit_license()

use_readme_md()
#> Writing 'README.md'
#> Modify 'README.md'

R code:

Create an .R file and R/ directory (if it does not already exist)

use_r("hello")
#>Creating 'R/'
#> Modify 'R/hello.R'

## Add a function into hello.R
say_hello <- function(name="stranger"){
  print(paste("Hello, ", name, "!", sep=""))
}

## Load the package
devtools::load_all()
#>Loading RFQAmodelr

RFQAmodelr::say_hello()
#> [1] "Hello, stranger!"

RFQAmodelr::say_hello("Clare")
#> [1] "Hello, Clare!"

It's not possible to have subdirectories, so if files need to be grouped use a common prefix: prefix-*.R

Packages are loaded in two steps: when it is built (e.g. by CRAN) all the code in R/ is executed and the results are saved; when it is loaded (library() or require()), the cached results are made available.

Don't run code at the top-level of a package, only create objects (mostly functions)

Be careful using functions that depend on global options (which may differ by user) e.g. read.csv() uses the option stringsAsFactors

To display a message when the package loads, use .onAttach()

.onAttach <- function(libname, pkgname) {
  packageStartupMessage("Welcome to my package")
}

Object documentation

Object documentation is accessed by ? or help() and stored in .Rd files in the man/ directory. The syntax is loosely based on LaTeX.

roxygen2 turns formatted comments into .Rd documentation files . roxygen comments start with #'

Documentation workflow:

• add roxygen comments to the .R files
• Run devtools::document() (or Cmd + shift + D in RStudio) to convert roxygen comments to .Rd files
• Preview documentation with ?
• Repeat

#' Say hello
#'
#' Receive a greeting from RFQAmodelr
#'
#' @param name string. Your name
#' @return Returns a greeting, personalised using \code{name} if provided.
#' @examples
#' say_hello()
#' say_hello("Clare")
say_hello <- function(name="stranger"){
  message = paste("Hello, ", name, "!", sep="")
  return(message)
}

Components:

• The first sentence is the title of the documentation (use sentence case, but don't use a full stop)
• The second paragraph is the description and should briefly describe what the function does
• The optional third and further paragraphs are included in the details, shown after the argument description.
• Blocks are broken up into tags: @tag details
• Most functions will have the tags @param, @examples, @return
• Examples must run without errors as they are run automatically, but \dontrun{} will prevent this (e.g. to demonstrate code that causes an error). They can be stored in separate files and use @example path/relative/to/package/root
• Arbitrary sections can be used: @section My Section:
• Params can be inherited from other function documentation using @inheritParams source_function

Vignettes

A vignette is a guide to using the package, and each package may have multiple vignettes. They can be made using the R markdown vignette engine provided by knitr.

usethis::use_vignette("RFQAmodelr-guide")
#> Adding 'knitr' to Suggests field in DESCRIPTION
#> Setting VignetteBuilder field in DESCRIPTION to 'knitr'
#> Adding 'inst/doc' to '.gitignore'
#> Creating 'vignettes/'
#> Adding '*.html', '*.R' to 'vignettes/.gitignore'
#> Adding 'rmarkdown' to Suggests field in DESCRIPTION
#> Writing 'vignettes/RFQAmodelr-guide.Rmd'
#> Modify 'vignettes/RFQAmodelr-guide.Rmd'

This generates the template for a vingette, which uses R markdown.

Testing

Implement formal automated (AKA unit) testing using the testthat package, rather than informal testing through the command line.

usethis::use_testthat()
#> Adding 'testthat' to Suggests field in DESCRIPTION
#> Creating 'tests/testthat/'
#> ✔ Writing 'tests/testthat.R'
#> Call `use_test()` to initialize a basic test file and open it for editing.

clarewest/RFQAmodelr documentation built on Jan. 25, 2020, 12:42 a.m.