Note that 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 biocthis will be helpful for you too.
1 Basics
1.1 Install biocthis
R is an open-source statistical environment which can be easily modified to enhance its functionality via packages. 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 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")
1.2 Required knowledge
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 usethis (Wickham, Bryan, Barrett, and Teucher, 2024), devtools (Wickham, Hester, Chang, and Bryan, 2022), and testthat (Wickham, 2011). It will also be helpful if you are familiar with styler (Müller and Walthert, 2024). Finally, we highly recommend that you run 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.
1.3 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.
1.4 Citing biocthis
We hope that 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")
#> To cite package 'biocthis' in publications use:
#>
#> Collado-Torres L (2024). _Automate package and project setup for
#> Bioconductor packages_. doi:10.18129/B9.bioc.biocthis
#> <https://doi.org/10.18129/B9.bioc.biocthis>,
#> https://github.com/lcolladotor/biocthisbiocthis - R package version
#> 1.16.0, <http://www.bioconductor.org/packages/biocthis>.
#>
#> Collado-Torres L (2024). "Automate package and project setup for
#> Bioconductor packages." _bioRxiv_. doi:10.1101/TODO
#> <https://doi.org/10.1101/TODO>,
#> <https://www.biorxiv.org/content/10.1101/TODO>.
#>
#> To see these entries in BibTeX format, use 'print(<citation>,
#> bibtex=TRUE)', 'toBibtex(.)', or set
#> 'options(citation.bibtex.max=999)'.
2 Quick start to using to biocthis
biocthis is an R package that expands 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. biocthis has functions that can also enhance your current R packages that either are already distributed by Bioconductor or have Bioconductor dependencies. 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")
2.1 Using biocthis in your R package
If you haven’t made an R package yet, you can do so using 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)
#> ✔ Creating '/home/biocbuild/bbs-3.20-bioc/tmpdir/RtmpVZn2Aw/biocthispkg/'.
#> ✔ Setting active project to
#> "/home/biocbuild/bbs-3.20-bioc/tmpdir/RtmpVZn2Aw/biocthispkg".
#> ✔ Creating 'R/'.
#> ✔ Writing 'DESCRIPTION'.
#> Package: biocthispkg
#> Title: What the Package Does (One Line, Title Case)
#> Version: 0.0.0.9000
#> Authors@R (parsed):
#> * First Last <first.last@example.com> [aut, cre] (YOUR-ORCID-ID)
#> Description: What the package does (one paragraph).
#> License: `use_mit_license()`, `use_gpl3_license()` or friends to pick a
#> license
#> Encoding: UTF-8
#> Roxygen: list(markdown = TRUE)
#> RoxygenNote: 7.3.2
#> ✔ Writing 'NAMESPACE'.
#> ✔ Setting active project to "<no active project>".
#> ✔ Setting active project to
#> "/home/biocbuild/bbs-3.20-bioc/tmpdir/RtmpVZn2Aw/biocthispkg".
#> ✔ Initialising Git repo.
#> ✔ Adding ".Rproj.user", ".Rhistory", ".Rdata", ".httr-oauth", ".DS_Store", and
#> ".quarto" to '.gitignore'.
Once you have created a package, you can use use_bioc_pkg_templates() to create a set of scripts in the dev (developer) directory.
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 1 You might want to use 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.
Adds a Bioconductor-friendly GitHub Actions workflow
Adds a pkgdown/extra.css file for configuring pkgdown (Wickham, Hesselberth, Salmon, Roy, and Brüggemann, 2024) documentation websites with Bioconductor’s official colors
Deploys an initial documentation website using pkgdown (Wickham, Hesselberth, Salmon et al., 2024)
04_update.R
Automatically styles the R code in your package using styler (Müller and Walthert, 2024)
Update the documentation file using devtools (Wickham, Hester, Chang et al., 2022)
Many of these steps are powered by usethis (Wickham, Bryan, Barrett et al., 2024) with some of them utilizing biocthis (Collado-Torres, 2024).
3biocthis functions overview
The dev scripts use the different functions provided by biocthis in the suggested order. However, below we give a brief overview of what they do.
3.1use_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()
#> ! Can't find a README for the current project.
#> ℹ See `usethis::use_readme_rmd()` for help creating this file.
#> ℹ Badge link will only be printed to screen.
#> ☐ Copy and paste the following lines into 'README':
#> <!-- badges: start -->
#> [](https://bioconductor.org/checkResults/release/bioc-LATEST/biocthispkg)
#> <!-- badges: end -->
#> ! Can't find a README for the current project.
#> ℹ See `usethis::use_readme_rmd()` for help creating this file.
#> ℹ Badge link will only be printed to screen.
#> ☐ Copy and paste the following lines into 'README':
#> <!-- badges: start -->
#> [](https://bioconductor.org/checkResults/devel/bioc-LATEST/biocthispkg)
#> <!-- badges: end -->
#> ! Can't find a README for the current project.
#> ℹ See `usethis::use_readme_rmd()` for help creating this file.
#> ℹ Badge link will only be printed to screen.
#> ☐ Copy and paste the following lines into 'README':
#> <!-- badges: start -->
#> [](http://bioconductor.org/packages/stats/bioc/biocthispkg/)
#> <!-- badges: end -->
#> ! Can't find a README for the current project.
#> ℹ See `usethis::use_readme_rmd()` for help creating this file.
#> ℹ Badge link will only be printed to screen.
#> ☐ Copy and paste the following lines into 'README':
#> <!-- badges: start -->
#> [](https://support.bioconductor.org/tag/biocthispkg)
#> <!-- badges: end -->
#> ! Can't find a README for the current project.
#> ℹ See `usethis::use_readme_rmd()` for help creating this file.
#> ℹ Badge link will only be printed to screen.
#> ☐ Copy and paste the following lines into 'README':
#> <!-- badges: start -->
#> [](https://bioconductor.org/packages/release/bioc/html/biocthispkg.html#since)
#> <!-- badges: end -->
#> ! Can't find a README for the current project.
#> ℹ See `usethis::use_readme_rmd()` for help creating this file.
#> ℹ Badge link will only be printed to screen.
#> ☐ Copy and paste the following lines into 'README':
#> <!-- badges: start -->
#> [](http://bioconductor.org/checkResults/devel/bioc-LATEST/biocthispkg/)
#> <!-- badges: end -->
#> ! Can't find a README for the current project.
#> ℹ See `usethis::use_readme_rmd()` for help creating this file.
#> ℹ Badge link will only be printed to screen.
#> ☐ Copy and paste the following lines into 'README':
#> <!-- badges: start -->
#> [](https://bioconductor.org/packages/release/bioc/html/biocthispkg.html#since)
#> <!-- badges: end -->
## Automatically style the example package
styler::style_pkg(pkgdir, transformers = biocthis::bioc_style())
#> ────────────────────────────────────────
#> Status Count Legend
#> ✔ 0 File unchanged.
#> ℹ 0 File changed.
#> ✖ 0 Styling threw an error.
#> ────────────────────────────────────────
3.3use_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()
#> ✔ Creating 'inst/'.
#> ✔ Writing 'inst/CITATION'.
#> ☐ Edit 'inst/CITATION'.
3.4use_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()
#> ℹ Leaving 'DESCRIPTION' unchanged.
#> Package: biocthispkg
#> Title: What the Package Does (One Line, Title Case)
#> Version: 0.99.0
#> Date: 2024-10-29
#> Authors@R (parsed):
#> * First Last <first.last@example.com> [aut, cre] (YOUR-ORCID-ID)
#> Description: What the package does (one paragraph).
#> License: Artistic-2.0
#> URL:
#> BugReports: https://support.bioconductor.org/tag/biocthispkg
#> Encoding: UTF-8
#> Roxygen: list(markdown = TRUE)
#> RoxygenNote: 7.3.2
#> biocViews: Software
3.5use_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()
#> ✔ Creating '.github/'.
#> ✔ Adding "^\\.github$" to '.Rbuildignore'.
#> ✔ Adding "*.html" to '.github/.gitignore'.
#> ✔ Creating '.github/ISSUE_TEMPLATE/'.
#> ✔ Writing '.github/ISSUE_TEMPLATE/feature_request_template.md'.
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()
#> ✔ Creating '.github/workflows/'.
#> ✔ Writing '.github/workflows/check-bioc.yml'.
3.6.2 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. 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.
3.6.3 Additional features
Furthermore, the use_bioc_github_action() GHA workflow provides the following features:
It runs covr (Hester, 2023) unless disabled by the environment variable run_covr (see the first few lines of the workflow).
It automatically deploys a documentation website using pkgdown (Wickham, Hesselberth, Salmon et al., 2024) 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 pkgdown (Wickham, Hesselberth, Salmon et al., 2024) documentation website with Bioconductor’s official colors.
It displays the information from testthat (Wickham, 2011) 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 2 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.
3.6.4 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)
3.6.5 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 bookdown or rmarkdown websites, or even docker images. Some examples are:
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 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) 3 See for example rocker-versioned2 issue 50. .
We highly recommend watching any developments as they happen at 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.
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()
#> ✔ Writing '.github/ISSUE_TEMPLATE/issue_template.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()
#> ✔ Writing 'NEWS.md'.
3.9use_bioc_pkg_templates()
This function was already described in detail in the previous main section.
3.10use_bioc_pkgdown_css()
use_bioc_pkgdown_css() creates the pkgdown/extra.css file that configures your pkgdown (Wickham, Hesselberth, Salmon et al., 2024) 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()
#> ✔ Creating 'pkgdown/'.
#> ✔ Writing 'pkgdown/extra.css'.
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()
#> ✔ Writing 'README.Rmd'.
#> ✔ Adding "^README\\.Rmd$" to '.Rbuildignore'.
#> ✔ Writing '.git/hooks/pre-commit'.
3.12use_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()
#> ✔ Writing '.github/SUPPORT.md'.
3.13use_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 RefManageR, styling your vignette with 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 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")
#> ✔ Adding knitr to 'Suggests' field in DESCRIPTION.
#> ☐ Use `requireNamespace("knitr", quietly = TRUE)` to test if knitr is
#> installed.
#> ☐ Then directly refer to functions with `knitr::fun()`.
#> ✔ Adding BiocStyle to 'Suggests' field in DESCRIPTION.
#> ☐ Use `requireNamespace("BiocStyle", quietly = TRUE)` to test if BiocStyle is
#> installed.
#> ☐ Then directly refer to functions with `BiocStyle::fun()`.
#> ✔ Adding RefManageR to 'Suggests' field in DESCRIPTION.
#> ☐ Use `requireNamespace("RefManageR", quietly = TRUE)` to test if RefManageR is
#> installed.
#> ☐ Then directly refer to functions with `RefManageR::fun()`.
#> ✔ Adding sessioninfo to 'Suggests' field in DESCRIPTION.
#> ☐ Use `requireNamespace("sessioninfo", quietly = TRUE)` to test if sessioninfo
#> is installed.
#> ☐ Then directly refer to functions with `sessioninfo::fun()`.
#> ✔ Adding testthat to 'Suggests' field in DESCRIPTION.
#> ☐ Use `requireNamespace("testthat", quietly = TRUE)` to test if testthat is
#> installed.
#> ☐ Then directly refer to functions with `testthat::fun()`.
#> ✔ Adding "knitr" to 'VignetteBuilder'.
#> ✔ Adding "inst/doc" to '.gitignore'.
#> ✔ Creating 'vignettes/'.
#> ✔ Adding "*.html" and "*.R" to 'vignettes/.gitignore'.
#> ✔ Adding rmarkdown to 'Suggests' field in DESCRIPTION.
#> ☐ Use `requireNamespace("rmarkdown", quietly = TRUE)` to test if rmarkdown is
#> installed.
#> ☐ Then directly refer to functions with `rmarkdown::fun()`.
#> ✔ Writing 'vignettes/biocthispkg.Rmd'.
#> ☐ Edit 'vignettes/biocthispkg.Rmd'.
This vignette was generated using BiocStyle (Oleś, 2024)
with knitr (Xie, 2024) and rmarkdown (Allaire, Xie, Dervieux et al., 2024) running behind the scenes.
[3]
L. Henry and H. Wickham.
rlang: Functions for Base Types and Core R and ‘Tidyverse’ Features.
R package version 1.1.4.
2024.
URL: https://CRAN.R-project.org/package=rlang.
[6]
J. Hester, H. Wickham, and G. Csárdi.
fs: Cross-Platform File System Operations Based on ‘libuv’.
R package version 1.6.4.
2024.
URL: https://CRAN.R-project.org/package=fs.
[7]
M. W. McLean.
“RefManageR: Import and Manage BibTeX and BibLaTeX References in R”.
In: The Journal of Open Source Software (2017).
DOI: 10.21105/joss.00338.
[10]
R Core Team.
R: A Language and Environment for Statistical Computing.
R Foundation for Statistical Computing.
Vienna, Austria, 2024.
URL: https://www.R-project.org/.
[14]
H. Wickham, J. Hesselberth, M. Salmon, et al.
pkgdown: Make Static HTML Documentation for a Package.
R package version 2.1.1.
2024.
URL: https://CRAN.R-project.org/package=pkgdown.