R Packages Dissemination

background-image: url("img/logo_padded.001.jpeg")
background-position: left
background-size: 60%
class: middle, center,

<br>

## .base_color[R Packages]
 
## .base_color[Dissemination] 
 
<br>

#### .navy[Kelly McConville]

#### .navy[ Stat 108 | Week 11 | Spring 2023]

]

---

## Announcements

* Changes to OHs for this week.  [Make sure to check the schedule.](https://docs.google.com/spreadsheets/d/1HqEmr4tEtFPWRrF5TJHd1VgtVD030w6aAYySoFTnhBw/edit?usp=sharing)
* No lecture next Wed, April 19th.  Project 2 OHs in 316 instead.
* Don't forget to fill out:
    + By April 14th: [Project 1 Group Work Form](https://forms.gle/C2iFjTo3Ww1CMsFy5)

************************

## Week's Goals

**Mon Lecture**

* Testing

]

**Wed Lecture**

* Discuss Project 2
* Extended documentation via vignettes
* Package dissemination via `pkgdown`

]

---

## Let's go through the Project 2 instructions.

---

### Project 2

In this project, your group will create an `R` package and give a 5 minute presentation about your package. You have two options for your package:

* Option 1: a package that primarily shares a suite of functions but also includes data for demoing functionality.
* Option 2: a package that primarily shares a dataset or dataset(s) but also includes a couple functions that help the user interact with the data effectively.

---

### Project 2

#### Requirements specific to Option 1:

* At least 4 functions.
* At least 8 tests.
* A dataset for demonstrating how to use the functions in the package.
    + There are no requirements on the size of the dataset.
* A 400 - 800 word vignette with at least 1 example that showcases a problem that your package is designed to solve.
    + Note: It is completely fine to use additional packages and functions in the vignette.

]

#### Requirements specific to Option 2:

* A dataset with at least 8 variables and at least 30 observations.
* At least 2 functions, such as ones that carry out common operations of interest on the dataset.
    + At least 1 of these functions should create a polished, well-constructed graph.
* At least 2 tests.
* A 600 - 1000 word vignette with at least 3 examples that showcase the questions you can answer with the provided dataset and functions.
    + Note: It is completely fine to use additional packages and functions in the vignette.

]

---

### Project 2

#### Requirements for Both Options:

* Package contains 
    + A complete and informative `DESCRIPTION` file.
    + A Readme (both the `Rmd` and `md`) which answers the questions: Why should I use this package? How do I access the package? How do I use the package?
        + The Readme should include 1-2 brief examples. Place more extended examples in the vignette.
        + The Readme should be about  400-800 words in length.
    + An R documentation file for each function and each dataset.
    + A reasonable name that is not already in use on CRAN or GitHub.  
        + Don't use `pkgDemo` or `project2-groupXXX`.
        + Helpful tip: Nick Tierney's [blog post](https://www.njtierney.com/post/2017/10/27/change-pkg-name/) walks through how to change a package name.
* A five minute presentation about the package.  Similar to the Readme, the presentation should motivate the viewer to use the package and should include an example of how to use the package.
* A `data-raw` folder for handling data wrangling.
* A `data` folder for holding the finalized dataset.

#### Extra Credit

* A hex sticker that contains the package name and a design that relates to the package in some way.

---

### Project 2

#### R Package Ideas

* Functions for learning the concepts in Stat 111, Stat 100, or some other course.
* Functions that facilitate common tasks you do in your research.
* Functions that pull open data and allow the user to easily create useful visuals and compute relevant summary statistics.
* Functions that pull in data from an API and then convert the data into useful `R` objects, like `data.frame()`s.
* Wrapper functions for common, useful tasks.
* Wrapper functions for cumbersome, difficult to use functions.

---

### Project 2

#### Tips for getting started

