Step 1: Add raw data file

• Call usethis::use_data_raw to create a folder called data-raw. We will use this folder as a general storage space for any raw data files, data pre-processing scripts, etc. that we don’t want to be built into our final package.

use_data_raw()

This new folder houses a DATASET.R script.

• Add your raw data file to the data-raw folder. I am adding a .csv file called aggression_behavior.csv.

Step 2: Save clean data to data/

Edit the DATASET.R script:

• Read in the .csv file containing our raw data.
• Include any code necessary for processing or cleaning to ready the data set as you’d like it to be presented in the package.
• Run usethis::use_data() which will export an .rda-formatted data file to a new folder, data. Any data in this folder will be accessible to the user.

[SHOULD WE MENTION ANYTHING ABOUT HERE::HERE?]

## code to prepare `DATASET` dataset goes here

# Read in your .csv file
aggression_behavior <- readr::read_csv(here::here("data-raw", "aggression_behavior.csv"))

# Include any processing steps here as well

# Export to `data/` as .rda file
usethis::use_data(aggression_behavior, overwrite = TRUE) # add overwrite option

Your data is now callable! Check that you can access your data.

• Click Build > Load All
• Print your data set object:

aggression_behavior

# A tibble: 214 x 11
   focal compound birthyr obyear  rank `infant?` attack_all chase_all threatcontact_a…
   <chr> <chr>      <dbl>  <dbl> <dbl> <chr>          <dbl>     <dbl>            <dbl>
 1 bs9   a1          2003   2008     3 N                  0         0            0    
 2 gk3   a1          1991   2007     1 Y                  0         0            0    
 3 se8   a1          2001   2008     1 N                  0         0            0    
 4 qq8   a1          2001   2008     3 N                  0         0            2.23 
 5 vd8   a1          2001   2008     3 Y                  0         0            0.998
 6 qv5   a1          1996   2008     3 Y                  0         0            0    
 7 sr8   a1          2001   2008     2 N                  0         0            0    
 8 pk8   a1          2001   2008     2 Y                  0         0            0    
 9 oz4   a1          1994   2008     1 N                  0         0            0    
10 hv5   a1          1996   2007     2 N                  0         0            0    
# … with 204 more rows, and 2 more variables: threatnocontact_all <dbl>, agg_in <dbl>
> 

Step 3: Document the data set

Because this will be a data set that is shared with others, it’s important to add reference documentation for it.

• Use usethis::use_r() with your data set name in quotes.

use_r("aggression_behavior")

This generates a .R script that lives in the R/ folder.

Add information about the data set:

• In the .R file, add the name of the data set object in quotes.
• Above the quoted object name, paste in specially-formatted comments (see the example below), called Roxygen comments.
• Manually edit the information to reflect the columns in your data set [IS THIS REALLY NOT A BETTER WAY TO DO THIS?].

(No “roxygen skeleton for data sets?”

• link0
• link1
• link2)

This is what will become our documentation.

#' Data of aggression behaviors observed in rhesus macaques
#'
#'
#'
#' @format A data frame with 214 rows representing individual "focal" rhesus and 11 variables:
#' \describe{
#'   \item{focal}{character denoting the subject ID of the rhesus}
#'   \item{compound}{a character indicating the social group the focal belongs to}
#'   \item{birthyr}{dbl denoting focal's year of birth}
#'   \item{obyear}{dbl denoting year of behavioral observation when data were collected on the focal}
#'   \item{rank}{dbl denoting high, middle, or low social rank of the focal (1, 2, or 3)}
#'   \item{infant?}{character denoting whether or not the focal had an infant less than 1 year old during time of observation}
#'   \item{attack_all}{average number of times an attack was intitiated by the }
#'   \item{chase_all}{a character string giving given name}
#'   \item{threatcontact_all}{a character string giving given name}
#'   \item{agg_in}{number of times aggression was initiated by the focal}
#' }
#' @source aggression_behavior.csv file
"aggression_behavior"

• Use devtools::document() to make the roxygen comments “concrete”.

#install.packages(c("devtools", "roxygen2"))
library(roxygen2)
library(devtools)

document()

This generates a .Rd file, that makes our documentation accessible to the package. [PHRASING?] This file lives inside a newly-generated man/ folder.

Now we can check that our documentation works:

• Call ? aggression_behavior, substituting the name of your data set.
• If everything looks good, then you’re done! If not, edit the roxygen-style comments in the .R file and document() again until you’re satisfied.

Step 4: Build and install

• As before, click on Install and Restart under the Build tab.

Here’s a review of all the data package steps so far:

Congratulations, your package now includes a documented data set! It can be downloaded and installed as recommeded in Step 5: Deliver of Part 1.

If you’d like to create a worksheet-like component for your package, continue with Part 3. Otherwise, skip to Final Steps for some recommendations on a couple final (and optional) package components.

Step 1: Create files and folders

I assume you have already created the basic package infrastructure from Part 1.

• Run use_rmarkdown_template(template_name = "<your-template-name")

use_rmarkdown_template(template_name = "Worksheet1")

✔ Setting active project to '/Users/desiree/Documents/New R Projects/testpackage'
✔ Creating 'inst/rmarkdown/templates/worksheet1/skeleton/'
✔ Writing 'inst/rmarkdown/templates/worksheet1/template.yaml'
✔ Writing 'inst/rmarkdown/templates/worksheet1/skeleton/skeleton.Rmd'
> 

This creates a new folder in the root package directory inst/ with several subdirectories.

Step 2: Create your template

• Edit skeleton.Rmd inside inst/rmarkdown/templates/<your-template-name>/skeleton/. This is what you’re users will see. consider what you’d like the output format to be.
  • To see some examples of how here.
• You can also include a description of your template in the template.yaml file in the parent directory skeleton/. But this is not critical to getting the template into the package.
• Save, Build > Install and Restart

You can get ideas for how minimal .Rmd templates can be customized by checkout out a few example templates here.

Step 3: Confirm that your template is accessible

• Once your R session has been restarted, navigate to File > New File > R Markdown. Select From Template from the dialogue box menu. Your custom R Markdown template will appear there. Voilà!

We next show you how you can introduce a special type of .Rmd document in your package: a LearnR tutorial.

Step 1: Create files and directories

As before, I assume you have at a minimum created the basic package structure from Part 1.

• Install the learnr package
• Run use_tutorial("<name-of-tutorial-file>", "<title-you'd-like-the-user-to-see>", open = interactive())

remotes::install_github("rstudio/learnr")

use_tutorial("Lesson1", "My Title", open = interactive())

This adds a tutorial folder to the inst directory.

Step 2: Customize your tutorial

• The .Rmd file inside the tutorial folder is automatically opened. Edit it to customize your tutorial content.

• Click Run Document next to the little green arrow in the toolbar of the .Rmd file.
  • This will generate a .html file in the same directory as the tutorial .Rmd file and also run your tutorial locally.

Step 3: Add additional subdirectory

At the time of writing, there is one additional folder that needs to be added, which use_tutorial did not create for us.

• Within the subdirectory tutorials/, add a new folder with the same name as your .Rmd tutorial file.
• Move your tutorial .Rmd file and the .html for your tutorial into this new folder.
• Build > Install and Restart

Step 4: Run your tutorial

• Run your tutorial with run_tutorial("<tutorial-name>", "<package-name>").

learnr::run_tutorial("Lesson1", "testpackage")

The above line of code is also how your users will be able to run your tutorial once they have installed your package.

If you get errors, double check that your structure for the tutorial folders and files matches that of those in the testpackage repository. Make sure you Build, Install, and Restart before trying again.