In ViennaR/startupPackage: Sample package

library(dplyr)
myFunction = function(values, groups){
  result = data.frame(value = values, group = groups) %>%
    group_by_('group') %>%
    summarize_(avg = ~mean(value, na.rm = TRUE))
  return(result)
}

Prerequisites

Software

• (surprisingly) R
• RStudio
• git or GitHub git client
• Rtools - only Windows users

R packages

• devtools - really don't know how people managed to develop R packages without it
• testthat - for automatic testing
• covr - for tests coverage reports
• dplyr - we will use it in our example function

install.packages(c('devtools', 'testthat', 'covr'))

Accounts

• GitHub - git hosting with many useful features (issue tracker, wiki, external tools, e.g. continues integration systems)
• Travis - continues integration system working with GitHub (so get a GitHub account first)
• Coveralls - code coverage reporting system working with GitHub (so get a GitHub account first)

Create a project

Create new GitHub repository

Log into GitHub and create a new repository (click the plus sign in the top-right corner and choose New repository...)

• Give it a name,
• Choose it to be public,
• Check Initialize this repository with a README
• Choose R from Add .gitignore
• Choose MIT License (or any other) from Add a license
• Click Create repository

• copy your repository clone URL - it will be needed in the next step

Create and configure RStudio project

Create RStudio project from the GitHub repository

• Open RStudio
• Choose menu File->New Project...
• Choose Version Control
• Choose Git
• Paste your repository clone URL (see previous chapter) into Repository URL
• Choose a directory
• Click Create Project

Configure your RStudio project

• Choose menu Tools->Project Options...
• Go to General
  • Choose No in all cases (we are developing a package, so there should be no automatically created session data there)
• Go to Build Tools
  • In Project build tools choose Package
  • Check Generate documentation with Roxygen
    • Make sure all entries in the Automatically roxygenize when running: are checked
• Close window by clicking OK (RStudio will reload your project)
• Create file .Rbuildignore in the root directory of your project
  (it contains a list of files which should be omitted during package build)
  Fill it with: r ^.*\.Rproj$ ^\.Rproj\.user$ ^.travis.yml$