* As a group, brainstorm ideas and decide whether you want to focus more on functions (Option 1) or data (Option 2) in your package.
* Remember to use class resources:
    + The Week 10 & Week 11 lecture slides
    + The [Creating an R Package handout](https://canvas.harvard.edu/courses/117625/files/17239697?module_item_id=1366379) which outlines the initial steps.
    + The [`camDogs` package](https://github.com/harvard-stat108s23/camDogs) we live-coded in lecture.  (Note: `camDogs` is still mostly the skeleton of a package.)
* Check out well-written and well-documented `R` packages.  Here are some examples:
    + [https://reprex.tidyverse.org/](https://reprex.tidyverse.org/) and the [`reprex` GitHub repo](https://github.com/tidyverse/reprex)
    + [https://glue.tidyverse.org/](https://glue.tidyverse.org/) and the [`glue` GitHub repo](https://github.com/tidyverse/glue)
    + [https://allisonhorst.github.io/palmerpenguins/](https://allisonhorst.github.io/palmerpenguins/) and the [`palmerpenguins` GitHub repo](https://github.com/allisonhorst/palmerpenguins)
* Regardless of the state of your package on April 17th, consider stopping by Prof McConville's 9 - 10:15am office hours in SC 316 to talk through your ideas and eat pastries.
* Create a `sandbox` folder and add it to the `.Rbuildignore`.  Use this folder for exploring different ideas and creating MVPs.

---

### Project 2

#### Timeline

* 4/12: Receive project instructions, [group assignment](https://docs.google.com/spreadsheets/d/1xU3w4sXQSWkU678YjtdnjyBZOuB6RtFiZeB4fbsZozo/edit?usp=sharing), and invite to your group's GitHub repo.
    + Please use your assigned Stat 108 GitHub repo for this project.
* 4/19: 9 - 10:15am: Lecture is cancelled.  Package office hours and pastries in SC 316.
* 4/19: As a group, come up with three potential names and a short description of your package.  Add this information to the [potential package names spreadsheet](https://docs.google.com/spreadsheets/d/1N63gjVFeHMdkUCENOsfVFKFE0aIT4jYVGcqQ81ZVXh0/edit?usp=sharing).
* 4/20 - 4/22: Package naming peer feedback activity
    + More guidance on providing feedback will be given in lecture that week.
    + Part of section time that week will be devoted to feedback activity.
* 5/8 - 5/10: Give a 5 minute presentation of your package in one of the following time slots:
    + Monday, May 8th noon - 2pm
    + Wednesday, May 10th 9 - 11am
* 5/10 (noon): Make sure the final version of your package is in your GitHub repo.
* 5/10: Decide as a group whether or not you want to make your GitHub repo (and so `R` package) public.  
    + If at least one group member does not want to make the repo public, please leave it private.
    + Your grade on this project does not at all depend on this decision.

#### Make sure to check out the Project 2 instructions for the detailed rubric!

---

## Recap Our Package: `camDogs`

* Share the [Dogs of Cambridge dataset](https://data.cambridgema.gov/General-Government/Dogs-of-Cambridge/sckh-3xyx), along with documentation.
* Includes, `top10()`, a function that outputs a dataset of the dogs with the 10 most common names.
* Working copy can be found at [https://github.com/harvard-stat108s23/camDogs](https://github.com/harvard-stat108s23/camDogs)
* I added one more test:

```r
test_that("Less than or equal number of rows in the filtered dataset", {
  expect_lte(nrow(top10(camDogs, Dog_Name)), nrow(camDogs))
})
```

#### Other questions so far?

---

## Vignettes

*"The vignette format is perfect for showing a workflow that solves that particular problem, start to finish. Vignettes afford you different opportunities than help topics: you have much more control over the integration of code and prose and it’s a better setting for showing how multiple functions work together." -- Hadley Wickham and Jenny Bryan

```r
browseVignettes()
```

---

### Vignettes Set-up

To get started, run:

```r
usethis::use_vignette("camDogs")
```

Which

* Creates the `vignettes` folder.
* Updates the `DESCRIPTION` with new dependencies.
* Provides a template in the file `camDogs.Rmd`.
* Updates your `.gitignore`.

---

### Vignettes Workflow

* Run `devtools::load_all()` to make sure you have access to the data and functions in the package.
* Edit the narrative and code chunks.
* To render the vignette using a temporarily installed, development version of your package, run

```r
devtools::build_rmd("vignettes/camDogs.Rmd")
```

* Inspect the output file.
* Repeat!

---

### Vignettes Workflow

Eventually,

* To make the current state available locally with an install of the package:

```r
devtools::install(dependencies = TRUE, build_vignettes = TRUE)
```

* Make the vignettes available when people install from GitHub:

```r
devtools::install_github(dependencies = TRUE, build_vignettes = TRUE)
```

* If you want to build your vignettes as part of a CRAN submission:

```r
devtools::submit_cran()
```

---

### The Vignette's YAML

```r
---
title: "Introduction to `camDogs`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to `camDogs`}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---
```

---

### Provided Vignette Chunks

````default
```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```
````

````default
```{r setup}
library(camDogs)
```
````

---

### Suggestions for Writing a Good Vignette

* Think of your vignette as an instructive tutorial.
* First, identify (for yourself) what you want the vignette to accomplish.
* Be careful with the curse of knowledge.
* Break up the code with concise but clear narrative that motivates the next block of code.
* Hyper-link to other relevant packages and functions.

#### Important Note

* Any package used in a vignette must be listed in the `DESCRIPTION` file under either `Imports` or `Suggests`.

---

## Website for Your Package with `pkgdown`

---

### Create the Site

Run:

```r
usethis::use_pkgdown()
```

* Creates `pkgdown.yml`: The configuration file for your package.
* Adds the correct files to the `.Rbuildignore`.
* Creates the `docs` folder which will store all the pages for the website.

---

### Build the Site

To create the site, run:

```r
pkgdown::build_site()
```

* The site is only as good as the documentation included in your package.  
    + But, if you have created useful help files, an informative Readme, a complete `DESCRIPTION` file, and a vignette, then your default `pkgdown` site will be pretty great!

---

### Deploy the Site

To set it up so that your site can be published to a GitHub pages, run (just once):

```r
usethis::use_pkgdown_github_pages()
```

* Creates a branch in GitHub that will store the files for your website.
* Turns on GitHub Pages for your repo
    + Let's GitHub know where to find the files for the website.
* Adds the URL for the site to the appropriate files.

---

### Deploy the Site

**Big Wrinkle**: Can't deploy on our private GitHub Organization.

* Have to deploy through a repo tied to your individual account:
    + [https://mcconvil.github.io/camDogsTest/](https://mcconvil.github.io/camDogsTest/)

* Requires changing a GitHub Action setting!

* Not a requirement of Project 2!

---

### Hex Sticker

<br>

* A strong tradition in the `R` community.

* Fun way to remember and advertise a package.

]

]

<br>

* But there are rules...

]

]

---

## `RMarkdown` Websites

---

### Three Flavors of `RMarkdown` Websites

* [A simple `RMarkdown` website](https://rmarkdown.rstudio.com/lesson-13.html)
    + [Our class slides](https://mcconvil.github.io/stat108s23/)
    + [Workshop](https://mcconvil.github.io/IMS21_ML_Surveys/) and [its corresponding GitHub repo](https://github.com/mcconvil/IMS21_ML_Surveys)
    
* [A `distill` website](https://rstudio.github.io/distill/website.html)
    + [My personal website](https://mcconville.rbind.io/)
    + [Lots of better examples](https://distillery.rbind.io/)
    
* [A `blogdown` website](https://bookdown.org/yihui/blogdown/)
    + [Alison Hill's website](https://www.apreshill.com/)
    
    
* And then there's always [`quarto`](https://quarto.org/docs/websites/)...