Skip to content

Edits to all chapters for consistency #17

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ellessenne merged 6 commits into from
Aug 19, 2025
Merged

Edits to all chapters for consistency #17

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
869e8f7
Edits to all chapters for consistency
ellessenne Aug 19, 2025
68475b3
Adjusted knitr engine
ellessenne Aug 19, 2025
080cd73
Licence -> license
ellessenne Aug 19, 2025
4074820
Updated index page with tools to compile packages from source code
ellessenne Aug 19, 2025
896205c
Merge branch 'main' into consistency-checks
ellessenne Aug 19, 2025
776f9ed
Harmonised changes in chapter 6
ellessenne Aug 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion index.qmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ Prior to the short course, participants should
- Set up a (free) [GitHub.com account](https://github.com/join).
- Note: There are other git platforms like [Gitlab](https://about.gitlab.com/) or [Bitbucket](https://bitbucket.org/), but we made the choice to go with GitHub.com for the course, since it is by far the most relevant git platform in the R community.
- Install the latest [R](https://www.r-project.org/) and [RStudio](https://posit.co/download/rstudio-desktop/) software.
- Install [Rtools](https://cran.r-project.org/bin/windows/Rtools/rtools44/rtools.html) (only on Windows and optional if you want to try out Rcpp)
- Install [Rtools](https://cran.r-project.org/bin/windows/Rtools/rtools44/rtools.html) (on Windows) or the [required tools](https://mac.r-project.org/tools/) (on macOS) to compile/build packages from source code.
- Install additional R packages using the [installation script](slides/download/install.R).

For the course, participants are required to use their own laptop to be able to participate in the exercises.
Expand Down
16 changes: 7 additions & 9 deletions slides/01_intro.qmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,12 @@ author: Audrey T. Yeo
{{< include _disclaimer.qmd >}}


## Welcome to GSWEP4R at the ISCB46 !
## Welcome to GSWEP4R at ISCB46!

\
\

_We have an open source spirit here. Please sit with someone you do not already know_
_We have an open source spirit here. Please sit with someone you do not already know._


\
Expand All @@ -33,7 +33,7 @@ Be Curious. Be Respectful. Be Kind.
::: {.column width="70%"}
- M Sci Biostatistics (Zurich), M Nursing (Sydney)
- Currently : Founder of [Finc-Research](https://finc-research.com)
- Previously : Master Thesis in Longitudinal Cluster Analysis, Biostatistician at Roche for 4 years, Paeds / Onc RN from Melbourne, Australia
- Previously : Master Thesis in Longitudinal Cluster Analysis, Biostatistician at Roche for 4 years, Paeds / Onc RN from Melbourne, Australia
- Lead developer of `phase1b` package, Bayesian Framework for Clinical Trials and
`openstatsware` member
- Enjoys developing statistical software, especially writing tests
Expand Down Expand Up @@ -144,7 +144,7 @@ readr::read_csv("resources/program.csv", col_types = "cc") |>
## What do we mean by GSWEP4R\*?

::: aside
\* Good Software Engineering Practice for R
\* Good Software Engineering Practice for R Packages
:::

- Applying concept of "Good XYZ Practice" to SWE with R
Expand All @@ -155,7 +155,7 @@ readr::read_csv("resources/program.csv", col_types = "cc") |>

## Why care about GSWEP4R?

- R is one of the most successfull statistical programming languages
- R is one of the most successful statistical programming languages
- R is a powerful yet complex *ecosystem*
- Core component: R packages
- Mature user & contributor community
Expand Down Expand Up @@ -262,13 +262,11 @@ knitr::include_graphics("resources/pkg_graph.png")
- shareable
- easier to document

# Extra motivation for today's course :
# Extra motivation for today's course:

check out the [diversity alliance hackathon on Sep 30](https://www.linkedin.com/posts/open-source-in-pharma_diversity-alliance-hackathon-rpharma-activity-7355688433186422784-XDpd/?utm_source=share&utm_medium=member_desktop&rcm=ACoAAAm-hUYBK6599wxUyoAYIPTNW2hexCikETs) and see if you can apply today's learned skills there!


# Question, Comments?

# Question, comments?

# License information {.smaller}

Expand Down
99 changes: 44 additions & 55 deletions slides/02_r_packages.qmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,26 +11,24 @@ author: Alessandro Gasparini

# Introduction

## What You Know Already
## What you know already

- Packages provide a mechanism for loading optional code, data, and
documentation
- Packages provide a mechanism for loading optional code, data, and documentation
- A library is a directory into which packages are installed
- `install.packages()` is used to install packages into the library
- `library()` is used to load and attach packages from the library
- "Attach" means that the package is put in your `search` list --- objects in
the package can be used directly
- "Attach" means that the package is put in your `search` list --- objects in the package can be used directly
- Remember that **package $\neq$ library**

## What We Want to Talk About Now
## What we want to talk about now

- How to write, build, test, and check your own package `r emoji::emoji("blush")`
- How to do this in a methodical and sustainable way
- Give tips and tricks based on practical experience

# Contents of a Package
# Contents of a package

## How is a Package Structured?
## How is a package structured?

Package source = directory with files and subdirectories

Expand All @@ -54,7 +52,7 @@ Package source = directory with files and subdirectories
:::
:::

## How to Get Started Quickly
## How to get started quickly

Once upon a time, developers would set up this structure manually `r emoji::emoji("yawning_face")`

Expand All @@ -65,7 +63,7 @@ Nowadays, it's super fast with:

![](resources/rstudio-rpackage.png){.r-stretch}

## `DESCRIPTION` File
## `DESCRIPTION` file

- *Package*: Choose the name of your package
- Not unimportant!
Expand All @@ -76,7 +74,7 @@ Nowadays, it's super fast with:
- *Authors@R*: Add authors and maintainer
- *Description*: Like an abstract, including references

## `DESCRIPTION` File (cont'd)
## `DESCRIPTION` file (cont'd)

- *License*: Important for open sourcing
- Consider permissive licenses such as Apache and MIT
Expand All @@ -88,7 +86,7 @@ Nowadays, it's super fast with:
- *Suggests*: Packages for documentation processing (`roxygen2`), running
examples, tests (`testthat`), vignettes

## `R` Folder
## `R` folder

- Only contains R code files (recommended to use `.R` suffix)
- Can create a file with `usethis::use_r("filename")`
Expand All @@ -105,7 +103,7 @@ Nowadays, it's super fast with:
NULL
```

## `NAMESPACE` File
## `NAMESPACE` file

```{r}
#| echo: true
Expand All @@ -118,13 +116,12 @@ export(package_used_second)
export(package_used_third)
```

- Defines the namespace of the package, to work with R's namespace management
system
- Defines the namespace of the package, to work with R's namespace management system
- Namespace directives in this file allow to specify:
- Which objects are exported to users and other packages
- Which are imported from other packages

## `NAMESPACE` File (cont'd)
## `NAMESPACE` file (cont'd)

- Controls the search strategy for variables:
1. Local (in the function body etc.)
Expand All @@ -133,34 +130,28 @@ export(package_used_third)
4. Base namespace
5. Normal `search()` path

## `man` Folder
## `man` folder

- Contains documentation files for the objects in the package in the `.Rd`
format
- Contains documentation files for the objects in the package in the `.Rd` format
- The syntax is a bit similar to `LaTeX`
- All user level objects should be documented
- Internal objects don't need to be documented --- but I recommend it!
- Once upon a time, developers would set up these `.Rd` files and the
`NAMESPACE` manually `r emoji::emoji("yawning_face")`
- Once upon a time, developers would set up these `.Rd` files and the `NAMESPACE` manually `r emoji::emoji("yawning_face")`
- Fortunately, nowadays we have `roxygen2`! `r emoji::emoji("rocket")`

## `roxygen2` to the Rescue!
## `roxygen2` to the rescue!

- We can include the documentation source directly in the R script on top of
the objects we are documenting
- Syntax is composed of special comments `#'` and special macros preceded with
`@`
- In RStudio, running Build > More > Document will render the `.Rd` files and
the `NAMESPACE` file for you
- We can include the documentation source directly in the R script on top of the objects we are documenting
- Syntax is composed of special comments `#'` and special macros preceded with `@`
- In RStudio, running Build > More > Document will render the `.Rd` files and the `NAMESPACE` file for you
- Get started with `usethis::use_roxygen_md()`
- Placing your cursor inside a function in RStudio, create a `roxygen2` skeleton
with Code > Insert Roxygen Skeleton
- Placing your cursor inside a function in RStudio, create a `roxygen2` skeleton with Code > Insert Roxygen Skeleton

## Setting up `roxygen2` in your project

![](resources/roxygen2-setting.png){.r-stretch}

## `roxygen2` Source
## `roxygen2` source

`R/my_sum.R`:

Expand All @@ -187,7 +178,7 @@ my_sum <- function(x, y) {
}
```

## `roxygen2` Output
## `roxygen2` output

`man/my_sum.Rd`:

Expand Down Expand Up @@ -222,7 +213,7 @@ my_sum(1, 2)
}
```

## `roxygen2` Output (cont'd)
## `roxygen2` output (cont'd)

`NAMESPACE`:

Expand All @@ -232,7 +223,7 @@ my_sum(1, 2)
export(my_sum)
```

## `tests` Folder
## `tests` folder

- Where store the unit tests covering the functionality of the package
- Get started with `usethis::use_testthat()` and `usethis::use_test()` and
Expand All @@ -241,7 +232,7 @@ export(my_sum)
into R scripts directly in `tests` directory
- We will look at unit tests in detail later

## `data` Folder
## `data` folder

- For (example) data that you ship in your package to the user
- Get started with `usethis::use_data()`
Expand All @@ -250,7 +241,7 @@ export(my_sum)
- If you generate the example data, save the R script, too
- Put that into `data-raw` folder, start with `usethis::use_data_raw()`

## `inst` Folder
## `inst` folder

- Contents will be copied recursively to installation directory
- Be careful not to interfere with standard folder names
Expand All @@ -261,7 +252,7 @@ export(my_sum)
- Create it with `usethis::use_citation()`
- `inst/doc` can contain documentation files (typically `pdf`)

## `src` Folder
## `src` folder

- Contains sources and headers for any code that needs compilation
- Should only contain a single language here
Expand All @@ -272,7 +263,7 @@ export(my_sum)
- Wrapping existing libraries for use in R
- Speeding up complex or long computations

## `vignettes` Folder
## `vignettes` folder

- Special case of documentation files (`pdf` or `html`) created by compiling
source files
Expand All @@ -283,7 +274,7 @@ export(my_sum)
- Important for the user to understand the high-level ideas
- Complements function-level documentation from our `roxygen2` chunks

## `NEWS` File
## `NEWS` file

- Lists user-visible changes worth mentioning
- In each new release, add items at the top under the version they refer to
Expand All @@ -297,7 +288,7 @@ export(my_sum)
- We mentioned before that licensing information is usually included in the `DESCRIPTION` file
- In fact, the `License` field (in standardized form) is mandatory
- Licensing for a package which might be distributed is an important but potentially complex subject
- It is very important to include license information, as otherwise:
- It is very important to include licensing information, as otherwise:
- It may not be possible to use it
- It may not be possible to distribute copies of it
- We are going to talk more about licensing in Chapter 5 later today
Expand All @@ -323,9 +314,10 @@ License: Artistic-2.0 | AGPL-3 + file LICENSE
- The optional file `LICENSE`/`LICENCE` contains a copy of the license
- Only include such a file if it is referred to in the `License` field

## Adding a license to your package
## Adding a license to your package {.scrollable}

- Once again, functions from the usethis package simplify this process

- Possible options:
- `usethis::use_mit_license(copyright_holder = NULL)`
- `usethis::use_gpl_license(version = 3, include_future = TRUE)`
Expand All @@ -336,18 +328,17 @@ License: Artistic-2.0 | AGPL-3 + file LICENSE
- `usethis::use_ccby_license()`
- `usethis::use_proprietary_license(copyright_holder)`

# Building the Package
# Building the package

## Documenting the Package
## Documenting the package

- The first step is to produce the documentation files and `NAMESPACE`
- In RStudio: Build > More > Document
- In the console: `devtools::document()`

## Checking the Package
## Checking the package

- R comes with pre-defined check command for packages:
"the R package checker" aka `R CMD check`
- R comes with pre-defined check command for packages: "the R package checker" aka `R CMD check`
- About 22 checks are run (so quite a lot), including things like:
- Can the package be installed?
- Is the code syntax ok?
Expand All @@ -357,28 +348,26 @@ License: Artistic-2.0 | AGPL-3 + file LICENSE
- In RStudio: Build > Check
- In the console: `devtools::check()`

## Building the Package
## Building the package

- The R package folder can be compressed into a single package file
- Typically we manually only build "source" package
- In RStudio: Build > More > Build Source Package
- In the console: `devtools::build()`
- Makes it easy to share the package with others and submit to CRAN

## Installing the Package
## Installing the package

- R comes with pre-defined install command for packages:
`R CMD INSTALL`
- R comes with pre-defined install command for packages: `R CMD INSTALL`
- In RStudio: Build > Install
- In the console: `devtools::install()`
- Note: During development it's usually sufficient to use Build > More > Load
All
- Note: During development it's usually sufficient to use Build > More > Load All
- Runs `devtools::load_all()`
- Roughly simulates what happens when package would be installed and loaded
- **Unexported** objects and helpers under `tests` will also be available
- Key: much faster!

## Keyboard Shortcuts
## Keyboard shortcuts

- Learning a few keyboard shortcuts can speed up many of the tasks we introduced in this lecture:

Expand All @@ -389,7 +378,7 @@ readr::read_csv(here::here("slides/resources/keyboard-shortcuts.csv"), col_types
knitr::kable(align = "ccc")
```

- There are many more – check the [RStudio IDE Documentation](https://docs.posit.co/ide/user/ide/reference/shortcuts.html)
- There are many more – check for instance the [RStudio IDE Documentation](https://docs.posit.co/ide/user/ide/reference/shortcuts.html)

# Exercise

Expand All @@ -405,7 +394,7 @@ readr::read_csv(here::here("slides/resources/keyboard-shortcuts.csv"), col_types
1. Run checks
1. Build the package

> We will be using this package throughout the day!
$\leadsto$ We will be using this package throughout the day!

# References

Expand Down
Loading