In lcolladotor/biocthis: Automate package and project setup for Bioconductor packages

knitr::opts_chunk$set(
    collapse = TRUE,
    comment = "#>",
    crop = NULL ## Related to https://stat.ethz.ch/pipermail/bioc-devel/2020-April/016656.html
)

## Track time spent on making the vignette
startTime <- Sys.time()

## Bib setup
library("RefManageR")

## Write bibliography information
bib <- c(
    R = citation(),
    BiocStyle = citation("BiocStyle")[1],
    biocthis = citation("biocthis")[1],
    covr = citation("covr")[1],
    devtools = citation("devtools")[1],
    fs = citation("fs")[1],
    glue = citation("glue")[1],
    knitr = citation("knitr")[1],
    pkgdown = citation("pkgdown")[1],
    rlang = citation("rlang")[1],
    RefManageR = citation("RefManageR")[1],
    rmarkdown = citation("rmarkdown")[1],
    sessioninfo = citation("sessioninfo")[1],
    styler = citation("styler")[1],
    testthat = citation("testthat")[1],
    usethis = citation("usethis")[1]
)

Note that r Biocpkg("biocthis") is not a Bioconductor-core package and as such it is not a Bioconductor official package. It was made by and for Leonardo Collado-Torres so he could more easily maintain and create Bioconductor packages as listed at lcolladotor.github.io/pkgs/. Hopefully r Biocpkg("biocthis") will be helpful for you too.

Basics

Install biocthis

R is an open-source statistical environment which can be easily modified to enhance its functionality via packages. r Biocpkg("biocthis") is a R package available via the Bioconductor repository for packages. R can be installed on any operating system from CRAN after which you can install r Biocpkg("biocthis") by using the following commands in your R session:

if (!requireNamespace("BiocManager", quietly = TRUE)) {
    install.packages("BiocManager")
}

BiocManager::install("biocthis")

## Check that you have a valid Bioconductor installation
BiocManager::valid()

You can install the development version from GitHub with:

BiocManager::install("lcolladotor/biocthis")

Required knowledge

r Biocpkg("biocthis") is based on many other packages and in particular in those that have implemented the infrastructure needed for creating tidyverse-style R packages. That is r CRANpkg("usethis") r Citep(bib[["usethis"]]), r CRANpkg("devtools") r Citep(bib[["devtools"]]), and r CRANpkg("testthat") r Citep(bib[["testthat"]]). It will also be helpful if you are familiar with r CRANpkg("styler") r Citep(bib[["styler"]]). Finally, we highly recommend that you run r Biocpkg("biocthis") within RStudio Desktop.

If you are asking yourself the question "Where do I start using Bioconductor?" you might be interested in this blog post.

Asking for help

As package developers, we try to explain clearly how to use our packages and in which order to use the functions. But R and Bioconductor have a steep learning curve so it is critical to learn where to ask for help. The blog post quoted above mentions some but we would like to highlight the Bioconductor support site as the main resource for getting help: remember to use the biocthis tag and check the older posts. Other alternatives are available such as creating GitHub issues and tweeting. However, please note that if you want to receive help you should adhere to the posting guidelines. It is particularly critical that you provide a small reproducible example and your session information so package developers can track down the source of the error.

Citing biocthis

We hope that r Biocpkg("biocthis") will be useful for your work. Please use the following information to cite the package and the overall approach. Thank you!

## Citation info
citation("biocthis")

Quick start to using to biocthis

r Biocpkg("biocthis") is an R package that expands r CRANpkg("usethis") with Bioconductor-friendly templates. These templates will help you quickly create an R package that either has Bioconductor dependencies or that you are thinking of submitting to Bioconductor one day. r Biocpkg("biocthis") has functions that can also enhance your current R packages that either are already distributed by Bioconductor or have Bioconductor dependencies. r Biocpkg("biocthis") also includes a Bioconductor-friendly GitHub Actions workflow for your R package(s). To use the functions in this package, you need to load it as shown below.

