Merge pull request #17 from openstatsware/consistency-checks

Edits to all chapters for consistency

Author: ellessenne

index.qmd

@@ -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.

slides/01_intro.qmd

@@ -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._
 
 
 \
@@ -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
@@ -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
@@ -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
@@ -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}
 

slides/02_r_packages.qmd

@@ -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
 
@@ -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")`
 
@@ -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!
@@ -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
@@ -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")`
@@ -105,7 +103,7 @@ Nowadays, it's super fast with:
 NULL
 ```
 
-## `NAMESPACE` File
+## `NAMESPACE` file
 
 ```{r}
 #| echo: true
@@ -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.)
@@ -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`:
 
@@ -187,7 +178,7 @@ my_sum <- function(x, y) {
 }
 ```
 
-## `roxygen2` Output
+## `roxygen2` output
 
 `man/my_sum.Rd`:
 
@@ -222,7 +213,7 @@ my_sum(1, 2)
 }
 ```
 
-## `roxygen2` Output (cont'd)
+## `roxygen2` output (cont'd)
 
 `NAMESPACE`:
 
@@ -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
@@ -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()`
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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)`
@@ -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?
@@ -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:
 
@@ -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
 
@@ -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