• Add a line *.Rproj to file .gitignore
  (we don't want to include our RStudio project file in the repository)

Initialize an R package

• Initialize package skeleton
  (this will generate an R directory and a DESCRIPTION file)
  (we are using rstudio = FALSE parameter, because RStudio project files are already created) r devtools::setup(rstudio = FALSE)
• Edit the DECRIPTION file:
  • Fill in Title and Description
    (title text should be in title case, e.g. My Sample Project instead of My sample project)
    (description text should contain a full stop at the end)
  • Fill in Authors\@R (replace First and Last and a sample email with your name, surname and email, leave role as it is)
  • Put your license name followed by + file LICENSE in the License field (compare screenshot below)
  • If you plan to use functions from other packages, put their names (and, if required, versions) as a comma-separated list in the Import field (compare screenshot below)
• Go to tab Build and click Check (or simply hit CTRL+SHIFT+E)
  A lot of messages will be displayed but the final one should be R CMD check succeeded
  Moreover you should see no more then one warning (the one we can expect is checking PDF version of manual ... WARNING and is connected with the fact we do not have LaTeX installed on our computer)
  Congratulations! You have just built your first R package (an empty one, but anyway)

Set up testing and continues integration

• Set up directory structure for tests (directory tests with some content will be created) r devtools::use_testthat()
• Enable Coveralls for your repository
  • Log into Coveralls at https://coveralls.io
  • Go to https://coveralls.io/repos/refresh - you will see a list of your GitHub repositories
  • Turn on Coveralls for your new repository
• Add the covr package to the Suggests: section of you DESCRIPTION file

• Set up a continues integration with code coverage checks

  • Create file .travis.yml in the root directory of your project
    Fill it with:
    (adjust the notification email) ```r # http://docs.travis-ci.com/user/languages/r/ language: r

    sudo: required

    after_success: - Rscript -e 'library(covr);coveralls()'

    warnings_are_errors: false

    notifications: email: - your@email - if your package depends on packages available on GitHub but not on CRAN, add a section:r r_github_packages: - user1/repoName1 - user2/repoName2 - Log in to Travis at https://travis-ci.org/ - Go to https://travis-ci.org/profile/ - Turn on Travis for your new repository - If you can not see your repository on the list, you may refresh the list with the _Sync_ button ![](img/travisEnable.png) - Add Travis and Coveralls badges to your package _README.md_ file: (adjust your login and repository name in URLs) (you can also copy badges code from Travis/Coveralls web sites)r # sampleProject

  ```

Commit your changes

• Open the Git tab in the RStudio (see the screenshot)
• Check all files in the Staged column
• Click the Commit button
• Provide a commit description in the Commit message text field
• Click the Commit button
  
• Close the window summing up your commit.
• Push your commit to the GitHub by clicking the Push button (if for some reason RStudio is unable to push the commit for you, please do it externally using your favorite git shell)

Create a simple function

Now lets create a simple function which will take two arguments and return average value of the first one grouped according to values of the second one

Create a file with function source code

Create file myFunction.R in the R directory with a following content:

myFunction = function(values, groups){
  result = data.frame(value = values, group = groups) %>%
    group_by_('group') %>%
    summarize_(avg = ~mean(value, na.rm = TRUE))
  return(result)
}

Remarks:

• you can use any file name you want but it is easier to find your function if a name of the file is the same as function name
• you can put many functions into one file but I find it easier to manage my source code if I create one file per function

Provide documentation

We will use Roxygen syntax.
The easiest way to introduce it will be an example, so lets look at the myFunction.R after adding documentation in a Roxygen syntax:

#' Computes means by groups
#' @description
#' You can put extended description here
#' @details
#' If your function is complicated, you may consider adding a details section
#' @param values numeric vector of values
#' @param groups vector of groups
#' @return data.frame with groups names in first column and average values per group in the second one
#' @export
#' @import dplyr
myFunction = function(values, groups){
  result = data.frame(value = values, group = groups) %>%
    group_by(group) %>%
    summarize(avg = mean(value, na.rm = TRUE))
  return(result)
}

Remarks:

• \@description and \@details sections are optional
• \@param has syntax \@param argumentName argument description
• \@return has no formal syntax (but I prefer to denote returned value type followed by detailed description)
• \@export means your function should be visible to package users (in opposite to functions which are used only internally)
• \@import has syntax \@import packageName and means that you are using functions from a given R package in your function
  • instead of using \@import you can explicitly declare namespace for functions from other package (e.g. write dplyr::group_by() instead of simply group_by())
  • if you want to submit your package to CRAN, take a while to read more on this topic, e.g. in Hadley's publications here and here as well as in the Writing R Extensions

Check if function works

• Hit CTRL+SHIFT+L to install and load package
  (it is something like install.packages(myPackage) followed by library(myPackage) but of course your package is installed from local source and not from CRAN)
  (you can also click the Build & Reload button in the Build tab)
• Run your function on sample data: r myFunction(1:10, rep(1:2, each = 5))
• Check automatically created documentation: r ?myFunction

Create a simple test

User-defined tests

We will use the testthat library to prepare tests.

• Create file tests/testthat/test-myFunction.R: r test_that('my first test', { expect_equal( myFunction(1:10, rep(1:2, each = 5)), data.frame(group = c(1, 2), avg = c(3, 8)) ) }) Remarks:
  • Each file containing test should be put in the tests/testthat directory and its nave have to begin with test-
    • its up to you, how you divide your tests among files
  • Each test file contains one or more group of tests. A group is denoted by a test_that() function call which takes to arguments - group name and the R code performing tests.
  • In each group you are using different expect...() functions to check if your package behaves as expected
    (technically we call such single tests _assertions or expectations)
• Run your tests by hitting CTRL+SHIFT+T
  (this will run all tests in your project)
  (of course you can also run single tests manually by marking their source and hitting CTRL+ENTER)

• You should get something like: ```r Loading sampleProject Loading required package: testthat Loading required package: dplyr

  Attaching package: ‘dplyr’

  Następujące obiekty zostały zakryte z ‘package:stats’:

  filter, lag
  

  Następujące obiekty zostały zakryte z ‘package:base’:

  intersect, setdiff, setequal, union
  

  Loading required package: ggplot2 Testing sampleProject 1 1. Failure (at test-myFunction.R#2): my first test ----------------------------- myFunction(1:10, rep(1:2, each = 5)) not equal to data.frame(group = c(1, 2), avg = c(3, 8)) Incompatible type for column group: x integer, y numeric - Lets fix our test according to the error message (by providing the _group_ variable as an _integer_ data type):r test_that('my first test', { expect_equal( myFunction(1:10, rep(1:2, each = 5)), data.frame(group = c(1L, 2L), avg = c(3, 8)) ) }) ```

R package tests

Besides tests provided by you R can perform his own tests on your package code.
Among them there are as useful ones as checking for undefined variables and functions (a curse of R developers).
As these are more advanced topics and your package will still work even R package tests rise some NOTEs or even WARNINGs on it you can skip this section if you find it to difficult (but if you want to put your package in CRAN at some point you will have master them anyway).

• Hit CTRL+SHIFT+E (or go to the Build tab and click Check button) to trigger package check (note that tests provided by you in the previous chapter are also executed)
• Among check results you should find: ```r
  • checking R code for possible problems ... NOTE myFunction: no visible binding for global variable ‘group’ myFunction: no visible binding for global variable ‘value’ ``` This message is caused by the fact that we are trying to use undeclared variables group and value in our function.
    In this case it is not an error because dplyr uses a technique called non-standard evaluation but:
  • you should read such messages carefully and check if it is really an expected behavior
  • developing packages you should avoid non-standard evaluation and rather write your function like that: r #' Computes means by groups #' @description #' You can put extended description here #' @details #' If your function is complicated, you may consider adding a details section #' @param values numeric vector of values #' @param groups vector of groups #' @return data.frame with groups names in first column and average values per group in the second one #' @export #' @import dplyr myFunction = function(values, groups){ result = data.frame(value = values, group = groups) %>% group_by_('group') %>% summarize_(avg = ~mean(value, na.rm = TRUE)) return(result) }

See how it works

At the moment we should have an R project configured to work with Travis and Coveralls with a sample function and tests.
No lets try to see a continues integration at work.

• Check your package by hitting CTRL+SHIFT+E - there is no point in committing a code which has errors
• Commit and push your code to the GitHub (you may notice a new man directory and the man/myFunction.RD file in it - this is a documentation generated automatically from your Roxygen comments)
• Open your repository package site on the GitHub and click on the build badge
  You will be redirected to the Travis build page and can track a progress of your build
  (be aware that it may take up to few minutes before Travis will find out about your commit and start your build)
  (the build can take a few minutes so please be patient)
• If your build was successful, open your repository package site on the GitHub and click on the coverage badge
  You will be redirected to the Coveralls page and can check your code coverage
• Everybody can install your package: r devtools::install_github('yourLogin/yourRepository')

ViennaR/startupPackage documentation built on May 9, 2019, 9:56 p.m.