BiocCheck

BiocCheck

BiocCheck provides additional package checks different from `R CMD check` that follow Bioconductor best practice and recommended guidelines

There are two ways to run BiocCheck after installing the package.

1. As R function: BiocCheck( <package> )
2. Command Line: `R CMD BiocCheck <package>`

​

Caveat: There is also BiocCheckGitClone (we will review the difference later)

Set Up / Process Overview

This assumes you have a github account and git installed:

1. Fork the BiocCheck github repository to your personal github https://github.com/Bioconductor/BiocCheck
2. Create a new branch for your changes/improvements
1. It is recommended to make changes on a branch so that your master branch always is a clean checkout and able to merge changes from the Bioconductor repository.
3. Make Changes
4. Run `R CMD build` and `R CMD check` to ensure it builds/checks with no errors
5. Commit changes to your branch
6. Submit a pull request to Bioconductor

Demo forking and creating branch

https://github.com/Bioconductor/BiocCheck

​

Editing Code

How you choose to edit and make changes to code will depend on what you as a programmer are used to but the two most highly used ways:

​

1. Command Line
2. RStudio

​

This assumes you forked to your local github as previously shown and you have git installed on your computer for version control.

​

Command Line

1. git clone git@github.com:lshep/BiocCheck.git # change lshep to your username
2. cd BiocCheck
3. git fetch --all # gets all branches
4. git checkout -b my_cool_newfeature origin/my_cool_newfeature
5. Make code changes in your favorite editor # don’t forget documentation/NEWS/etc. Not just R code!
6. cd .. && R CMD build BiocCheck && R CMD check BiocCheck_x.y.z.tar.gz

Command Line

​

• cd BiocCheck
• git add <files> # repeat as necessary (git status and git diff could be helpful)
• git commit # make sure to leave a detailed informative commit message!
• git push origin my_cool_newfeature

RStudio

Some useful links on creating package from scratch and version control can be found at

​

https://github.com/lshep/MakeAPackage

https://github.com/shwetagopaul92/biocmeetup

​

Rstudio

​

This assumes you have git set up on your computer and with Rstudio

1. Make a new project: File -> New Project
2. Choose: Version Control
3. Choose: Git
1. Repository Url: https://github.com/lshep/BiocCheck ( change lshep to your github username)
2. Project Directory Name: BiocCheck
3. Your choice of where you would like the folder created!
4. Choose: Create Project
• Rstudio should load in the BiocCheck directory
• Notice the Git tab now available

​

Rstudio

1. Click on the new Git tab
2. Change the branch from master to your my_cool_newfeature branch
3. Close the terminal pop up that appears

​

Now you are git tracking your local changes to your github repository on the special branch you created

​

Make your code changes

Rstudio

Commit changes locally

1. Go to Git tab
2. Select files that have changed that you want to commit
3. Press: Commit
4. Write a commit Message in the appropriate text box
5. Select Commit
6. Close terminal that appears
7. Close Rstudio: Review Change box

Rstudio

Don’t forget to build and check the package!

Two ways:

1. Package devtools
1. library(devtools) # if you don’t have it installed install.packages(“devtools”)
2. build( )
3. check( )
2. Using Rstudio Terminal (Recommended)
• Open Terminal: Tools > Terminal > New Terminal
• cd ..
• R CMD build BiocCheck
• R CMD check BiocCheck_x.y.z.tar.gz

Rstudio

Push changes to Github

1. Go to Git tab
2. Commit any file changes you want to be pushed up to github
3. Select Push
4. Follow the prompts for username and password if they appear
5. Close terminal box

If you check github your changes will be uploaded if it was successful

Creating Pull Request

