Creating packages

class: left, center, middle, inverse, title-slide

# Creating packages
## with devtools and usethis
### <a href="https://llrs.dev">Lluís Revilla Sancho</a> <a href="https://twitter.com/Lluis_Revilla"><svg viewBox="0 0 512 512" style="height:1em;position:relative;display:inline-block;top:.1em;" xmlns="http://www.w3.org/2000/svg"> <path d="M459.37 151.716c.325 4.548.325 9.097.325 13.645 0 138.72-105.583 298.558-298.558 298.558-59.452 0-114.68-17.219-161.137-47.106 8.447.974 16.568 1.299 25.34 1.299 49.055 0 94.213-16.568 130.274-44.832-46.132-.975-84.792-31.188-98.112-72.772 6.498.974 12.995 1.624 19.818 1.624 9.421 0 18.843-1.3 27.614-3.573-48.081-9.747-84.143-51.98-84.143-102.985v-1.299c13.969 7.797 30.214 12.67 47.431 13.319-28.264-18.843-46.781-51.005-46.781-87.391 0-19.492 5.197-37.36 14.294-52.954 51.655 63.675 129.3 105.258 216.365 109.807-1.624-7.797-2.599-15.918-2.599-24.04 0-57.828 46.782-104.934 104.934-104.934 30.213 0 57.502 12.67 76.67 33.137 23.715-4.548 46.456-13.32 66.599-25.34-7.798 24.366-24.366 44.833-46.132 57.827 21.117-2.273 41.584-8.122 60.426-16.243-14.292 20.791-32.161 39.308-52.628 54.253z"></path></svg></a> <br> <a href="https://ghana.llrs.dev">Slides:</a> <a href="https://github.com/llrs/ghana_packages/"><svg viewBox="0 0 496 512" style="height:1em;position:relative;display:inline-block;top:.1em;" xmlns="http://www.w3.org/2000/svg"> <path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"></path></svg></a>
### IDIBAPS, CIBEREHD
### 2021-09-04 <sup><sub>(updated: 2021-12-27)</sub></sup>

---

# About

