From 8c42f9452de280511ca4a208b6ecb10a4768c094 Mon Sep 17 00:00:00 2001 From: lshep Date: Fri, 14 Jul 2017 13:52:20 -0400 Subject: [PATCH] Initial Commit --- .Rbuildignore | 2 + .gitignore | 4 + DESCRIPTION | 15 ++++ MakeAPackage.Rproj | 21 +++++ NAMESPACE | 2 + vignettes/MakeAPackage.Rmd | 173 ++++++++++++++++++++++++++++++++++++ vignettes/MakeAPackage.html | 106 ++++++++++++++++++++++ 7 files changed, 323 insertions(+) create mode 100644 .Rbuildignore create mode 100644 .gitignore create mode 100644 DESCRIPTION create mode 100644 MakeAPackage.Rproj create mode 100644 NAMESPACE create mode 100644 vignettes/MakeAPackage.Rmd create mode 100644 vignettes/MakeAPackage.html diff --git a/.Rbuildignore b/.Rbuildignore new file mode 100644 index 0000000..91114bf --- /dev/null +++ b/.Rbuildignore @@ -0,0 +1,2 @@ +^.*\.Rproj$ +^\.Rproj\.user$ diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..09a72cb --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +.Rproj.user +.Rhistory +.RData +inst/doc diff --git a/DESCRIPTION b/DESCRIPTION new file mode 100644 index 0000000..c6660c5 --- /dev/null +++ b/DESCRIPTION @@ -0,0 +1,15 @@ +Package: MakeAPackage +Title: Steps to create and submit a package +Version: 0.0.1 +Authors@R: person("Lori", "Shepherd", email = "lori.shepherd@roswellpark.org", role = c("aut", "cre")) +Description: The vignette provided will have a basic sketch of the steps we + interactively went through to build a package with devtools, version control + with git, link to github, bioconductor advice, and submitting to bioconductor. +Depends: R (>= 3.4.1) +License: Artistic-2.0 +Encoding: UTF-8 +LazyData: true +RoxygenNote: 6.0.1 +Suggests: knitr, + rmarkdown +VignetteBuilder: knitr diff --git a/MakeAPackage.Rproj b/MakeAPackage.Rproj new file mode 100644 index 0000000..bfa3107 --- /dev/null +++ b/MakeAPackage.Rproj @@ -0,0 +1,21 @@ +Version: 1.0 + +RestoreWorkspace: No +SaveWorkspace: No +AlwaysSaveHistory: Default + +EnableCodeIndexing: Yes +UseSpacesForTab: Yes +NumSpacesForTab: 4 +Encoding: UTF-8 + +RnwWeave: Sweave +LaTeX: pdfLaTeX + +AutoAppendNewline: Yes +StripTrailingWhitespace: Yes + +BuildType: Package +PackageUseDevtools: Yes +PackageInstallArgs: --no-multiarch --with-keep.source +PackageRoxygenize: rd,collate,namespace diff --git a/NAMESPACE b/NAMESPACE new file mode 100644 index 0000000..6ae9268 --- /dev/null +++ b/NAMESPACE @@ -0,0 +1,2 @@ +# Generated by roxygen2: do not edit by hand + diff --git a/vignettes/MakeAPackage.Rmd b/vignettes/MakeAPackage.Rmd new file mode 100644 index 0000000..917465d --- /dev/null +++ b/vignettes/MakeAPackage.Rmd @@ -0,0 +1,173 @@ +--- +title: "Make A Package" +author: "Lori Shepherd" +date: "`r Sys.Date()`" +output: + BiocStyle::html_document: + toc: true + toc_depth: 2 +vignette: > + %\VignetteIndexEntry{Make A Package} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + +# Make A Package + +A package is a collection of functions that work together in a cohesive manner +to achieve a goal. It (should) include detailed documentation through man pages +and vignettes and (should) be tested for accuracy and efficiency. + +[Writing R extensions](https://cran.r-project.org/doc/manuals/r-release/R-exts.html) +is a very detailed manual to writing packages and what the structure of a +package entails. + +## Using `devtools` to create a package + +The `devtools` package provides a lot of options and utility for helping to +construct a new package. You can get a list of all available devtools functions +with `ls("package:devtools")`. + +Some useful references for using devtools to build packages are [Rstudio Devtools Cheetsheet](https://www.rstudio.com/wp-content/uploads/2015/03/devtools-cheatsheet.pdf) and +[Jennifer Bryan class](http://stat545.com/packages06_foofactors-package.html) + +### set up shell of a package +```{r, eval=FALSE} +library(devtools) +create("myFirstPackage") +``` + +Create will instantiate all the necessary files and sub-directories that are required +by R to be a valid package: DESCRIPTION, NAMESPACE, and R directory. You +will have to edit the DESCRIPTION to insert the information pertinent to your package. + + +After running create, the package has a valid package structure and can installed +and loaded: `install("myFirstPackage")`, `library("myFirstPackage")`, +`library(help="myFirstPackage")`. + +### version control + +It is an excellent idea to version control whenever creating a package and especially +when collaborating on a project, where multiple users are allowed to make changes. It allows +for a constant record of changes that can be advanced or reverted if necessary. + +Only a project can be version controlled, to make a directory a project in Rstudio +go to: `File -> New Project` . In this case we started creating the directory so +we follow the prompts for the option `Use Existing Directory`. Now that it is a +project we can go to `Tools -> Version Control -> Project Setup` Change the +`Version Control System` to `Git` and follow the prompts. Notice in the Rstudio +pane for environments/history/build there is a new tab Git. The package now can +start using `git` version control by making commits. To make a commit, you can go +to the Git tab, select the check box next to any files that have been modified, +added, or deleted that you would like to track, and select `commit`. Enter a new +commit message in the window that pops up and select `commit`. + +We coud stop here but we also would like put the package on GitHub. (This +assumes you have a github account). First, in Rstudio go to +`Tools -> Global Options` and select Git/SVN. Ensure the paths are correct. If you +have not linked a Rstudio project to Github, select `Create RSA key`. Close the +window. Click on `View public key` and copy the displayed public key. Now in a +web browser, open your GitHub account. Go to `Settings` and `SSH and GPG keys`. +Click on the option for `New SSH key` and paste the public key that was copied. Also +on GitHub, create a new repository with the same name as the one you created in +Rstudio using `create()`. Back in Rstudio, select `Tools -> Shell` and type the +following subsituting your github user.name and the package name. +``` +git remote add origin https://github.com//.git +git config remote.origin.url git@github.com:/.git +git pull -u origin master +git push -u origin master +``` +For instance, my package repository on github is "myFirstPackage" and my git hub +user.name is lshep: +``` +https://github.com/lshep/myFirstPackage.git +git@github.com:lshep/myFirstPackage.git +``` +Now if you look in the Rstudio tab for Git, the push and pull options are available. +You can now push and pull from/to the local version of your package and the GitHub +repository version of the package. + +### Back to making a valid package + +`devtools` proviodes built in functions for building, checking, and installing a +package. The package we created using `create` has a valid package structure but +if we did `check` we will find the DESCRIPTION needs updating. Update the +DESCRIPTION file to be appropriate for your package; throughout the development of +your package you might have to update the DESCRIPTION for appropraite Depends, Imports, +and Suggest fields. + +Now we want to start writing R functions. In Rstudio you can open an empty file +by `File -> New File` and selecting `R Script`. Save the file in the R directory. Write your functions and document. You can either document functions manually or if you use roxygen you can use the devtools function `document()`. See the [Writing R extensions](https://cran.r-project.org/doc/manuals/r-release/R-exts.html) for +manual creation of Rd files (located in the man directory) but roxygen is growing +increating popular. Some helpful links for roxygen tags can be found [Rstudio Devtools Cheetsheet](https://www.rstudio.com/wp-content/uploads/2015/03/devtools-cheatsheet.pdf) and +[Roxygen Help](https://cran.rstudio.com/web/packages/roxygen2/vignettes/rd.html). + +Some useful devtools commands while creating functions: + + * `load_all()` loads all package functions in environment to test + * `check()` checks the package (R CMD check) + * `document()` generates or updates andy documentation files + +and using the Rstudio options `Build -> Build And Reload` and `Build -> Clean and Rebuild`. + +It is also recommended to have a man page for your package. devtools provides +framework for this and creates the file that needs to be modified by calling +`use_package_doc()`. + +If you import any functions in your code, don't forget to update the DESCRIPTION +file for Depends, Imports, or Suggests. + +### Testing + +It is highly recommended to add unit tests to your package. Unit test ensure the +package is working as expect. The two main ways to test are using `RUnit` or `testthat`. +testthat functionality is included in devtools. Using `use_testthat()` will set up +the needed directory structure and add the package suggestion to the DESCRIPTION. +Here are some examples of the structure of tests for testthat: `expect_identical`, +`expect_true`, `expect_error`. There are other options as well that are discussed +in [testthat Wickham](https://journal.r-project.org/archive/2011-1/RJournal_2011-1_Wickham.pdf) +and [testthat](http://r-pkgs.had.co.nz/tests.html). + + +### Vignettes + +Vignettes are another major documentation piece to a package and more and more +repository systems (CRAN, Bioconductor, ROpenSci) and making vignettes a standard +requirement. They are a more indepth description and examples of package usage. +devtools also provides the function `use_vignette()` to set up the directory structure +and initial file for creating a vignette. For Bioconductor submissions we recommend +changing the `output:` section of the vignette header to the following (this would +require adding BiocStyle to the Suggest field in the DESCRIPTION): +``` +output: + BiocStyle::html_document: + toc: true + toc_depth: 2 +``` +A helpful rmarkdown link, which is commonly used for vignette creation can be found +here: [rmarkdown cheetsheet](http://www.rstudio.com/wp-content/uploads/2016/03/rmarkdown-cheatsheet-2.0.pdf) + + +## Bioconductor Standards +1. proper coding and efficient coding: + + * [Efficient and Robust Code](http://bioconductor.org/developers/how-to/efficient-code/) + * [Query Web Resource](http://bioconductor.org/developers/how-to/web-query/) +2. Bioconductor connection - reuse existing classes and structure - link to other packages + * [BiocViews](http://bioconductor.org/packages/release/BiocViews.html#___Software) +3. Tests + * [unitTest guidelines](http://bioconductor.org/developers/how-to/unitTesting-guidelines/) +4. complete and detailed Vignettes and man pages with executable examples +5. check time < 5min +6. package size < 4Mb +7. All package guidelines can be found [here](http://bioconductor.org/developers/package-guidelines/) + +A clean build and check and BiocCheck is not a guarantee to acceptance. It will +go through a formal view process. + +### Submitting to Bioconductor +Read the [Contributions Page](https://github.com/Bioconductor/Contributions) and +when ready to submit open a [New Issue](https://github.com/Bioconductor/Contributions/issues). The Title: should be the name of your package. Once the package is approved for building, +don't forget to set up the [webhook](https://github.com/Bioconductor/Contributions/blob/master/CONTRIBUTING.md#adding-a-web-hook) diff --git a/vignettes/MakeAPackage.html b/vignettes/MakeAPackage.html new file mode 100644 index 0000000..2ff2c24 --- /dev/null +++ b/vignettes/MakeAPackage.html @@ -0,0 +1,106 @@ + + + + + + + + + + + + + + +Make A Package + + + + + + + + + + + + + + + + + + + + +

