Day 24 - Package Documentation

Spring 2023

Dr. Jared Joseph

Smith College

Overview

Timeline

  • Help Files Overview
  • Writing Help Files

Goal

Learn how to author help files and make them usable in R.

Help Files Overview

What Does a Help File Include?

Title
What is the title of the help page? (Usually a tiny description of function)
Description
What does this function do?
Arguments
What arguments does the function take? What are the defaults? What type of objects work?
Details
What else do you want people to know?
Return
What does the function return?
Examples
What are some examples of using this function?

Help Files live in ./man/

The man directory contains all of the help files for your code.


These are the files loaded when using the ? or help() function in R.


You need to write them, but we have tools to help with the formatting later.

R Project Name
.
├── R/
│   └── func1.R
├── man/
│   └── func1.Rd
├── inst/
│   ├── data/
│   │   └── example_data1.csv
│   └── other
├── vignettes/
│   └── v1.rmd
├── docs/
│   └── v1.html
├── tests/
│   └── testthat/
│       └── test-func1.R
├── NAMESPACE
├── DESCRIPTION
├── LICENSE
├── NEWS.md
├── README.Rmd 
├── .gitignore
└── .Rbuildignore

Writing Help Files

The .rd Syntax

R help files rely on a specific syntax unique to R.


It’s like LaTeX, but not quite. You can see an example here.


By using specific formats, we can do things like link to other help files, and have executable examples.

\name{nattswap_compare}
\alias{nattswap_compare}
\title{nattswap_compare}
\usage{
nattswap_compare(
  get_att_swap_sig_results,
  metric_name = "all",
  swapped_att,
  all_nrow = 1,
  all_ncol = NULL,
  font_family = NULL,
  yaxis = c(NA, NA),
  xaxis = NA,
  bin_num = 50
)
}
\arguments{
\item{get_att_swap_sig_results}{Result of \code{get_att_swap_sig}}

\item{metric_name}{Character. A vector of "degree", "evc", "bet", "n_bet", "closeness", "max_cohesion", or "nestedness". Defaults to "all" which will display all metrics.}

...

roxygen2 Templates

Rather than write help files ourselves, we’ll use roxygen2 to help.


This package lets us write the documentation for functions along side the code, and simplifies the syntax a bit.


You can see an example template here.

#' nattswap_compare
#'
#' @param get_att_swap_sig_results Result of \code{get_att_swap_sig}
#' @param metric_name Character. A vector of "degree", "evc", "bet", "n_bet", "closeness", "max_cohesion", or "nestedness". Defaults to "all" which will display all metrics.
#' @param swapped_att Character. Name of swapped attribute.
#' @param all_nrow How many rows do you want the plot to have?
#' @param all_ncol How many columns do you want the plot to have?
#' @param font_family Font family to use in plots.
#' @param yaxis Vector of 2 integers. Lower and upper limit of y axis.
#' @param xaxis List of with element names matching plot types \(e.g. degree\). List contains length 2 vectors specifying x axis limits for plot of that type.
#' @param bin_num The number of bins you want in the histograms.
#'
#' @return A ggplot2 plot showing real vs simulated means
#' @export

Elements of a RO2 Template

Title
The first line of your template
Description
Anything between the @description tag and the next tag.
Arguments
Each argument needs it’s own @param tag.
Details
Anything between the @details tag and the next tag.
Return
Anything after the @returns tag
Examples
The rest of the template after the @examples tag.
Export
The end of every template should include the @export tag if you want users to find it

Special Formatting

The tags on the last slide are used to define sections in the help file.


There are also a few other special formatting tricks.

  • Ticks ` ` can be put around text to make look like code.
  • Square brackets [] can be put around the name of a function to link to the corresponding help file.
#' Title Here
#' 
#' @description
#' Here I describe the function
#' 
#' @param x What is x?
#' @param y What is y?
#' 
#' @details
#' Other details about the function
#' Similar to [sum()]
#' 
#' @returns The sum of `x` + `y`
#' 
#' @export
#' 
#' @examples
#' result <- my_func(1, 5)
my_func <- function(x, y){return(sum(x, y))}

A Note on Examples

While most sections of a help file are just text, the examples need to be actual R code that can be executed and must never error.


This presents a dilemma. Your example code needs to be both:

  • Complex are realistic enough to be helpful
  • Simple enough to be run with no side effects or complex dependencies.

This will work:

#' @examples
#' result <- my_func(1, 5)
my_func <- function(x, y){return(sum(x, y))}


These will break your entire package:

#' @examples
#' result <- my_func(1, "a")
#' result <- my_fish(1, 5)
my_func <- function(x, y){return(sum(x, y))}

Making the .rd Files

Once you have written your function and it’s documentation, you can use the devtools::document() function to convert your template into a real help page file.


devtools will automatically create a new file, format it, and add the function to your DESCRIPTION file so people can use it.


You have to remember to run it though! You can re-run it at any time to update changes.

Code-Along

For Next Time

Topic

Lab 6

To-Do

  • Finish Worksheet

SDS 270: Advanced Programming for Data Science