Contributing

If you plan to do anything beyond fixing a typo, the best thing you can do is to open an issue and discuss changes before you spend a lot of time doing them.

If you don’t have a lot of experience with git or GitHub, take a look at the wonderful Happy Git and GitHub for the useR.

If you want to contribute, some general advice is:

Only check in the source files (qmd, yml, bib, pre-made image files, etc). Don’t commit the rendered files.
Keep the changes small in scope. If the overall change is larger, make a sequence of small pull requests.
The edits cannot include exact code that is under another license (i.e., don’t just copy/paste from R sources, etc.)
Respect the existing code formatting/linting (as heterogeneous as it is).
Stick to using R for computations.
Don’t update software versions unless you have to. If you need to update or add something, use renv (described below) to codify the software requirements.
The usethis package has excellent tools for creating, updating, and managing pull requests. You should consider utilizing those features.

A merged PR will make you appear in the contributor list (see below). It will, however, be considered a donation of your work to this project. You are still bound by the conditions of the license, meaning that you are not considered an author, copyright holder, or owner of the content once it has been merged in.

You will mostly work with the *.qmd files in the chapters directory.

Here is a list of the elements in the repo:

├── DESCRIPTION          # Set package dependencies
├── _cache               # Location of cached chunks  
├── _extensions          # Created by quarto
├── _freeze              # Created by quarto
├── _publish.yml         # Publishing details
├── _quarto.yml          # Most options
├── website.Rproj        # Rstudio IDE file
├── chapters             # qmd content files
├── delimited            # csv versions of the data
├── docs                 # Created by quarto
├── figures              # Location for created image files 
├── includes             # tex, bib, and html files to include
├── index.qmd            # Initial quarto file
├── license.*            # License information
├── premade              # Premade diagrams and other files
├── renv                 # Version control for R packages
├── renv.lock            # Version control for R packages
├── R                    # Ancillary R files
├── RData                # WIP RData results
├── README.*             # Information
└── tests                # testthat files to check some results

Software

Regarding R packages, the repository has a DESCRIPTION file as if it were an R package. This lets us specify precisely what packages and their versions should be installed. The packages listed in the imports field contain packages for modeling/analysis and packages used to make the website/book. Some basic system requirements are likely needed to install packages: Fortran, gdal, and others.

The main requirements are as follows.

Quarto

Quarto is an open-source scientific and technical publishing system. Quarto version 1.6.3 is used to compile the website.

We also use a few Quarto extensions. These should be installed from the project’s root directory via:

quarto add quarto-ext/fontawesome
quarto add quarto-ext/shinylive
quarto add quarto-ext/fancy-text
quarto add leovan/quarto-pseudocode

R and renv

R version 4.4.1 (2024-06-14) is what we are currently using. We suggest using rig to manage R versions. There are several IDEs that you can use. We’ve used RStudio (>= 2023.6.1.524).

The current strategy is to use the renv (>= version 1.0.8) package to make this project more isolated, portable and reproducible.

To get package dependencies installed…

When you open the website.Rproj file, the renv package should be automatically installed/updated (if neded). For example:

# Bootstrapping renv 1.0.3 ---------------------------------------------------
- Downloading renv ... OK
- Installing renv  ... OK

The following package(s) will be installed:
- BiocManager [1.30.22]
These packages will be installed into "~/content/aml4td/renv/library/R-4.3/x86_64-apple-darwin20".

if you try to compile the book, you probably get and error:

- One or more packages recorded in the lockfile are not installed.
- Use `renv::status()` for more details.

You can get more information using renv::status() but you can get them installed by first running renv::activate(). As an example:

> renv::activate()

Restarting R session...

- Project '~/content/aml4td' loaded. [renv 1.0.3]
- One or more packages recorded in the lockfile are not installed.
- Use `renv::status()` for more details.

Since we have package versions recorded in the lockfile, we can installed them using renv::restore(). Here is an example of that output:

> renv::restore() 
The following package(s) will be updated:

# Bioconductor ---------------------------------------------------------------
- mixOmics         [* -> mixOmicsTeam/mixOmics]

# CRAN -----------------------------------------------------------------------
- BiocManager      [1.30.22 -> 1.30.21.1]
- lattice          [0.21-9 -> 0.21-8]
- Matrix           [1.6-1.1 -> 1.6-0]
- nlme             [3.1-163 -> 3.1-162]
- rpart            [4.1.21 -> 4.1.19]
- survival         [3.5-7 -> 3.5-5]
- abind            [* -> 1.4-5]

<snip>

- zip              [* -> 2.2.0]
- zoo              [* -> 1.8-12]

# GitHub ---------------------------------------------------------------------
- BiocParallel     [* -> Bioconductor/BiocParallel@devel]
- BiocVersion      [* -> Bioconductor/BiocVersion@devel]
- modeldatatoo     [* -> tidymodels/modeldatatoo@HEAD]
- parsnip          [* -> tidymodels/parsnip@HEAD]
- usethis          [* -> r-lib/usethis@HEAD]

# RSPM -----------------------------------------------------------------------
- bslib            [* -> 0.5.1]
- fansi            [* -> 1.0.5]
- fontawesome      [* -> 0.5.2]
- ggplot2          [* -> 3.4.4]
- htmltools        [* -> 0.5.6.1]
- withr            [* -> 2.5.1]

Do you want to proceed? [Y/n]: y

# Downloading packages -------------------------------------------------------
- Downloading BiocManager from CRAN ...         OK [569 Kb in 0.19s]
- Downloading nlme from CRAN ...                OK [828.7 Kb in 0.19s]
- Downloading BH from CRAN ...                  OK [12.7 Mb in 0.4s]
- Downloading BiocVersion from GitHub ...       OK [826 bytes in 0.37s]

<snip>

Depending on whether you have to install packages from source, you may need to install some system dependencies and try again (I had to install libgit2 the last time I did this).

Once you have everything installed, we recommend installing the underlying torch computational libraries. You can do this by loading the torch package A download will automatically begin if you need one.

Contributor List

The would like to thank those who have made a contribution to the project: @amy-palmer, @bmreiniger, @coatless, @krz, @syclik, and @tomsing1.