index.qmd

---
title: "Developing R packages"
subtitle: "OECD Stats Day 2023"
author: 
  - name: "María Paula Caldas"
    affiliation: 
      - "Economics Department"
      - "R/Python/Algobank CoP"
# code-line-numbers: false
format: 
  revealjs:
    incremental: false
    theme: [simple, custom.scss]
    css: custom.css
    slide-number: true
    # footer: "<https://mpaulacaldas.github.io/oecd-r-pkg-dev>"
    # logo: www/SYMBOL_20cm.png
workshop:
  slides: https://mpaulacaldas.github.io/oecd-r-pkg-dev
  project: https://posit.cloud/content/7235458
execute: 
  eval: false
  echo: true
knitr: 
  opts_chunk: 
    collapse: true
    comment: "#>" 
---

## Useful links

\

{{< fa link >}} Slides

<https://mpaulacaldas.github.io/oecd-r-pkg-dev>

{{< fa folder-open >}} Posit Cloud Project

<https://posit.cloud/content/7235458>


# Introduction {background-color="#2a2e45ff"}

Motivation and prerequisites

## What is an R package? 

A package bundles together **code**, **data**, and **documentation** in a 
format that is **easy to share with others**

```{r}
#| code-line-numbers: "|1-2|6-8|10-12|14-16"
#| label: ggplot2-example
#| eval: false
# R makes it easy to install and use packages from CRAN or other repositories
install.packages("ggplot2")

library(ggplot2)

# Some packages contain data, which can be documented
data(package = "ggplot2")
?ggplot2::diamonds

# Beyond object documentation, packages can include short articles to 
# describe broader functionality
vignette("ggplot2-specs")

ggplot(diamonds, aes(x, y)) + 
  geom_bin_2d(show.legend = FALSE) +
  scale_y_log10()
```

## Why package your R code?

It's easy for users! 

::: {.incremental}
  - Most already know `install.package()` and `library()`
  - `{remotes}` makes it easy to install and build packages hosted on 
    code sharing platforms
  - You can publish packages to CRAN, to the [r-universe](https://r-universe.dev/) 
    or to internal package repositories (e.g. 
    [Sonatype Nexus](https://www.sonatype.com/products/sonatype-nexus-repository),
    coming to the OECD)
:::

## Why package your R code?

As a developer, adopting a package infrastructure helps you __iterate faster__ 
and create __more robust code__

::: {.incremental}
- Clearly stating your dependencies
- Separating development from deployment
- Providing a framework to create unit tests and do automated checks
- Giving the ability to version your releases
:::

## Why package your R code?

It gives you a set of tools to help people __understand__ your code and learn
how to __interact__ with it.

::: {.incremental}
- Concise documentation of functions, data and examples
- Vignettes, for long-form documentation
- Automatically create package websites with `{pkgdown}`
- Conventions to communicate `NEWS.md` and for `CONTRIBUTING.md`
:::

## What do you need to start building R packages?

- Be curious and willing!
- Enough {{< fa brands r-project >}} to create a function
- {{< fa brands git size=lg >}} is not a must, but a very nice-to-have
- Some markdown, to write documentation

# Let's create a package {background-color="#2a2e45ff"  background-image="https://usethis.r-lib.org/logo.png" background-size="150px" background-position="1050px 50px"}

\ 

{{< fa folder-open >}} Posit Cloud Project

<https://posit.cloud/content/7235458>

## [1]{.circle} Set-up the basic infrastructure

::: {.notes}
Let's load `{usethis}` and `{devtools}` into your global environment. These are 
**workflow** packages. They are used interactively during package development.
:::

\

```{r}
library(usethis)
library(devtools)

create_package("location-i-want/mypackage")
```

::: {.incremental}

- What happens when you run `create_package()`?
- What files do you see?
- Open the `DESCRIPTION` file and edit some fields
- Run `devtools::check()` What do you see?

:::

## [2]{.circle} Create a function, and use it!

\

::: {.incremental}

- Open a file to write your function
  ```{r}
  use_r("name-of-your-file")
  ```

- Write a small function
  ```{r}
  #| code-fold: true
  #| code-summary: "If you need a little inspiration"
  #| label: year-progress
  year_progress <- function(date, is_leap_year = FALSE) {
    nominator   <- as.numeric(format(date, "%j"))
    denominator <- if (is_leap_year) 366 else 365
    share <- round(nominator * 100 / denominator)
    message(share, "% of the year is done!")
  }
  ```
- When you are done, go to the __Console__ and type `devtools::load_all()`
  Press ENTER. What happens?

:::

## [3]{.circle} Document

\

::: {.incremental}
- Place your cursor in the body of your function
- Navigate to __Code > Insert Roxygen Skeleton__ 
- Fill the documentation, and save
- In the console, run `devtools::document()`
- See the documentation you just wrote with `?yourfun`
:::

## Internal vs. exported functions

::: {.notes}
When you add a Roxygen Skeleton to a function, it will automatically generate 
an `@export` tag
:::

- __`@export` identifies user-facing functions__ i.e. functions available to 
  your users when they load your library, or call a function with `::`

  ```{r}
  #| eval: false
  usethis::create_package
  ```

- __Other functions are internal__, there to help you break down your logic 
  into smaller functions that are easier to test, but which may not be of 
  interest to users

  ```{r}
  # eval: false
  usethis:::user_path_prep
  ```

## [4]{.circle} Test

\

__Unit tests__ are deliberate tests we perform whilst developing a package 
to _monitor_ the correct functioning of our code

::: {.incremental}

- What would make a good unit test for the function below?
  ```{r}
  #| ref.label: year-progress
  #| echo: true
  #| eval: false
  #| code-fold: false
  ```
- Create a test with `use_test()` and test it with `test()`

:::

## [5]{.circle} Install

\

The final step before deployment is to __install__ your package

```{r}
install()
```

If you are sharing with users, also consider increasing its __version__,  and 
documenting the main changes in the `NEWS.md` file.

```{r}
use_news_md()
use_version()
```

::: {.incremental}
- Let's see how [we deploy packages in ECO](https://gitlab.algobank.oecd.org/ADB/adbthis/-/blob/PROD/_deploy.R?ref_type=heads)
:::

## Sharing with other developers

\

:::: {.columns}

::: {.column}
`{usethis}` makes it easy to set up __version control__
```{r}
use_git()
use_github()
```
:::

::: {.column}
`{oecdthis}` aims to do the same for OECD staff

```{r}
use_git()
use_algobank()
```
:::

::::

::: {.aside}
_oecdthis_ is currently under development by Matthew de Queljoe and 
Maria Paula Caldas
<https://gitlab.algobank.oecd.org/rpythonalgobank/oecdthis>
:::

# Lessons {background-color="#2a2e45ff"}

## What has been the experience in ECO?

\

The __[ECO Data Platform](https://adbportal.oecd.org/edp/index.aspx)__ is an 
ambitious IT project to migrate core databases and programs into 
open-source, code-first solutions.

A key part of this platform includes __an ecosystem of R packages__, helping 
statisticians and analysts connect, curate and interact with our databases


## What has been the experience in ECO? {.smaller}

\

### Advantages of using packages

- Better __documentation__ and __examples__ to statisticians
- Better __versioning__ of code and deployment cycles.
- Reducing __dependencies__ and NAMESPACE conflicts in analysis code

### Where we are trying to improve

- Defining a framework for governance and maintenance
- Upskilling staff in Git, R and good practice

# Thank you! {background-color="#2a2e45ff"}
Any questions?