Creating an R-package with roxygen2 and devtools using Github and RStudio
Creating an R-package with devtools and roxygen2 in RStudio with versioning control in GitHub is fairly easy. First of all, we need to install the corresponding packages like this
install.package("devtools")
install.package("roxygen2")
Then we set the working directory into the folder to where we would like to create the new R-package. I for example manage my packages via GitHub and have a folder called git/
in my home folder, hence, I would type
setwd("/home/fischuu/git")
to set the working directory and then create there the package
devtools::create("PackageName")
This creates a new project which is, however, not maintined via GitHub or any versioning system. For that, we turn on the versioning control for the project. First, we open our new project (Upper right corner, Open project
). After the project was opened, we should see the project Name written in the upper right corner of our RStudio instance.
Now, we turn on the versioning system by Tools -> Versioning System -> Project Setup -> Git/SVN and there we choose Git as versioning system. Setting this up requires RStudio to restart.
Then go to GitHub and create a project with thte same name (watch out for the capitalisation) as your new RStudio project, but do *not* check any of the initialisation checkboxes, but create an empty project.
Then go back to your computer, open a terminal and navigate to your project and type there
git init
git add *
git commit -m "first commit"
git branch -M main
git remote add origin git@github.com:USERNAME/PackageName.git
git push -u origin main
This will push your files to the repository and starting from there your package is under versioning control.
You can see, that essentiall three things have been added a file called DESCRIPTION
and a file called NAMESPACE
as well as an folder called R
. First, we can edit the file DESCRIPTION
and add there the correct content and commit the change to the repository. (Go to the Github tab, check the boxes of all files and then click on commit, add your commit notes, click on commit and then on the Push button to push it into the repository).
Now, in case you have already R files containing functions that you want to turn into a package, you can copy the files into the folder called R
, otherwise you can start creating them there and define your functions.
As a first step, we will define, which functions we would like to export, meaning, which will be accessible directly for the user. For that, we write the line #'@export
in front of the function like this
#' @export
myFunction <- function(x){
...
}
We can check if this worked well by running the R-command
devtools::document()
and check afterwards the NAMESPACE
file, it should contain all the exported functions. In case you need functions from other libraries, do *not* load them with the library() command, but indicate the namesspace with the double-double-colon so that the dependencies are also automatically imported like this:
GenomicTools::importVCF()
Writing the documentation
writing the documentation is now easy, the roxygen2 syntax starts always with #'
like this
#' SHORT DESCRIPTION
#'
#' Long description
#' with as many rows as needed
#' just remember the one empty row that separated title
#' and description
#'
#' @param variable description
#' @return The return type
#' @export
myFunction <- function(x){
...
}
And once this is done we can run again devtools::document()
.
To install the package then, we can type devtools::install()
and that’s it, the first, rough version is ready and installed.