In MariekeDirk/Reproducability-Reusability-course: Course example package

knitr::opts_chunk$set(echo = TRUE)
#themes: “default”, “cerulean”, “journal”, “flatly”, “readable”, “spacelab”, “united”, “cosmo”, “lumen”, “paper”, “sandstone”, “simplex”, “yeti"

Introduction

During this tutorial the following topics are covered:

Create a new project
Writing and documenting functions in R
Raw data and data description
Document, built and reload
Extra: Introduction to markdown, README.md

Required packages for this tutorial:

devtools
roxygen2

Creating a new project

According to Rpackages by Hadley Wickham the following package components are included:

Code (R/)
Package metadata (DESCRIPTION)
Object documentation (man/)
Vignettes (vignettes/)
Testing (tests/)
Namespaces (NAMESPACE)
Data (data/)
Compiled code (src/)
Installed files (inst/)
Other components

Challenge 2.1: Create a new Rstudio project on GitHub (online instructions). What are the standard folders and files that are created?

Challenge 2.2: Give your new package a title, description and author name. Commit your changes to GitHub.

Additional reading: We won't cover all the package components, feel free to read more about them online , or check the online support

Writing and documenting functions in R

We use functions all the time, e.g. min, max, mean.

Challenge 3.1: Check the code with read.csv. On which function does read.csv relay?

Using function can significantly reduce your code length and improve the reproducibility. Below an example of a function in R:

area_of_square<-function(length,width){
  if(!inherits(length,"numeric") | !inherits(width,"numeric")) { #check if the input is numeric
    message("Your length or width is not numeric")
    return(FALSE)                                                # if the input is not numeric FALSE is returned 
  } else {
    area<-length*width                                           #calculating the area of the square
    return(area)                                                 #returning the variable area
  }

}

Challenge 3.2: Run area_of_square and test the function with random numbers. What happens if you use area_of_square('5','5')? Save your function in the R folder.

The function read.csv has a documentation page, which we can read typing ?read.csv. It is very handy to check what all the variables mean and what the function does. So, we are also going to create a documentation page for our function. The documentation uses the following syntax:

#'
#'@title Square area
#'@description Function to calculate the area of a square. Requires numeric input. 
#'@param length The length of the square 
#'@param width The width of the square 
#'@examples
#'square_area(4,5)
#'
#'\dontrun{
#'square_area(4,"5")}
#'@author Marieke Dirksen
#'@export
#'

area_of_square<-function(length,width){
  if(!inherits(length,"numeric") | !inherits(width,"numeric")) { #check if the input is numeric
    message("Your length or width is not numeric")
    return(FALSE)                                                # if the input is not numeric FALSE is returned 
  } else {
    area<-length*width                                           #calculating the area of the square
    return(area)                                                 #returning the variable area
  }

}

Challenge 4.2: Write and document your own function. In order to create the documentation page use devtools::document(). Check your man/ folder, it should now contain a *.Rd file. Use the Install and Restart button under Build to attach the library. To test if your documentation works type: ?area_of_square.

Additional material: watch youtube

Raw data and data description

Small datasets, like data("iris"), can be stored within a package. Similar to the functions this data is also documented: ?iris. We are going to create our own dataset with lengths and widths from which we want to calculate the area.

length<-runif(15,min=1,max=50)
width<-runif(15,min=1,max=50)
my.df<-data.frame("length"=length,"width"=width)

devtools::use_data(my.df,overwrite=TRUE)

Challenge 5.1: Use devtools::use_data_raw() to create the folder data-raw. Go to the folder and create a R scipt with the name dataraw.R. Create a data.frame for your own function, use devtools::use_data(my.df) to write your data into the data folder.

The documentation of the data looks similar to the function documentation:

#' Lengths and widths
#'
#' This dataset contains random numerical values between 1 and 50
#' 
#'
#' @format A data frame with 15 rows and 2 variables:
#' \describe{
#'   \item{length}{length of the area}
#'   \item{width}{width of the area}
#' }
"my.df"