Package 'biocthis'

Add Bioconductor README badges

Description

These functions add markdown text to the README to include all or individual badges from the Bioconductor landing page.

Usage

use_bioc_badges()

use_bioc_build_badge(which = c("release", "devel"))

use_bioc_support_badge()

use_bioc_rank_badge()

use_bioc_history_badge()

use_bioc_last_commit_badge()

use_bioc_dependencies_badge()

Arguments

which

Which branch to report the build status for. Possible values: "release" (default) or "devel".

Details

• use_bioc_badges(): adds all badges listed below, mimicking the Bioconductor landing page

• use_bioc_build_badge(): badge indicating Bioconductor build status for either the devel or release branch

• use_bioc_support_badge(): Bioc support site activity in the last 6 months (answered posts / total posts)

• use_bioc_rank_badge(): ranking by number of downloads

• use_bioc_history_badge(): how long since the package was first in a released Bioconductor version (or if it is in devel only)

• use_bioc_last_commit_badge(): time since last commit

• use_bioc_dependencies_badge(): number of recursive dependencies needed to install the package

See Also

usethis::use_badge()

Examples

## Not run: 
## Add all Bioc badges at once
use_bioc_badges()

## Add just the Bioc build status badge for devel
use_bioc_build_badge("devel")

## End(Not run)

---

Tidyverse style made Bioconductor-friendly

Description

This function uses styler::tidyverse_style() and modifies it to make it Bioconductor friendly. The full Bioconductor coding style is described at https://bioconductor.org/developers/how-to/coding-style/ and it shares many properties with the Tidyverse coding style guide https://style.tidyverse.org/. This function defines the transformers code that you can then use with other styler functions such as styler::style_pkg().

Usage

bioc_style(indent_by = 4, ...)

Arguments

indent_by	How many spaces of indention should be inserted after operators such as '('. Unlike styler::tidyverse_style(), the default is 4 to conform with the Bioconductor coding style.
...	Other arguments passed to styler::tidyverse_style().

Details

The styler package seems to be more actively maintained and better performance than formatR, though that package can also be useful. This function does not produce an exact Bioconductor coding style, but it gets you close enough! =)

For more details on how this function came to be, check https://github.com/r-lib/styler/issues/636 https://github.com/Bioconductor/BiocCheck/issues/57 https://github.com/Bioconductor/bioconductor.org/issues/54

Value

A list() object with the information required by functions in the transformers argument in the styler package functions such as styler::style_pkg().

Examples

## Not run: 
## Run these functions in your package
styler::style_pkg(transformers = biocthis::bioc_style())
styler::style_dir(usethis::proj_path("dev"), transformers = biocthis::bioc_style())

## End(Not run)

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

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

---

Create a temporary example package

Description

This function creates a temporary example package. It is used by the functions in biocthis to illustrate the functionality of the package without exposing users to internals of usethis that users do not need to use under typical working conditions.

Usage

biocthis_example_pkg(name = "biocthisexample", use_git = FALSE)

Arguments

name	A character(1) with the name of the example package.
use_git	A logical(1) indicating whether to set up git through usethis::use_git() on the temporary example package.

Details

This function creates a package under tempdir() with the name provided and uses usethis::proj_set() for setting the project directory. Users do not need to rely on usethis::proj_set() under typical scenarios. In other words, if you are running R interactively, usethis will set the directory for you.

Check https://github.com/lcolladotor/biocthis/commit/dc387807623f0e945432d15f0d0f899de1b1dd9d#r39102094 for more details that motivated this function.

Value

A character(1) with the path to a temporary example package to use in the examples of the biocthis functions.

Examples

## Create an example temporary package for illustrative purposes
pkgdir <- biocthis_example_pkg()

---

Create a biocthis-style CITATION template

Description

This function is very similar to usethis::use_citation() except that it uses a template from biocthis. This template can help you get started with a citation file for your Bioconductor package. You can compare the template produced with the one from usethis::use_citation() to pick and choose the parts you like best from each.

Usage

use_bioc_citation()

