presentation.qmd

---
title: "R packages"
author: "Ed Burn"
format:
  revealjs: 
    theme: [simple, custom_1.scss]
    incremental: true   
    slide-number: true
    chalkboard: true
    preview-links: auto
    margin: 0.07
    code-link: true
    code-line-numbers: false
    height: 900
    width: 1600
execute:
  echo: true
  eval: true
editor: visual
---

# The PenguinSummary package

## Penguins data

The from [palmerpenguins package](https://allisonhorst.github.io/palmerpenguins/) contains data on penguins collected from the [Palmer Station](https://en.wikipedia.org/wiki/Palmer_Station) in Antarctica.

![](images/lter_penguins.png){width="300"}

*Artwork by \@allison_horst*

## Penguins data

```{r, eval=FALSE}
install.packages("palmerpenguins")
```

<br/>

. . .

```{r, message=FALSE}
library(palmerpenguins)
library(dplyr)

glimpse(penguins)
```

## Summarising measurements

```{r}
penguins %>% 
  group_by(species, sex) %>% 
  summarise(min=min(body_mass_g, na.rm=TRUE),
            median=quantile(body_mass_g, 0.5, na.rm=TRUE),
            max=max(body_mass_g, na.rm=TRUE)) %>% 
  head(2)
```

<br/>

. . .

```{r}
penguins %>% 
  group_by(species, sex) %>% 
  summarise(min=min(flipper_length_mm, na.rm=TRUE),
            median=quantile(flipper_length_mm, 0.5, na.rm=TRUE),
            max=max(flipper_length_mm, na.rm=TRUE)) %>% 
  head(2)
```

## Function with one argument

```{r}
measurement_summary<-function(var){

penguins %>% 
  group_by(species, sex) %>% 
  summarise(min = min({{ var }}, na.rm=TRUE),
            median = quantile({{ var }}, 0.5, na.rm=TRUE),
            max = max({{ var }}, na.rm=TRUE))
}
```

<br/>

. . .

```{r}
measurement_summary(body_mass_g) %>% head(2) 
```

. . .

```{r}
measurement_summary(flipper_length_mm) %>% head(2)
```

## Function with multiple arguments

```{r}
measurement_summary<-function(data, var, groupings=c("species", "sex")){
data %>% 
  group_by(across(groupings)) %>% 
  summarise(min = min({{ var }}, na.rm=TRUE),
            median = quantile({{ var }}, 0.5, na.rm=TRUE),
            max = max({{ var }}, na.rm=TRUE))
}
```

<br/>

. . .

```{r}
measurement_summary(data=penguins, var=body_mass_g) %>% head(2) # groupings used will be defaults
```

<br/>

. . .

```{r}
measurement_summary(data=penguins, var=body_mass_g, groupings = "island") %>% 
  head(2) 
```

## Time to make a package?

Makes it easier to reuse functions

<br/>

. . .

Provides a consistent framework which encourages better organisation, documentation and testing of codes

<br/>

. . .

Consistent framework means we can use many standardised tools

## Packages to help us to create a package

```{r, eval=FALSE}
install.packages("usethis")
install.packages("testhat")
install.packages("devtools")
install.packages("roxygen")
```

![](images/rbanner_medium-900x250.png)

## Create an empty package

```{r, eval=FALSE}
usethis::create_package("PenguinSummary")
```

## Workflow

```{r, eval=FALSE}
devtools::load_all()
devtools::check()
```

## Add a function

```{r, eval=FALSE}
usethis::use_r("measurement_summary")
```

<br/>

. . .

```{r, eval=FALSE}
measurement_summary<-function(data, var, groupings=c("species", "sex")){
  data %>%
    group_by(across(.env$groupings)) %>%
    summarise(min = min(!!!syms(var), na.rm=TRUE),
                     median = quantile(!!!syms(var), 0.5, na.rm=TRUE),
                     max = max(!!!syms(var), na.rm=TRUE))
}
```

## Adding dependencies

```{r, eval=FALSE}
usethis::use_pipe()
usethis::use_package("dplyr")
```

## Check

```{r, eval=FALSE}
devtools::load_all()
devtools::check()
```

## Specifying dependencies

```{r}
measurement_summary<-function(data, var, groupings=c("species", "sex")){
  data %>%
    dplyr::group_by(dplyr::across(groupings)) %>%
    dplyr::summarise(min = min({{ var }}, na.rm=TRUE),
                     median = stats::quantile({{ var }}, 0.5, na.rm=TRUE),
                     max = max({{ var }}, na.rm=TRUE))
}
```

## Data masking

```{r, eval=FALSE}
measurement_summary<-function(data, var, groupings=c("species", "sex")){
  data %>%
    dplyr::group_by(dplyr::across(.env$groupings)) %>%
    dplyr::summarise(min = min({{ var }}, na.rm=TRUE),
                     median = stats::quantile({{ var }}, 0.5, na.rm=TRUE),
                     max = max({{ var }}, na.rm=TRUE))
}
```

<br/>

. . .

<https://youtu.be/SW_TUkPXSmA>

## Check

```{r, eval=FALSE}
devtools::load_all()
devtools::check()
```

<br/>

. . .

```{r, eval=FALSE}
usethis::use_package("rlang")
usethis::use_import_from("rlang", c(".data", ".env"))
```

## Does it work?

```{r, eval=FALSE}
library(palmerpenguins)
library(dplyr)

measurement_summary(penguins,var=body_mass_g)
```

<br/>

. . .

It works?

<br/>

. . .

![](images/index-01.png){fig-align="center" width="230"}

![](images/simpsons-homer-01.gif){fig-align="center" width="380"}

## Informative errors

```{r, eval=FALSE}
library(palmerpenguins)
library(dplyr)

measurement_summary(penguins,var=sex)
```

## Informative errors

```{r, eval=FALSE}
measurement_summary<-function(data, var, groupings=c("species", "sex")){

  errorMessage <- checkmate::makeAssertCollection()
  data_check<-any(class(data) %in%
                    c("tbl_df", "data.frame"))
  checkmate::assertTRUE(data_check, add =errorMessage)
  if (!isTRUE(data_check)) {
    errorMessage$push(glue::glue("- {data} is not a tibble or dataframe"))
  }
  var_check <- all(var %in%
                     c("bill_length_mm", "bill_depth_mm",
                       "flipper_length_mm", "body_mass_g"))
  checkmate::assertTRUE(var_check, add =errorMessage)
  if (!isTRUE(var_check)) {
    errorMessage$push(glue::glue("- {var} is not a variable to summarise"))
  }

  groupings_check <- all(groupings %in%
                     c("species","island",
                       "sex" ,"year"))
  checkmate::assertTRUE(groupings_check, add =errorMessage)
  if (!isTRUE(groupings_check)) {
    errorMessage$push("- not all groupings are variables to group by")
  }
  checkmate::reportAssertions(collection = errorMessage)

  data %>%
    dplyr::group_by(dplyr::across(.env$groupings)) %>%
    dplyr::summarise(min = min(!!!rlang::syms(var), na.rm=TRUE),
                     median = stats::quantile(!!!rlang::syms(var), 0.5, na.rm=TRUE),
                     max = max(!!!rlang::syms(var), na.rm=TRUE))
}
```

## Informative errors

```{r, eval=FALSE}
library(palmerpenguins)
library(dplyr)

measurement_summary(penguins,var="sex")
```

## Documenting the function

```{r, eval=FALSE}
usethis::use_package("checkmate")
usethis::use_package("glue")
```

<br/>

. . .

```{r, eval=FALSE}
#' Measurement summary
#'
#' @param data penguins data
#' @param var variable to summarise
#' @param groupings variables to group by
#'
#' @return tibble with summary
#' @export
#'
#' @examples
measurement_summary<-function(data, var, groupings=c("species", "sex")){

  errorMessage <- checkmate::makeAssertCollection()
  data_check<-any(class(data) %in%
                    c("tbl_df", "data.frame"))
  checkmate::assertTRUE(data_check, add =errorMessage)
  if (!isTRUE(data_check)) {
    errorMessage$push(glue::glue("- {data} is not a tibble or dataframe"))
  }
  var_check <- all(var %in%
                     c("bill_length_mm", "bill_depth_mm",
                       "flipper_length_mm", "body_mass_g"))
  checkmate::assertTRUE(var_check, add =errorMessage)
  if (!isTRUE(var_check)) {
    errorMessage$push(glue::glue("- {var} is not a variable to summarise"))
  }

  groupings_check <- all(groupings %in%
                     c("species","island",
                       "sex" ,"year"))
  checkmate::assertTRUE(groupings_check, add =errorMessage)
  if (!isTRUE(groupings_check)) {
    errorMessage$push("- not all groupings are variables to group by")
  }
  checkmate::reportAssertions(collection = errorMessage)

  data %>%
    dplyr::group_by(dplyr::across(.env$groupings)) %>%
    dplyr::summarise(min = min(!!!rlang::syms(var), na.rm=TRUE),
                     median = stats::quantile(!!!rlang::syms(var), 0.5, na.rm=TRUE),
                     max = max(!!!rlang::syms(var), na.rm=TRUE))
}
```

## Testing

```{r, eval=FALSE}
usethis::use_test("measurement_summary")
```

## Testing

```{r, eval=FALSE}
test_that("check summary", {
  library(palmerpenguins)
  result <- measurement_summary(penguins,
                                var="bill_length_mm",
                                groupings=c("species"))
  expect_true(all(names(result) == c("species", "min", "median","max")))

  expect_error(measurement_summary(penguins,
                                   var="bill_length_mm",
                                   groupings=c("not_a_grouping")))
})
```

## Testing

```{r, eval=FALSE}
detach("package:PenguinSummary", unload=TRUE)
devtools::test_coverage()
```