Contents

+ + +

A package is a collection of functions that work together in a cohesive manner to achieve a goal. It (should) include detailed documentation through man pages and vignettes and (should) be tested for accuracy and efficiency.

+

Writing R extensions is a very detailed manual to writing packages and what the structure of a package entails.

+
+

0.1 Using devtools to create a package

+

The devtools package provides a lot of options and utility for helping to construct a new package. You can get a list of all available devtools functions with ls("package:devtools").

+

Some useful references for using devtools to build packages are Rstudio Devtools Cheetsheet and Jennifer Bryan class

+
+

0.1.1 set up shell of a package

+
library(devtools)
+create("myFirstPackage")
+

Create will instantiate all the necessary files and sub-directories that are required by R to be a valid package: DESCRIPTION, NAMESPACE, and R directory. You will have to edit the DESCRIPTION to insert the information pertinent to your package.

+

After running create, the package has a valid package structure and can installed and loaded: install("myFirstPackage"), library("myFirstPackage"), library(help="myFirstPackage").

+
+
+

0.1.2 version control

+

It is an excellent idea to version control whenever creating a package and especially when collaborating on a project, where multiple users are allowed to make changes. It allows for a constant record of changes that can be advanced or reverted if necessary.

+

Only a project can be version controlled, to make a directory a project in Rstudio go to: File -> New Project . In this case we started creating the directory so we follow the prompts for the option Use Existing Directory.

+
+
+ + + + + + + + +