library("biocthis")

## Load other R packages used in this vignette
library("usethis")
library("styler")

Using biocthis in your R package

If you haven't made an R package yet, you can do so using r CRANpkg("usethis"). That is, utilize usethis::create_package() with the package name of your choice. If you are using RStudio Desktop this function will open a new RStudio window and open R in the correct location. Otherwise, you might need to use setwd() to change directories.

In this vignette we will create an example package called biocthispkg on a temporary directory and work in this directory in order to illustrate how the functions work. In a real world scenario, you would be working inside your R package and would not run biocthis_example_pkg().

## Create an example package for illustrative purposes.
## Note: you do not need to run this for your own package!
pkgdir <- biocthis_example_pkg("biocthispkg", use_git = TRUE)

Once you have created a package, you can use use_bioc_pkg_templates() to create a set of scripts in the dev (developer) directory.

## Create the bioc templates
biocthis::use_bioc_pkg_templates()

If you run use_bioc_pkg_templates() inside RStudio Desktop, then all the scripts will open on your RStudio window. Each script contains comments that will guide you on the steps you need to do to create your Bioconductor-friendly R package. These scripts are:

• 01_create_pkg.R
• Helps you install R packages needed for developing R packages with these template scripts.
• Helps you check if the R package name you chose is available.
• Includes the steps up to running use_bioc_pkg_templates().
• 02_git_github_setup.R
• Ignores the *.Rproj files to comply with Bioconductor's requirements
• Initializes a git repository
• Creates the corresponding GitHub repository
• 03_core_files.R
• Creates Bioconductor-friendly README.Rmd and NEWS.md files
• Creates Bioconductor-friendly GitHub templates for issues, feature requests, and support requests
• Uses the tidyverse-style GitHub contributing and code of conduct files
• Creates a template Bioconductor-friendly CITATION file
• Adds several badges to the README.Rmd file ^[You might want to use r CRANpkg("badger") too, which has badges for Bioconductor download statistics. Some of the badges are only tailored for Bioconductor software packages, so you'll have to edit them for annotation, experiment and workflow packages.]
• Sets up unit tests using r CRANpkg("testthat") r Citep(bib[["testthat"]])
• Adds a Bioconductor-friendly GitHub Actions workflow
• Adds a pkgdown/extra.css file for configuring r CRANpkg("pkgdown") r Citep(bib[["pkgdown"]]) documentation websites with Bioconductor's official colors
• Deploys an initial documentation website using r CRANpkg("pkgdown") r Citep(bib[["pkgdown"]])
• 04_update.R
• Automatically styles the R code in your package using r CRANpkg("styler") r Citep(bib[["styler"]])
• Update the documentation file using r CRANpkg("devtools") r Citep(bib[["devtools"]])

Many of these steps are powered by r CRANpkg("usethis") r Citep(bib[["usethis"]]) with some of them utilizing r Biocpkg("biocthis") r Citep(bib[["biocthis"]]).

biocthis functions overview

The dev scripts use the different functions provided by r Biocpkg("biocthis") in the suggested order. However, below we give a brief overview of what they do.

use_bioc_badges()

Creates several Bioconductor badges for software packages (you will need to edit them for experiment data, annotation, workflow, or book packages) on your README files.

## Create some Bioconductor software package badges on your README files
biocthis::use_bioc_badges()

This function was contributed by Milan Malfait (@milanmlft) at pull request 35.

bioc_style()

bioc_style() helps you automatically apply a coding style to your R package files using r CRANpkg("styler") r Citep(bib[["styler"]]) that is based on the tidyverse coding style guide but modified to make it more similar to the Bioconductor coding style guide.

## Automatically style the example package
styler::style_pkg(pkgdir, transformers = biocthis::bioc_style())

use_bioc_citation()

use_bioc_citation() creates an R package CITATION file at inst/CITATION that is pre-populated with information you might want to use for your (future) Bioconductor package such as the Bioconductor DOIs and reference a journal article describing your package (that you might consider submitting to bioRxiv as a pre-print first). Alternatively, use usethis::use_citation().

## Create a template CITATION file that is Bioconductor-friendly
biocthis::use_bioc_citation()

use_bioc_description()

use_bioc_description() creates an R package DESCRIPTION file that is pre-populated with information you might want to use for your (future) Bioconductor package such as links to the Bioconductor Support Website and biocViews. You will still need to manually edit the file. Alternatively, use usethis::use_description().

## Create a template DESCRIPTION file that is Bioconductor-friendly
biocthis::use_bioc_description()

use_bioc_feature_request_template()

This function is related to use_bioc_issue_template(), as it creates a GitHub issue template file specifically tailored for feature requests. It is pre-populated with information you might want to users to provide when giving this type of feedback.

## Create a GitHub template for feature requests that is Bioconductor-friendly
biocthis::use_bioc_feature_request_template()

This function was added after a related contribution by Marcel Ramos (@LiNk-NY) at pull request 33.

use_bioc_github_action()

Getting started

use_bioc_github_action() creates a GitHub Actions (GHA) workflow file that is configured to be Bioconductor-friendly. Alternatively, use usethis::use_github_action() for the general GitHub Actions workflow maintained by r-lib/actions. If this is your first time seeing the words GitHub Actions, we highly recommend that you watch Jim Hester's rstudio::conf(2020) talk on this subject. Here is how you can add this GHA workflow to your R package:

## Create a GitHub Actions workflow that is Bioconductor-friendly
biocthis::use_bioc_github_action()

Main GHA workflow features

This GitHub Actions (GHA) workflow is based on r-lib/actions//examples/check-standard.yaml and others. The goal is to provide on demand R CMD checks on Linux, macOS and Windows using a similar setup to Bioconductor-devel and release branches. Some key features that make this GHA workflow Bioconductor-friendly are:

• It runs R CMD check on the same platforms (Linux, macOS and Windows) that Bioconductor supports.
• It runs BiocCheck::BiocCheck() on all these platforms, unlike the Bioconductor nightly builds. r Biocpkg("BiocCheck") is complementary to R CMD check and can help you improve your R package.
• It uses the Bioconductor devel and release dockers to test your package on Linux. Since all system dependencies required by Bioconductor packages are already included in these docker images, it's unlikely that you'll need to fiddle with Linux system dependencies. The information on the docker image is then used for configuring the macOS and Windows tests.

Additional features

Furthermore, the use_bioc_github_action() GHA workflow provides the following features:

• It runs r CRANpkg("covr") r Citep(bib[["covr"]]) unless disabled by the environment variable run_covr (see the first few lines of the workflow).
• It automatically deploys a documentation website using r CRANpkg("pkgdown") r Citep(bib[["pkgdown"]]) unless disabled by the environment variable run_pkgdown (see the first few lines of the workflow). With use_bioc_pkgdown_css() you can also create the pkgdown/extra.css file that will configure your r CRANpkg("pkgdown") r Citep(bib[["pkgdown"]]) documentation website with Bioconductor's official colors.
• It displays the information from r CRANpkg("testthat") r Citep(bib[["testthat"]]) unless disabled by the environment variable has_testthat (see the first few lines of the workflow). Similarly, has_RUnit controls whether you want to run the RUnit tests described in the Bioconductor unit testing guidelines.
• It caches the R packages and re-uses them for future tests except if you use the keyword /nocache in your commit message. Using /nocache can be helpful for debugging purposes. The caches are specific to the platform, the R version, and the Bioconductor version ^[In some situations, you might want to change the cache_version environment variable to force GHA to use new caches.]. These caches help you speed up your checks and are updated after a successful build.
• The machines provided by GitHub have 7GB of RAM, 2 cores and 14 GB of disk as noted in their help pages. It's free for open source projects, but you can also pay to use it on private repositories as explained in their features website.

Configure options

To help you set some of these configuration environment variables in the GHA workflow, use_bioc_github_action() has a few arguments that are used to update a template and customize it for your particular repository. Several of the arguments in use_bioc_github_action() use base::getOption(), which enables you to edit your R profile file with usethis::edit_r_profile() and add lines such as the ones mentioned in the code below.

## Open your .Rprofile file with usethis::edit_r_profile()

## For biocthis
options("biocthis.pkgdown" = TRUE)
options("biocthis.testthat" = TRUE)

Automatically scheduled tests

You could also edit the resulting GHA workflow to run automatically every few days (for example, every Monday) by adding a cron line as described in the official GHA documentation. This could of interest to you in some situations, though you should also be aware that it will use your GHA compute time that can have limits depending on your GitHub account and repository settings. If you are setting up a cron scheduled job, you might find crontab.guru useful.

Ultimately, there are many things you can do with GHA and you might want to use workflow as the basis for building r CRANpkg("bookdown") or r CRANpkg("rmarkdown") websites, or even docker images. Some examples are:

• lcolladotor/bioc_team_ds for r CRANpkg("bookdown").
• LieberInstitute/recountWorkshop2020 for creating a docker image at the end.

Notes about GHA workflows

Using a GitHub Actions workflow with Bioconductor-devel (R-devel six months in the year), regardless of which GHA workflow you use specifically, will expose you to issues with installing R packages in the latest versions of Bioconductor, CRAN, GitHub and elsewhere. At r-lib/actions#where-to-find-help you can find a list of steps you can take to get help for R GHA workflows. In the end, you might have to ask for help in:

• developer-oriented mailing lists,
• GitHub repositories for the packages you have issues installing them with,
• GitHub Actions repositories, and elsewhere.

That is, the GHA workflow provided by r Biocpkg("biocthis") can break depending on changes upstream of it. In particular, it can stop working:

• just prior to a new R release (unless r-lib/actions supports R alpha releases),
• if the required Bioconductor docker image is not available (for example, due to issues building these images based on dependencies on rocker and other upstream tools) ^[See for example rocker-versioned2 issue 50. ].

We highly recommend watching any developments as they happen at r Githubpkg("r-lib/actions") since the r-lib team does an excellent job keeping their GHA workflows updated. You can do so by subscribing to the RSS atom feed for commits in their repository processed through RSS FeedBurner that you can subscribe to by email.

If you are interested in learning more details about how this GHA workflow came to be, check the biocthis developer notes vignette.

use_bioc_issue_template()

use_bioc_issue_template() creates a GitHub issue template file that is pre-populated with information you might want to use for your (future) Bioconductor package such as links to the Bioconductor Support Website and examples of the information you can ask users to provide that will make it easier for you to help your users. Alternatively, use usethis::use_tidy_issue_template().

## Create a GitHub issue template file that is Bioconductor-friendly
biocthis::use_bioc_issue_template()

This function was greatly modified in a contribution by Marcel Ramos (@LiNk-NY) at pull request 33

use_bioc_news_md()

use_bioc_news_md() creates a NEWS.md template file that is pre-populated with information you might want to use for your (future) Bioconductor package. Alternatively, use usethis::use_news_md().

## Create a template NEWS.md file that is Bioconductor-friendly
biocthis::use_bioc_news_md()

use_bioc_pkg_templates()

This function was already described in detail in the previous main section.

use_bioc_pkgdown_css()

use_bioc_pkgdown_css() creates the pkgdown/extra.css file that configures your r CRANpkg("pkgdown") r Citep(bib[["pkgdown"]]) documentation website with Bioconductor's official colors.

## Create the pkgdown/extra.css file to configure pkgdown with
## Bioconductor's official colors
biocthis::use_bioc_pkgdown_css()

This function was created after issue 34 contributed by Kevin Rue-Albrecht @kevinrue.

use_bioc_readme_rmd()

use_bioc_readme_rmd() creates a README.Rmd template file that is pre-populated with information you might want to use for your (future) Bioconductor package such as Bioconductor's installation instructions, how to cite your package and links to the development tools you used. Alternatively, use usethis::use_readme_rmd().

## Create a template README.Rmd file that is Bioconductor-friendly
biocthis::use_bioc_readme_rmd()

use_bioc_support()

use_bioc_support() creates a template GitHub support template file that is pre-populated with information you might want to use for your (future) Bioconductor package such where to ask for help including the Bioconductor Support website. Alternatively, use usethis::use_tidy_support().

## Create a template GitHub support file that is Bioconductor-friendly
biocthis::use_bioc_support()

use_bioc_vignette()

use_bioc_vignette() creates a template vignette file that is pre-populated with information you might want to use for your (future) Bioconductor package. This template includes information on how to cite other packages using r CRANpkg("RefManageR"), styling your vignette with r Biocpkg("BiocStyle"), instructions on how to install your package from Bioconductor, where to ask for help, information a user might need to know before they use your package, as well as the reproducibility information on how the vignette was made powered by r CRANpkg("sessioninfo"). You will need to spend a significant amount of time editing this vignette as you develop your R package. Alternatively, use usethis::use_vignette().

## Create a template vignette file that is Bioconductor-friendly
biocthis::use_bioc_vignette("biocthispkg", "Introduction to biocthispkg")

Acknowledgments

r Biocpkg("biocthis") wouldn't have been possible without the help of many other R package developers. Please read the full story at the biocthis developer notes vignette.

Thank you very much! 🙌🏽😊

Reproducibility

The r Biocpkg("biocthis") package r Citep(bib[["biocthis"]]) was made possible thanks to:

• R r Citep(bib[["R"]])
• r Biocpkg("BiocStyle") r Citep(bib[["BiocStyle"]])
• r CRANpkg("covr") r Citep(bib[["covr"]])
• r CRANpkg("devtools") r Citep(bib[["devtools"]])
• r CRANpkg("fs") r Citep(bib[["fs"]])
• r CRANpkg("glue") r Citep(bib[["glue"]])
• r CRANpkg("knitr") r Citep(bib[["knitr"]])
• r CRANpkg("pkgdown") r Citep(bib[["pkgdown"]])
• r CRANpkg("rlang") r Citep(bib[["rlang"]])
• r CRANpkg("RefManageR") r Citep(bib[["RefManageR"]])
• r CRANpkg("rmarkdown") r Citep(bib[["rmarkdown"]])
• r CRANpkg("sessioninfo") r Citep(bib[["sessioninfo"]])
• r CRANpkg("styler") r Citep(bib[["styler"]])
• r CRANpkg("testthat") r Citep(bib[["testthat"]])
• r CRANpkg("usethis") r Citep(bib[["usethis"]])

This package was developed using r BiocStyle::Biocpkg("biocthis").

Code for creating the vignette

## Create the vignette
library("rmarkdown")
system.time(render("biocthis.Rmd", "BiocStyle::html_document"))

## Extract the R code
library("knitr")
knit("biocthis.Rmd", tangle = TRUE)

Date the vignette was generated.

## Date the vignette was generated
Sys.time()

Wallclock time spent generating the vignette.

## Processing time in seconds
totalTime <- diff(c(startTime, Sys.time()))
round(totalTime, digits = 3)

R session information.

## Session info
library("sessioninfo")
options(width = 120)
session_info()

Bibliography

This vignette was generated using r Biocpkg("BiocStyle") r Citep(bib[["BiocStyle"]]) with r CRANpkg("knitr") r Citep(bib[["knitr"]]) and r CRANpkg("rmarkdown") r Citep(bib[["rmarkdown"]]) running behind the scenes.

Citations made with r CRANpkg('RefManageR') r Citep(bib[['RefManageR']]).

## Print bibliography
PrintBibliography(bib, .opts = list(hyperlink = "to.doc", style = "html"))

lcolladotor/biocthis documentation built on Jan. 17, 2024, 8:07 p.m.