From your personal github (e.g. https://github.com/lshep/BiocCheck)

1. Make sure you are on your branch
2. Click on `New pull request`
3. Make sure you are able to merge into Bioconductor/BiocCheck master branch
1. If there is a conflict, you must resolve the merge conflict. If you need help or guidance on merge conflicts please reach out to the core team
4. If able to merge, create a detailed description of what the change/new feature includes and click on `Create pull request`

​

Important!

The Core Team will not merge just a Pull Request of R Code!

You must also update:

1. NEWS (required)
2. Vignette (required)
3. Bonus points: Unit tests!
1. We always recommend unit tests to ensure the check is functioning properly
4. Bonus points: For new higher level checks, flag to turn check off
• We incorporated these flags as there were requests from other groups that they wanted to use some but not all of the checks we implemented especially since some are very Bioconductor specific. This allows the flexibility of those groups to still utilize BiocCheck for their code base. All check in Bioconductor are default ON!

Code Organization

The R files

BiocCheck.R

Main function exposed to end users.

One liner calls to functions in checks.R organized by different package sections: Broadly: dependencies, version numbers, Description, Namespace, Vignette, Coding practices, man pages, news file, unit tests, formatting, package naming, support site registration (see vignette)

Each check in this file has a `handleCheck( )` with message that appears as output in the BiocCheck

Contains flags to turn off any of the high level check contained in this file

The R files

BiocCheckGitClone.R - same as BiocCheck but...

There are some checks that Bioconductor implemented that could not be done on the built tar.gz file like checking for bad file types or formatting of author/maintainer fields.

The built tar will exclude certain files or lose extensions so they would not be able to be checked but that should not be included in Bioconductor’s copy of the git repository

The built tar will reformat the description appropriately from the original file.

These types of checks are therefore intended to only done on a fresh clone of the git repository.

The R files

utils.R

Contains helper functions to the checks.R functions.

- Helps keep checks.R functions more readable and maintainable

- Contains helpers that are used in multiple function calls

* handleError, handleWarning, handleNote, handleMessage

The R files

checks.R - This is the file you will most likely be adding/modifying

Functions are in order of the sections they appear in the BiocCheck

There can be multiple checks per section or a new section can be added but try and group the checks according to what it is checking

Each check should contains a handleNote( ), handleWarning( ), or handleError( ) with a descriptive short message to indicate the check failure and the severity. If appropriate a handleCheck( ) could also be included.

Additional informative output should use handleMessage(“ “, indent=6)

To keep check readable put helper functions directly after they are used or in utils.R

​

Vignette

The Vignette follows the order of checks in BiocCheck.R.

This clearly identifies the different sections of a package being checked at any given time.

For EVERY/ANY new check or modified check the section in the vignette should be updated for a detailed description of the severity, causation, and reasoning. The header of the section is what text would appear in the BiocCheck output (i.e handleCheck)

Any new or updated use of handleCheck, handleNote, handleWarning, handleERROR will need an entry in the vignette.

Unit Tests

BiocCheck uses RUnit to do its testing.

The file is inst/unitTests/test_BiocCheck.R

There are test packages in inst/testpackages to add specific test cases in a repository setting

As BiocCheck is performed, a running count of Notes, Warnings, and Errors occurs. `.zeroCounters` returns the counter to zero for the next check. There is a .note, .warning, and .error object that keeps track of the numbers and text. inspect() will print out the current status of all. An individual counter can be accessed with .error$getNum() or .error$get()

​

​

Don’t Give Up

The Core Team appreciates every effort your making. We want your changes to be included.

Coding around other programmers code can be challenging and frustrating. Don’t give up!

This is meant to be a FUN community event so remember your resources! The slack channel is a great resource to engage other programmers and the core team if you need advice or are getting stuck.

We would encourage forming small groups too!

Live Check-Ins

Developers Forum - Thursday May 21 12:00 pm EST

https://bluejeans.com/114067881

​

Friday Review: Friday May 22 11:00 am EST

https://bluejeans.com/296225857

​

Hack-a-thon Open Issues

https://github.com/Bioconductor/BiocCheck/projects/1

​