Value

This function adds and/or replaces the inst/CITATION file in your R package.

Examples

## Not run: 
## Run this function in your package
use_bioc_citation()

## End(Not run)

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

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

---

Create a Bioconductor-styled code of conduct

Description

This function is very similar to usethis::use_tidy_cov() except that it uses a template from biocthis. This template links to the Bioconductor Code of Conduct available at http://bioconductor.org/about/code-of-conduct/. The function adds by default the file .github/CODE_OF_CONDUCT.md with a brief overview of the Bioconductor Code of Conduct and links to the latest version.

Usage

use_bioc_coc(path = ".github")

Arguments

path	A character(1) specifying the location where the CODE_OF_CONDUCT.md will be saved at in relation to the root of your R package.

Value

This function adds and/or replaces the .github/CODE_OF_CONDUCT.md file in your R package.

Examples

## Not run: 
## Run this function in your package
use_bioc_coc()

## End(Not run)

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

## Create a Bioconductor-styled CODE_OF_CONDUCT.md
biocthis::use_bioc_coc()

---

Create a biocthis-style DESCRIPTION template

Description

This function is very similar to usethis::use_description() except that it uses a template from biocthis. This template includes some of the information expected in the DESCRIPTION file of a Bioconductor package. You can compare the output of this function to the one from usethis::use_description() to select the parts you want from each.

Usage

use_bioc_description(biocViews = "Software", report_bioc = TRUE)

Arguments

biocViews	A character() with the Bioconductor biocViews terms you want to use for your package. See https://bioconductor.org/packages/release/BiocViews.html for details. Note that the terms you choose have to be part of one of the main four trees: software, annotation, experiment or workflow.
report_bioc	A logical(1) indicating whether to set the BugReports to the Bioconductor Support website https://support.bioconductor.org/ or to the GitHub package issues page.

Details

For details about the DESCRIPTION file guidelines for Bioconductor packages check http://bioconductor.org/developers/package-guidelines/#description.

Value

This function adds and/or replaces the DESCRIPTION file in your R package.

Examples

## Not run: 
## Run this function in your package
use_bioc_description()

## End(Not run)

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

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

---

Create a biocthis-style GitHub feature request template

Description

This function is very similar to usethis::use_tidy_issue_template() except that it uses a template from biocthis and is tailored for feature requests.

Usage

use_bioc_feature_request_template()

Details

For more details on how this function came to be, check https://github.com/lcolladotor/biocthis/pull/33.

Value

This function adds and/or replaces the .github/ISSUE_TEMPLATE/feature_request_template.md file in your R package.

Examples

## Not run: 
## Run this function in your package
use_bioc_feature_request_template()

## End(Not run)

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

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

---

Create a biocthis-style GitHub Actions workflow

Description

This function is very similar to usethis::use_github_action() except that it uses a template from biocthis. It creates a Bioconductor-friendly GitHub action workflow for your package. You can also use this GitHub Actions workflow by executing usethis::use_github_action().

Usage

use_bioc_github_action(
  biocdocker,
  pkgdown = getOption("biocthis.pkgdown", FALSE),
  testthat = getOption("biocthis.testthat", FALSE),
  covr = testthat,
  covr_coverage_type = getOption("biocthis.covr_coverage_type", "all"),
  RUnit = getOption("biocthis.RUnit", FALSE),
  pkgdown_covr_branch = getOption("biocthis.pkgdown_covr_branch", "devel"),
  docker = getOption("biocthis.docker", FALSE)
)

Arguments

