biocthis
Automate package and project setup for Bioconductor packages

Package index
Search the biocthis package
Vignettes
Functions
28
Source code
21
Man pages
12
Home
/
Bioconductor
/
biocthis
/
Introduction to biocthis

Introduction to biocthis
In 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:

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.

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_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:

Additional features

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

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:

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:

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

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 template GitHub issue file that is Bioconductor-friendly
biocthis::use_bioc_issue_template()

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_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:

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


Try the biocthis package in your browser

Any scripts or data that you put into this service are public.

biocthis documentation built on Feb. 28, 2021, 2:02 a.m.

R Package Documentation

rdrr.io home R language documentation Run R code online

Browse R Packages

CRAN packages Bioconductor packages R-Forge packages GitHub packages

We want your feedback!

Note that we can't provide technical support on individual packages. You should contact the package authors for that.
GitHub issue tracker
ian@mutexlabs.com
Personal blog

 
Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.

Close