Get Started

In rworkflows: Test, Document, Containerise, and Deploy R Packages

pkg <- read.dcf("../DESCRIPTION", fields = "Package")[1]
library(pkg, character.only = TRUE)

library(`r pkg`)

GitHub Secrets

Before pushing changes to your new R package, you may want to set up one or more GitHub Secrets:

• GITHUB_TOKEN [Optional]: Can grant access to private repos on GitHub Actions. You can generate your very own Personal Authentication Token using these instructions.
• DOCKER_TOKEN [Optional]: Allows GitHub Actions to push to a DockerHub account.

use_workflow

dynamic action

User only have to run use_workflow once per R package to create a workflow file that calls the rworkflows action.

workflow <- rworkflows::use_workflow(run_bioccheck = FALSE, 
                                     run_rcmdcheck = TRUE,  
                                     run_pkgdown = TRUE, 
                                     run_docker = TRUE,
                                     docker_user = "bschilder",
                                     docker_org = "neurogenomicslab",
                                     force_new = TRUE,
                                     ## Use default save_dir in practice
                                     save_dir = tempdir())

static workflow

Alternatively, you may use

workflow_static <- rworkflows::use_workflow(name = "rworkflows_static",
                                     run_bioccheck = FALSE, 
                                     run_rcmdcheck = TRUE,  
                                     run_pkgdown = TRUE, 
                                     run_docker = TRUE,
                                     docker_user = "bschilder",
                                     docker_org = "neurogenomicslab",
                                     force_new = TRUE,
                                     ## Use default save_dir in practice
                                     save_dir = tempdir())

use_badges

This function creates a banner containing badges, a hex sticker (if one is available), and author names.

badges <- rworkflows::use_badges()

use_dockerfile

Create a Dockerfile that installs your R package and all its Imports/Suggests. It is normally not necessary for users to run this function themselves unless they would like to use it to create a template Dockerfile and then customise it further (rather than creating one on the fly).

## Use default save_dir in practice
dockerfile <- rworkflows::use_dockerfile(save_dir = tempdir()) 

Templates

You can generate templates for each of the following R package elements. These templates are designed to dynamically autofill as as much information as possible (package name, date, authors) to minimise manual editing steps and ensure documentation is as up-to-date as possible.

README

README rmarkdown file. Allows you to run code inside to generate a README markdown file.

## Use default save_dir in practice
readme <- rworkflows::use_readme(save_dir = tempdir())

Vignette: Get started

Generate a vignette on how to get started with your R package. Requires additional editing to fill in examples.

## Use default save_dir in practice
vignette1 <- rworkflows::use_vignette_getstarted(package = "mypackage",
                                                 save_dir = tempdir())

Vignette: docker

Generate a vignette on how to install your R package via with your R package, RStudio, and all dependencies already installed. This vignette does not require any manual editing after creation (unless you want to change things like port number, for example).

Note, this is only relevant when you have a container for your R package stored in a public Docker registry (e.g. GitHub Container Registry, DockerHub). You can automatically generate one by using the rworkflows action with run_docker=TRUE:

rworkflows::use_workflow(run_docker = TRUE, 
                         docker_org = "neurogenomics")

If you're using the GitHub Container Registry, docker_org can simply be your GH organization name or user name.

## Use default save_dir in practice
vignette2 <- rworkflows::use_vignette_docker(docker_org = "neurogenomics",
                                             save_dir = tempdir())

Adding Python

If your R package depends on python (e.g. via reticulate), the rworkflows action can also automatically install python for you.

Using Python

You can instruct GitHub Actions to install a version of python, with whatever level of versioning specificiy you want (e.g. "3.10.11", "3.10", or even just "3").

If you supply one python_version, it will be applied to all runners. You also assign a different python_version to each os, as we do here:

runners <- rworkflows::construct_runners(
  python_version = list("ubuntu-latest"="3.10.11",
                        "macOS-latest"="3.9",
                        "windows-latest"="3.9.1"))
workflow <- rworkflows::use_workflow(runners = runners,
                                     preview = TRUE,
                                     force_new = TRUE,
                                     ## Use default save_dir in practice
                                     save_dir = tempdir())

Using conda

Optionally, you can tell it to create and activate a conda environment to use. rworkflows::construct_conda_yml is a helper function to create conda yaml files for you.

Here we construct our yaml file that specifies what we want in our conda env. Make sure you write the yaml to your project directory, so that it gets pushed to GitHub (and thus can be found after checking out your repo on GitHub Actions).

See here for some examples of

environment_file <- construct_conda_yml(name = "myenv", 
                                        channels = c("conda-forge",
                                                     "bioconda"),
                                        dependencies = c("python>=3.7",
                                                         "scanpy",
                                                         "anndata"), 
                                        pip = c("scarches",
                                                "magic-impute"),
                                        preview = TRUE)

You could also simply provide a URL to a publicly accessible conda yaml file stored elsewhere.

environment_file <- "https://github.com/RajLabMSSM/echoconda/raw/main/inst/conda/scanpy.yml"

Now we can supply the conda environment_file path, and Miniconda will automatically be installed to build the conda env on all of your GitHub Actions runners.

workflow <- rworkflows::use_workflow(environment_file = environment_file, 
                                     preview = TRUE, 
                                     force_new = TRUE,
                                     ## Use default save_dir in practice
                                     save_dir = tempdir())

## Cleanup files
try({file.remove(environment_file)})

Session Info

utils::sessionInfo()

---

rworkflows documentation built on Sept. 23, 2024, 1:08 a.m.