biocdocker	A character(1) specifying the Bioconductor docker version you want to use. Valid names are "devel" or in the "RELEASE_X_Y" format such as "RELEASE_3_11". Check http://bioconductor.org/help/docker/ for more information on the Bioconductor docker images. If you don't specify this, it will be determined automatically using your current Bioconductor version. The R version will be set to match the Bioconductor version.
pkgdown	A logical(1) specifying whether to run pkgdown. Check https://cran.r-project.org/web/packages/pkgdown/index.html for more information on pkgdown which is useful for creating documentation websites. If TRUE, then pkgdown will only run on the Linux (Bioconductor docker) test.
testthat	A logical(1) specifying whether to run testthat. Check https://cran.r-project.org/web/packages/testthat/index.html for more information about testthat which is useful for unit tests. The testing chapter at https://r-pkgs.org/tests.html is also very useful.
covr	A logical(1) specifying whether to run covr. Check https://cran.r-project.org/web/packages/covr/index.html for more information about covr, which is useful for displaying for assessing your test coverage. If TRUE, then covr will only run on the Linux (Bioconductor docker) test.
covr_coverage_type	A character(1) specifying the code used to calculate the covr coverage. Option are package "tests", "vignettes", "examples", "all", or "none". The default is "all".
RUnit	A logical(1) specifying whether to run RUnit unit tests. Check http://bioconductor.org/developers/how-to/unitTesting-guidelines/ for more information about RUnit.
pkgdown_covr_branch	A character(1) specifying the name of the GitHub branch that will be used creating the pkgdown website and running covr. Since biocthis version 1.9.3 this changed from "master" to "devel" by default to match https://twitter.com/Bioconductor/status/1631234299423850497.
docker	A logical(1) specifying whether to build a docker image with the resulting package. This will also create a Dockerfile. You can alternatively try using this excellent template: https://github.com/seandavi/BuildABiocWorkshop.

Details

For the full history on how this GitHub Actions workflow came to be, check the "biocthis developer notes" vignette https://lcolladotor.github.io/biocthis/articles/biocthis_dev_notes.html.

Value

This function adds and/or replaces the .github/workflows/check-bioc.yml file in your R package.

Examples

## Not run: 
## Run this function in your package
biocthis::use_bioc_github_action()

## End(Not run)

## I have the following options on my ~/.Rprofile set
## Check
## <https://github.com/lcolladotor/biocthis/issues/9#issuecomment-702401032>
## for more information.
options("biocthis.pkgdown" = TRUE)
options("biocthis.testthat" = TRUE)

---

Create a biocthis-style GitHub issue template

Description

This function is very similar to usethis::use_tidy_issue_template() except that it uses a template from biocthis.

Usage

use_bioc_issue_template()

Details

For more details on how this function came to be, check https://github.com/r-lib/usethis/issues/1108.

Value

This function adds and/or replaces the .github/ISSUE_TEMPLATE/issue_template.md file in your R package.

Examples

## Not run: 
## Run this function in your package
use_bioc_issue_template()

## End(Not run)

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

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

---

Create a biocthis-style NEWS.md file

Description

This function is very similar to usethis::use_news_md() except that it uses a template from biocthis.

Usage

use_bioc_news_md(open = rlang::is_interactive())

Arguments

open	Open the newly created file for editing? Happens in RStudio, if applicable, or via utils::file.edit() otherwise. This argument has the same behavior as the open argument used in usethis functions.

Details

Unlike the original function, use_bioc_news_md() does not make git commits. So you won't lose work you didn't save when using this function.

Value

This function adds and/or replaces the NEWS.md file in your R package.

Examples

## Not run: 
## Run this function in your package
use_bioc_news_md()

## End(Not run)

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

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

---

Create a biocthis package template R scripts

Description

This function creates the dev directory and in it, it creates R script files that you can follow to create your own Bioconductor-friendly R package. These R scripts include all the commands you need to get started =) The commands are designed to be run on the order given, though we also encourage you to check the latest utility functions in the usethis package.

Usage

use_bioc_pkg_templates(open = rlang::is_interactive())

Arguments

open	Open the newly created file for editing? Happens in RStudio, if applicable, or via utils::file.edit() otherwise. This argument has the same behavior as the open argument used in usethis functions.

Details

For more details on how this function came to be, check: https://github.com/r-lib/actions/issues/84 https://github.com/r-lib/styler/issues/636 https://github.com/Bioconductor/BiocCheck/issues/57 https://github.com/Bioconductor/bioconductor.org/issues/54 https://github.com/r-lib/usethis/issues/1108 as well as the "biocthis developer notes" vignette https://lcolladotor.github.io/biocthis/articles/biocthis_dev_notes.html.