.left[**myself**

I'm [Lluís Revilla Sancho](https://llrs.dev), a bioinformatician working on a research center of a hospital. 
Three packages on repositories: [BioCor](https://bioconductor.org/packages/BioCor/), [BaseSet](https://cran.r-project.org/package=BaseSet) and [experDesign](https://cran.r-project.org/package=experDesign).  
I have reviewed some packages on [rOpenSci](https://ropensci.org) and informally at [Bioconductor](https://bioconductor.org). 
]

.center[**you**

- ... know how to use R and write functions.  
- ... are using [RStudio IDE](https://www.rstudio.com/products/rstudio/download/).  
- ... have not created a package.  
- ... are using a computer with the latest [devtools](https://cran.r-project.org/package=devtools) installed.  
]

If you want to be sure run this code:

```r
if (!require("devtools", character.only = TRUE, quietly = TRUE)) {
  install.packages("devtools")
}
if (!require("covr", character.only = TRUE, quietly = TRUE)) {
  install.packages("covr")
}
```

???

[devtools](https://cran.r-project.org/package=devtools) is a package to help develop packages.
Currently many actions are done via [usethis](https://cran.r-project.org/package=usethis).
If you see something like `usethis::function` it means we call the `function` from usethis package.

---
name:resources

# Resources

- [R extensions](https://cran.r-project.org/doc/manuals/r-release/R-exts.html "Offical complete instructions"): Official documentation, everything is answered here
- [R packages](https://r-pkgs.org/ "R pakages"): A book more digestible and using other packages and tools to create packages.
- [Package primer](https://kbroman.org/pkg_primer/ "R package primer a minimal tutorial"): Website explaining different aspects of creating a package.
- [Creating R packages from scratch](https://hilaryparker.com/2014/04/29/writing-an-r-package-from-scratch/ "Creating a cats package"): Very easy to follow blog post.
- [Updated version by Tomas Westlake](https://r-mageddon.netlify.app/post/writing-an-r-package-from-scratch/ "Creating a cats package with usethis"): Similar to the post above but updated with more modern tools.
- [rOpenSci](https://devguide.ropensci.org/): A book  about writing packages and maintaining them on good shape.
- [Video](https://www.youtube.com/watch?v=IlWMkz769B4) with a similar workshop showing live the code used.

Many resources!

You can also find help online (always check the etiquette)
- Asking your local community
- [Asking on Twitter #rstats](https://www.t4rstats.com/)
- [Asking on Stack Overflow](https://stackoverflow.com/questions/5963269)
- [Asking on Rstudio forum](https://community.rstudio.com/)

???

Resources used to create this workshop

[Maëlle post](https://masalmon.eu/2017/12/11/goodrpackages/): how to write good packages is also recommended.

---

## Example

.left-column[

]

.right-column[
- `.github` folder: Files specific to GitHub (this isn't necessary/[Advanced content](#advanced))
- A `R` folder with [*.R files](#r-files): your code.
- A `man` folder with [*.rd files](#rd-files): your documentation.
- A `tests` folder: [Check the code](#tests) of the package.
- A [`vignette` folder](#vignettes): Long documentation; not just examples.
- A `.Rbuildignore`: A file describing what to omit when building the package.
- A [`DESCRIPTION` file](#description): Summary and description of the package.
- A [`LICENSE` file](#licenses): The conditions under the package is released.
- A [`NAMESPACE` file](#namespace): What this package shares and needs.
- A [`NEWS` file](#news): What has changed since last release.
- A [`README`](#readme): How to install and why this packages is needed and some basic examples.
]

---

## Template

.pull-left[

```r
create_package("dogs")
```

It will create a dogs project within the directory and will open a new Rstudio window.

]

.pull-right[
- Creates DESCRIPTION file
- Creates R files
- Creates documentation files
- Creates NAMESPACE file
]

.pull-left[
Suggestions for packages:

- fruits
- cats
- food
- sports
- ...
]

.pull-right[

![:scale 70% "Ghana market with cattle"](https://live.staticflickr.com/4041/4584360223_5ab315bfa4_b.jpg)
]
<div class="countdown" id="timer_61c9f755" style="top:0;right:0;margin:5%;" data-warnwhen="0">
<code class="countdown-time"><span class="countdown-digits minutes">01</span><span class="countdown-digits colon">:</span><span class="countdown-digits seconds">30</span></code>
</div>

---
name: description

## DESCRIPTION

.pull-left[
```
Package: BaseSet
Title: Short Descriptiono in Title Case
Version: 0.0.9000
Authors@R: c(person(given = "Lluís",
             family = "Revilla Sancho",
             role = c("aut", "cre", "cph"),
             email = "lluis.revilla@gmail.com"),
             ...)
Description: A long description of the pacakge
License: MIT + file LICENSE
Depends: 
    R (>= 4.0.0)
Imports: 
    dplyr (>= 1.0.0),
    methods
Suggests: 
    covr,
    knitr,
    rmarkdown,
    spelling,
    testthat (>= 2.1.0)
VignetteBuilder: 
    knitr
Encoding: UTF-8
Language: en-US
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.1.1
```
]

???
Name of the package, description of the package, maintainer, relationships with other packages...
Language does not need to be on English, it can be in other languages
--

.pull-right[
Modify the DESCRIPTION of your package.

- Add a good title.
- Add a Description.
- Add yourself as an author.

]

---
name:r-files

## Add R files

On the new package R console run:

```r
usethis::use_r("dog_functions")
```

It will create a `dog_functions.R` file inside the R folder (and it will open it).

.center[
![:scale 50% "GIF of hadly wickham saying just typing R code"](https://c.tenor.com/pnK2MIoEAccAAAAC/hadley-wickham.gif)
]

---

## Add R files

1. Only valid R code: functions, objects, environments that don't depend on previous code executed. 
2. If a function uses a function of an other package use `package::function`
    3. Add that package to the appropriate site on [Description](#description)
    4. add a `#' @importFrom package function` (See next slide)

```r
meow <- function() {
    message("meow")
}
```
<div class="countdown" id="timer_61c9f8dd" style="top:0;right:0;" data-warnwhen="0">
<code class="countdown-time"><span class="countdown-digits minutes">03</span><span class="countdown-digits colon">:</span><span class="countdown-digits seconds">00</span></code>
</div>

---
name:namespace
## NAMESPACE

Import code of other packages and export code of your package:

```r
import(dplyr)
importFrom(methods, is)
export(meow)
```

If using roxygen2 you can use:

```r
#' @import dplyr
#' @importFrom methods is
is_meow <- function(x){
    methods(x, "meow")
}

#' @export # To make it available to others
meow <- function() {
    message("meow")
} 
```

Which will be written to the NAMESPACE file when [updating the documentation](#rd-files)

???
Important file!

---
name:readme
## Documentation

### README

First page people might read if on Github or on a computer.

```r
usethis::use_readme_rmd() # build_readme()
```

Example README:
<img src="images/data.table_README.png" width="2531" />

Modify README:

---
name:rd-files

## Documentation

### Function documentation

.pull-left[
Using [roxygen2](https://cran.r-project.org/package=roxygen2), example:

```r
#' Title
#'
#' Description
#' @param x 
#'
#' @return Values returned
#' @export
#'
#' @examples
#' a("hi")
a <- function(x) {
  print(x)
}
```
]

.pull-right[
Convert this specials comments into *.Rd files with:
```r
document()
```
]

???

In Rstudio you can insert the skeleton with <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Shift</kbd>+<kbd>R</kbd> .
In Rstudio you can convert the special comments into documentation with <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>D</kbd> .

.center[Write your own documentation]

---
name: vignettes

## Documentation

### Vignettes

Long form of documentation, how multiple functions work together (It can use functions of other packages)

```r
usethis::use_vignette(name = "intro")
```

Write your own vignette:
- Fruits growing
- Dogs/cats exploring the house or the neighborhood
- A match of your sport
- ...

---
name: tests

## Tests

Make sure that what you think it happens it really stays that way:
Can be quite complicated

```r
use_testthat()
use_test("meow")
```

.pull-left[
Change from:

```r
test_that("multiplication works", {
  expect_equal(2 * 2, 4)
})

```
]

.pull-right[

To (**If** you used the [meow function](#namespace)): 
```r
test_that("mewo works", {
  expect_message(meow(), "meow")
})
```

]

--
<div class="countdown" id="timer_61c9f927" style="top:0;right:0;" data-warnwhen="0">
<code class="countdown-time"><span class="countdown-digits minutes">03</span><span class="countdown-digits colon">:</span><span class="countdown-digits seconds">00</span></code>
</div>

---
name:licenses
## Licenses

If sharing the package what can people do with your package?

- **Permissive** licenses: Code with a permissive license can be freely copied, modified, and published, and the only restriction is that the license must be preserved.

- **Copyleft** licenses: if you publish modified versions or bundle with other code, the modified version or complete bundle must also be licensed with the same license.

```r
usethis::use_mit_license() # Permissive
usethis::use_gpl_license() # Copyleft
usethis::use_proprietary_license() # Own license
```

.right[<sup>[Source](https://r-pkgs.org/license.html)</sup>]

???

---
name: news

## NEWS

Sharing what changed between releases

```r
usethis::use_news_md()
```

The file has this structure:

```raw
 # dogs 0.0.0.9000

* Added a `NEWS.md` file to track changes to the package.

```

Version of the package

Text describing changes on the packages. 
It is a good place to acknowledge minor contributions

???
Modify to explain the changes.
Good idea to use - (#issue, `@user`)

---
## Finishing and checking

Check if everything works well! It can take some time.

```r
check()
```

It should pass without Warnings or Errors. 
If not (most probable) fix the problems found

???
Automatically runs the test and checks the package compilance with common quality standards

---

## That's all

.center[
![:scale 60% "That's all folks"](https://media.giphy.com/media/lD76yTC5zxZPG/giphy.gif)
]

---

## Developing your package

- [Modify or add](#r-files) more *.R files to the R folder
- [Add or change function's documentation](#rd-files) and [vignettes](#vignettes) and update it (`document()`)
- Check the package (`check()`)
- Repeat.

---
## Questions, doubts, comments?

- It is normal to not succeed on the first 5-10 attempts!!
- Search, ask whenever you need.

Thanks for following through it.

![:scale 40% ""](https://media1.giphy.com/media/f2HiQKaEkaKwo/giphy.gif?cid=ecf05e475uwtpser5kqd7t5pwoz8vdrrkbp817x708vdb4ci&rid=giphy.gif&ct=g)
???

---
name:advanced
# Advanced

## Git

Set up git as a control version system. This allows to share on [GitHub](https://github.com).
To set it up use:

```r
usethis::use_git()
```

???
Version controls helps you to modify code securely and interact with others (and receive their suggestions).

---
# Advanced
## Github

Share the package on Github:

```r
usethis::use_github()
```

Add checks

```r
usethis::use_github_action_check_release()
```

Use the git panel of Rstudio to commit and push updates on the package.

???

Having a package public on github can help on your CV and to get users.

---
# Advanced
## Code coverage

Report how much of the package is tested.

```r
usethis::use_coverage()
```

It can be done offline on your computer `covr::report()` but usually also reported online.

???
Aim to have high code coverage (above 75%). 
High code coverage prevents your users (and yourself) to push changes that do not work.

---
# Advanced
## Pkgdown website

Now that the package is working and public, a website makes it easier for users to find documentation.

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

???

It is also great for publicity, so others can read and learn about your package without installing it.