In au-oc/content: Lesson Content for AU Open Coders

source("R/utils.R")
library(magrittr)
knitr::opts_chunk$set(comment = "")

Session details

• Date of session: r format_date(params$datetime)
• Instructor: r params$instructor
• Session level: r params$level
  • Part of the "Package Development Series"

• Required packages to install:

  r install.packages(c("devtools", "usethis"))

Objectives

1. To see that making packages is not as difficult as it seems.
2. To learn about and use the tools to simplify and automate package development.
3. To provide the resources to expand your knowledge on package development.

At the end of this session you will be able:

1. Setup up the necessary folders and files for making a package.
2. Fill out some package description information (in the DESCRIPTION and README.md files).
3. Include some functions in your package (in the R/ folder).
4. Install your package.

Resources for learning and help

• R Packages online (free) book
• Creating an R package, a pictorial tutorial
• Package development cheatsheet
• devtools package website
• usethis package website
• DataCamp R package course (with a DataCamp subscription)

List of functions and files covered

Functions:

• usethis::create_package()
• usethis::use_r()
• usethis::use_readme_md()
• usethis::use_mit_license()
• devtools::load_all() (Ctrl-Shift-L)
• devtools::build() / devtools::install() (Ctrl-Shift-B)
• usethis::use_usethis()

Files:

• DESCRIPTION
• NAMESPACE
• R/
• README.md
• LICENSE

Creating and naming a package

First thing is first: An R package is simply a collection of R functions saved on your computer that make it easy to access by using the library() command. When you make an R package, it does not get uploaded online, it does not mean other people can use it right away. At the beginning, the R package is only available to you and to your computer. That's it. So why would you want to create a package? Well, it can save time later with other data analyses since you can access your functions across files by using library(<yourpackagename>). A package bundles related code together, simplifying your life! Alright, that's done with, next step!

Creating the initial setup of files and folders necessary for an R package is incredibly easy with the usethis package! But! Before we begin, it's a good idea to think about what the name of the package should be. You can name it whatever you want, as long as it is not "base", "stats", "graphics", "utils", "tools", "methods", or any other default base R package. Generally, name it something that is pretty unique or specific to you. For this session, let's call it by your initials (or mine "lwj") and add "helpers"... so:

usethis::create_package("lwj.helpers")

pkg_name <- file.path(tempdir(), "lwj.helpers")
usethis::create_package(pkg_name)

A bunch of things are shown on your console. These are just some information that usethis is telling you that it has done. Otherwise, you now have the beginning of an R package! Pretty easy eh??

RStudio project options

Before we get into the package details more, let's make some edits to the project options. We'll change the "General" options to all "No" and check that the "Build Tools" has correctly set the project as a package.

Files and folders

There are many things that make an R package, well, an R package. One of them is the folder and file structure. All R packages must have certain files and folders in order to properly install.

Required:

• R/: This folder contains the code that is available when the package is installed. R files should only be in this folder, hence why it is called the R/ folder! Covered more below.
• DESCRIPTION: Contains all the necessary information about the package, such as author, version number, name, brief description, and the package dependencies. This file is more of the "machine-readable" metadata of the package. Covered more below.
• NAMESPACE: Tells R which functions are available to use from the package. At first, this file contains a command to list all functions that are in the R/ folder. We won't cover this file too much during this session.

Optional, but very helpful:

• .Rbuildignore: This file let's R know what to ignore when you install your package (for instance, the .Rproj file).
• The .Rproj file: Let's RStudio know that the directory is an RStudio Project and that it is a package. Adds some package development functionality to RStudio.

Package metadata

As mentioned above, there are two main files for providing package "metadata". Firstly, there is the DESCRIPTION, which is required for making a package. There are several data-fields in the file:

withr::with_dir(pkg_name, desc::desc())

The important data-fields are the Title, Authors, Description, and License (get to this more later). Ok, let's open up the file and make the edits.

Exercise (3-5 min): Open the DESCRIPTION file and change the title, author, and description fields.

The next optional, but important file to have as "human-readable metadata" is the README.md file. Right now it doesn't exist. But we can create it using:

usethis::use_readme_md()

withr::with_dir(pkg_name, {
    capture.output(usethis::proj_set(pkg_name))
    usethis::use_readme_md()
})

The file looks like this:

cat(readr::read_lines(file.path(pkg_name, "README.md")), sep = "\n")
# cat(file = file.path(pkg_name, "README.md"))

The README.md file is a markdown file. We covered markdown in a previous session. Generally, this file is a brief documentation containing a high level summary of what the package does, how to install it, and sometimes a simple example of how to use it. It should be written and targetted to other (potential) users, or yourself 9 months in the future (you'll thank yourself). Ok, this file right now has some things that need to be changed. Let's edit it.

Exercise (5 min): Write a (fake) goal and description of the package in the README.md file. Remove the text in the "Installation" section for now. Delete the "Example" section.

Next we want to add the license. The license is really important, even if you never put your package online. The license gives information about how other people can use and modify your code. We won't cover the legal details about licensing, but for now, I would recommend using an MIT License:

# usethis::use_mit_license("<your name>")
usethis::use_mit_license("Luke Johnston")

withr::with_dir(pkg_name, {
    capture.output(usethis::proj_set(pkg_name))
    usethis::use_mit_license("Luke Johnston")
})

The contents of the LICENSE file are:

cat(readr::read_lines(file.path(pkg_name, "LICENSE")), sep = "\n")

Adding R code

Now for the main reason you have created a package! To put your R code in it so you can use the code easily in other scripts! To create an R script in the package, use:

# usethis::use_r("<filename>")
usethis::use_r("addition")

# usethis::use_r("<filename>")
withr::with_dir(pkg_name, {
    capture.output(usethis::proj_set(pkg_name))
    usethis::use_r("addition")
})

An R script will open in RStudio. Now, let's add a function to it. We'll use a very simple function in file:

addition <- function(x, y) {
    x + y
}

Now save. To test that it works, now we run the next command:

devtools::load_all()

Or type "Ctrl-Shift-L". In the console, test if the function works:

addition(2, 2)

It should work! We'll add some more functions and play around with the R scripts.

Building and installing

Now, the final step! Let's build and install the package! When you feel your package is ready, time to install it for you to use with library()! And you can install it by using...:

devtools::install()

Or by typing "Ctrl-Shift-B". It does some quick checks, and if all goes well, you now have installed your package!

Other useful functions

If you end up developing R packages often, I would recommend running this command:

usethis::use_usethis()

This let's you add some code to automatically load when you open up R, to make it easier to continue your package development!

au-oc/content documentation built on May 21, 2019, 4:05 a.m.