Value

This function adds and/or replaces the dev files in your R package. That is:

• ⁠dev/01_create_pkg.R⁠

• ⁠dev/02_git_github_setup.R⁠

• ⁠dev/03_core_files.R⁠

• ⁠dev/04_update.R⁠

Examples

## Not run: 
## Run this function in your package
use_bioc_pkg_templates()

## End(Not run)

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

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

---

Create a css with Bioconductor colors for pkgdown

Description

This function creates the pkgdown/extra.css file with Bioconductor-style colors that will make your pkgdown documentation websites much cooler ^_^.

Usage

use_bioc_pkgdown_css()

Details

For more details on how this function came to be, check https://github.com/lcolladotor/biocthis/issues/34.

Value

This function adds and/or replaces the pkgdown/extra.css file in your R package.

Examples

## Not run: 
## Run this function in your package
use_bioc_support()

## End(Not run)

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

## Create a css file to style your pkgdown website in Bioconductor colors
biocthis::use_bioc_pkgdown_css()

---

Create a biocthis-style README.Rmd file

Description

This function is very similar to usethis::use_readme_rmd() except that it uses a template from biocthis. This template README.Rmd includes information on how to install your Bioconductor package, how to cite it, and thanks the authors of several packages. It was built on top of the original template from usethis::use_readme_rmd().

Usage

use_bioc_readme_rmd(open = rlang::is_interactive())

Arguments

open	Open the newly created file for editing? Happens in RStudio, if applicable, or via utils::file.edit() otherwise. This argument has the same behavior as the open argument used in usethis functions.

Value

This function adds and/or replaces the README.Rmd file in your R package. It's useful to use devtools::build_readme() after running this function or whenever you update the README.Rmd file.

Examples

## Not run: 
## Run this function in your package
use_bioc_readme_rmd()

## End(Not run)

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

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

---

Create a biocthis-style GitHub support file

Description

This function is very similar to usethis::use_tidy_support() except that it uses a template from biocthis.

Usage

use_bioc_support()

Details

For more details on how this function came to be, check https://github.com/r-lib/usethis/issues/1108.

Value

This function adds and/or replaces the .github/SUPPORT.md file in your R package.

Examples

## Not run: 
## Run this function in your package
use_bioc_support()

## End(Not run)

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

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

---

Create a biocthis-style vignette template

Description

This function is very similar to usethis::use_vignette() except that it uses a template from biocthis. This template includes instructions for citing other packages using RefManageR, uses sessioninfo::session_info() for displaying the R session information since it includes GitHub installation information and other useful details. The template also includes a section on how to ask for help and required knowledge.

Usage

use_bioc_vignette(name, title = name)

Arguments

name	Just like in usethis::use_vignette(): base for file name to use for new vignette. Should consist only of numbers, letters, _ and -. Lower case is recommended.
title	Just like in usethis::use_vignette(): the title of the vignette.

Value

This function adds and/or replaces the ⁠vignettes/<name>.Rmd⁠ file in your R package.

Examples

## Not run: 
## Run this function in your package
pkg <- basename(usethis::proj_get())
biocthis::use_bioc_vignette(pkg, paste("Introduction to", pkg))

## End(Not run)

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

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

---

Use the tinytest framework for unit tests

Description

This function works similarly to usethis::use_testthat. It sets up the minimal files required to make tinytest compatible with the current project.

Usage

use_tinytest()

use_tiny_test(name = NULL, open = interactive())

Arguments

name	Either a string giving a file name (without directory) or NULL to take the name from the currently open file in RStudio.
open	Whether to open the file for interactive editing.

Value

• use_tinytest: creates a tinytest.R file in the tests directory

• use_tiny_test: creates a ⁠test_<name>.R⁠ file in the inst/tinytest directory where are to reside

Functions

• use_tiny_test(): add a unit test file for testing functions in the current R file

---