---
title: "Introduction to biocthis"
author: 
  - name: Leonardo Collado-Torres
    affiliation:
    - &libd Lieber Institute for Brain Development, Johns Hopkins Medical Campus
    - &ccb Center for Computational Biology, Johns Hopkins University
    email: lcolladotor@gmail.com
output: 
  BiocStyle::html_document:
    self_contained: yes
    toc: true
    toc_float: true
    toc_depth: 3
    code_folding: show
date: "`r doc_date()`"
package: "`r pkg_ver('biocthis')`"
vignette: >
  %\VignetteIndexEntry{Introduction to biocthis}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}  
---

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


```{r vignetteSetup, echo=FALSE, message=FALSE, warning = FALSE}
## 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/](https://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](http://bioconductor.org) repository for packages. `R` can be installed on any operating system from [CRAN](https://cran.r-project.org/) after which you can install `r Biocpkg("biocthis")` by using the following commands in your `R` session:

```{r "install", eval = FALSE}
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](https://github.com/) with:

```{r 'install_dev', eval = FALSE}
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](https://www.rstudio.com/products/rstudio/download).

If you are asking yourself the question "Where do I start using Bioconductor?" you might be interested in [this blog post](http://lcolladotor.github.io/2014/10/16/startbioc/#.VkOKbq6rRuU).

## 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](https://support.bioconductor.org/) as the main resource for getting help: remember to use the `biocthis` tag and check [the older posts](https://support.bioconductor.org/t/biocthis/). 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](http://www.bioconductor.org/help/support/posting-guide/). 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!

```{r "citation"}
## 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](https://github.com/features/actions) workflow for your R package(s). To use the functions in this package, you need to load it as shown below.

```{r "start", message=FALSE}
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](https://www.rstudio.com/products/rstudio/download) 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()`.


```{r 'create_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.

```{r 'create_dev'}
## 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 template for issues
  - 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
  - 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.

## `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](https://style.tidyverse.org/) but modified to make it more similar to the [Bioconductor coding style guide](http://bioconductor.org/developers/how-to/coding-style/).

```{r 'style_code'}
## 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](https://www.biorxiv.org/) as a pre-print first). Alternatively, use `usethis::use_citation()`.

```{r 'bioc_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()`.

```{r 'bioc_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](https://www.jimhester.com/talk/2020-rsc-github-actions/). Here is how you can add this GHA workflow to your R package:

```{r 'bioc_github_action'}
## Create a GitHub Actions workflow that is Bioconductor-friendly
biocthis::use_bioc_github_action()
```

### Main GHA workflow features

This [GitHub Actions](https://github.com/features/actions) (GHA) workflow is based on [r-lib/actions//examples/check-standard.yaml](https://github.com/r-lib/actions/blob/master/examples/check-standard.yaml) and others. The goal is to provide on demand `R CMD check`s 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](https://www.bioconductor.org/help/docker/) 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).
* 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](http://bioconductor.org/developers/how-to/unitTesting-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](https://help.github.com/en/actions/reference/virtual-environments-for-github-hosted-runners). It's free for open source projects, but you can also pay to use it on private repositories as explained [in their features website](https://github.com/features/actions).

### 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.

```{r "biocthis_options"}
## 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](https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions#onschedule). 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](https://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](https://github.com/lcolladotor/bioc_team_ds/blob/master/.github/workflows/build_book_bioc_docker.yml) for `r CRANpkg("bookdown")`.
* [LieberInstitute/recountWorkshop2020](https://github.com/LieberInstitute/recountWorkshop2020/blob/master/.github/workflows/check-bioc.yml) 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](https://github.com/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](https://github.com/rocker-org/rocker-versioned2/issues/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](https://github.com/r-lib/actions/commits/master.atom) for commits in their repository processed through [RSS FeedBurner](http://feeds.feedburner.com/RecentCommitsToActionsmaster) that you can [subscribe to by email](https://feedburner.google.com/fb/a/mailverify?uri=RecentCommitsToActionsmaster).

If you are interested in learning more details about how this GHA workflow came to be, check the [`biocthis developer notes` vignette](https://lcolladotor.github.io/biocthis/articles/biocthis_dev_notes.html). 

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

```{r 'bioc_issue'}
## 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()`.

```{r 'bioc_news'}
## 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()`.

```{r 'bioc_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()`.

```{r 'bioc_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()`.

```{r 'bioc_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](https://lcolladotor.github.io/biocthis/articles/biocthis_dev_notes.html).

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

```{r createVignette, eval=FALSE}
## 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.

```{r reproduce1, echo=FALSE}
## Date the vignette was generated
Sys.time()
```

Wallclock time spent generating the vignette.

```{r reproduce2, echo=FALSE}
## Processing time in seconds
totalTime <- diff(c(startTime, Sys.time()))
round(totalTime, digits = 3)
```

`R` session information.

```{r reproduce3, echo=FALSE}
## 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']])`.

```{r vignetteBiblio, results = "asis", echo = FALSE, warning = FALSE, message = FALSE}
## Print bibliography
PrintBibliography(bib, .opts = list(hyperlink = "to.doc", style = "html"))
```
