Get Started

library(rworkflows)

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())

## Saving yaml ==> /tmp/Rtmpjelklm/rworkflows.yml

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())

## Saving yaml ==> /tmp/Rtmpjelklm/rworkflows_static.yml

`use_badges`

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

badges <- rworkflows::use_badges()

## Finding hex sticker(s) for 1 package(s).

## Adding license.

## Adding version.

## Adding code size

## Adding commit.

## Adding actions.

## Adding codecov.

## Adding authors.

## When refs is provided, paths must have the same length (or be set to NULL). Setting paths=NULL.

Authors: Brian Schilder, Alan Murphy, Nathan Skene

`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())

## Creating new Docker file ==> /tmp/Rtmpjelklm/Dockerfile

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())

## Creating new README file ==> /tmp/Rtmpjelklm/README.Rmd

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())

## Creating new vignette file ==> /tmp/Rtmpjelklm/vignettes/mypackage.Rmd

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())

## Creating new vignette file ==> /tmp/Rtmpjelklm/vignettes/docker.Rmd

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())

## name: rworkflows
## 'on':
##   push:
##     branches:
##     - master
##     - main
##     - devel
##     - RELEASE_**
##   pull_request:
##     branches:
##     - master
##     - main
##     - devel
##     - RELEASE_**
## jobs:
##   rworkflows:
##     permissions: write-all
##     runs-on: ${{ matrix.config.os }}
##     name: ${{ matrix.config.os }} (${{ matrix.config.r }})
##     container: ${{ matrix.config.cont }}
##     strategy:
##       fail-fast: no
##       matrix:
##         config:
##         - os: ubuntu-latest
##           bioc: devel
##           r: auto
##           cont: ghcr.io/bioconductor/bioconductor_docker:devel
##           rspm: ~
##           python-version: 3.10.11
##         - os: macOS-latest
##           bioc: release
##           r: auto
##           cont: ~
##           rspm: ~
##           python-version: '3.9'
##         - os: windows-latest
##           bioc: release
##           r: auto
##           cont: ~
##           rspm: ~
##           python-version: 3.9.1
##     steps:
##     - uses: neurogenomics/rworkflows@master
##       with:
##         run_bioccheck: no
##         run_rcmdcheck: yes
##         as_cran: yes
##         run_vignettes: yes
##         has_testthat: yes
##         run_covr: yes
##         run_pkgdown: yes
##         has_runit: no
##         has_latex: no
##         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
##         run_docker: no
##         DOCKER_TOKEN: ${{ secrets.DOCKER_TOKEN }}
##         runner_os: ${{ runner.os }}
##         cache_version: cache-v1
##         docker_registry: ghcr.io

## Saving yaml ==> /tmp/Rtmpjelklm/rworkflows.yml

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)

## name: myenv
## channels:
## - conda-forge
## - bioconda
## dependencies:
## - python>=3.7
## - scanpy
## - anndata
## - pip
## - pip:
##   - scarches
##   - magic-impute

## Saving yaml ==> /__w/rworkflows/rworkflows/myenv_conda.yml

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())

## environment_file supplied. Enabling miniforge.

## python-version not set for runner os='ubuntu-latest'. Using default.

## python-version not set for runner os='macOS-latest'. Using default.

## python-version not set for runner os='windows-latest'. Using default.

## name: rworkflows
## 'on':
##   push:
##     branches:
##     - master
##     - main
##     - devel
##     - RELEASE_**
##   pull_request:
##     branches:
##     - master
##     - main
##     - devel
##     - RELEASE_**
## jobs:
##   rworkflows:
##     permissions: write-all
##     runs-on: ${{ matrix.config.os }}
##     name: ${{ matrix.config.os }} (${{ matrix.config.r }})
##     container: ${{ matrix.config.cont }}
##     strategy:
##       fail-fast: no
##       matrix:
##         config:
##         - os: ubuntu-latest
##           bioc: devel
##           r: auto
##           cont: ghcr.io/bioconductor/bioconductor_docker:devel
##           rspm: ~
##         - os: macOS-latest
##           bioc: release
##           r: auto
##           cont: ~
##           rspm: ~
##         - os: windows-latest
##           bioc: release
##           r: auto
##           cont: ~
##           rspm: ~
##     steps:
##     - uses: neurogenomics/rworkflows@master
##       with:
##         run_bioccheck: no
##         run_rcmdcheck: yes
##         as_cran: yes
##         run_vignettes: yes
##         has_testthat: yes
##         run_covr: yes
##         run_pkgdown: yes
##         has_runit: no
##         has_latex: no
##         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
##         run_docker: no
##         DOCKER_TOKEN: ${{ secrets.DOCKER_TOKEN }}
##         runner_os: ${{ runner.os }}
##         cache_version: cache-v1
##         docker_registry: ghcr.io
##         miniforge_variant: ''
##         environment_file: /__w/rworkflows/rworkflows/myenv_conda.yml

## Saving yaml ==> /tmp/Rtmpjelklm/rworkflows.yml

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

## [1] TRUE

Session Info

utils::sessionInfo()

## R version 4.4.1 (2024-06-14)
## Platform: x86_64-pc-linux-gnu
## Running under: Ubuntu 22.04.4 LTS
## 
## Matrix products: default
## BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3 
## LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.20.so;  LAPACK version 3.10.0
## 
## locale:
##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
##  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8    
##  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
##  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
##  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
## 
## time zone: UTC
## tzcode source: system (glibc)
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] rworkflows_1.0.3
## 
## loaded via a namespace (and not attached):
##  [1] gtable_0.3.5        jsonlite_1.8.9      renv_1.0.9         
##  [4] BiocManager_1.30.25 dplyr_1.1.4         compiler_4.4.1     
##  [7] tidyselect_1.2.1    jquerylib_0.1.4     rvcheck_0.2.1      
## [10] systemfonts_1.1.0   scales_1.3.0        textshaping_0.4.0  
## [13] yaml_2.3.10         fastmap_1.2.0       here_1.0.1         
## [16] ggplot2_3.5.1       R6_2.5.1            generics_0.1.3     
## [19] knitr_1.48          yulab.utils_0.1.7   htmlwidgets_1.6.4  
## [22] tibble_3.2.1        desc_1.4.3          dlstats_0.1.7      
## [25] rprojroot_2.0.4     munsell_0.5.1       bslib_0.8.0        
## [28] pillar_1.9.0        RColorBrewer_1.1-3  rlang_1.1.4        
## [31] utf8_1.2.4          cachem_1.1.0        badger_0.2.4       
## [34] xfun_0.47           fs_1.6.4            sass_0.4.9         
## [37] cli_3.6.3           pkgdown_2.1.1       magrittr_2.0.3     
## [40] digest_0.6.37       grid_4.4.1          lifecycle_1.0.4    
## [43] vctrs_0.6.5         data.table_1.16.0   evaluate_1.0.0     
## [46] glue_1.8.0          ragg_1.3.2          fansi_1.0.6        
## [49] colorspace_2.1-1    rmarkdown_2.28      tools_4.4.1        
## [52] pkgconfig_2.0.3     htmltools_0.5.8.1

Authors: Brian Schilder, Alan Murphy, Nathan Skene

Vignette updated: Oct-02-2024

GitHub Secrets

use_workflow

dynamic action

static workflow

use_badges

Authors: Brian Schilder, Alan Murphy, Nathan Skene

use_dockerfile

Templates

README

Vignette: Get started

Vignette: docker

Adding Python

Using Python

Using conda

Session Info

`use_workflow`

`use_badges`

`use_dockerfile`