14.5 Write a package in R - Video Tutorials & Practice Problems

<v Voiceover>Writing C++ code is nice,</v> but it's even better if you can integrate it into a package. Doing so has never been easier, thanks to RStudio and DevTools. But, before we learn to put C++ into a package, let's refresh building a package with just R Code. To do this we'll come up to File, New Project, inside of RStudio. We'll say New Directory. This will create some of the files we need automatically. RStudio even has this helpful R Package type. That will automatically create some of the files for us. I'll call it, BasicCpp. and I will open it in a new window, so I still have this previous project. Go ahead and click Create Project, and now we are ready to get started. A lot of this was covered in previous live lessons and in Chapter 24 of R for everyone. This will be a quick refresher. When getting started with a package we need to make sure the description files in good shape; let's take a look at it. Come to File, Open File, Description. Now remember, the Description File has to say the word description in all capital letters with no extension. And in here are some basic fields that we need to enter. The first of which is, the Package which is the name of the package in our case BasicCpp. The Type is Package. And the Title is what the package does. We'll say Illustrates C++ code. We're starting at version 1.0.0 and it was last updated today's date. The Author is who wrote it, which in this case is me. The Maintainer, and they are very particular about this, at first has to be the person's name. Not necessarily the same as the author. Then in angle brackets the email address of that person. Now CRAN is very particular about this, the email address put here has to match the email address you upload the package to CRAN with. Now for the description you can put in, a little description about your package as the name suggests. We will just say some sample C++ code with R code. The license is very important. They used to be the case that you could just declare license such as BSD or MIT but if you want to be on CRAN they are now very particular that it has to be a specific type of license, plus must contain an extra license file describing it further. We will use the BSD_3_clause license plus include a file called License. We'll look at the file in a moment. For extra speed, I want to make sure the package is Byte compiled so I will say Bytecompile:TRUE. We can save this now. As for the License File, we have to go ahead and create that now. So I will hit control, shift N on the keyboard to create a new file, and this file takes exactly three entries, one row each. The first is the year, this can be a range of years but we'll just say 2014. The Copyright Holder, which in this case is Jared P. Lander. And the organization, which I'll put as my company, Lander Analytics. And leave an empty line at the end. I'll save this as the License File. Now you notice, RStudio automatically put an extension .DCF on this file. We need to get rid of that extension. So I will close this tab. Go to the open dialog and rename the file. Getting rid of that extension. It'll ask me if I'm sure I want to do that, I say yes. I'll go ahead and open it, just to be certain that it's okay. There's also a Namespace file but we'll let the package Roxagen2 take care of that automatically. Now that we have our package ready to go, let's write our first function that will be all R Code. When we started this project, RStudio created an empty R File for us, so lets go look at that. It's in the R folder and all of your R code must be in the R folder. And it's called Basic CPP.R. As you can see, it's empty. So lets go in there and build a simple little function that just takes two vectors and adds them together. We will say addbase &lt;- function(x, y). This function will simply return x+y, and we're done. However, you should create a proper Help File and you must create a proper Help File if you want it to be on CRAN. We will take advantage of the Roxagen Comment Block to make this easy for us. For such a small function, it will seem like we're doing a lot of typing to create this comment block, but it automatically creates your manual help files and makes life easier. So above the function, each line starts with a hash and a single quote. And then we have tags, such as @title and that's the name of this function which is add base. We have a description with a function which is just add two vectors. And if you want to include details you will say add two vectors using base R. We have aliases, which is just the name of the function in this case. we also want to make sure we export the function. If we don't export it, it won't be exposed to the end user. Declare the author. And you have to specify the arguments and what they are. You do that by saying @peram space, the name of the argument, space and a description. Our description will just be a vector. But of course, this function is just built right into R's just addition, but this just illustrate how to build a function. Our next argument, @param y a vector. And you tell it what the return value will be which is the addition of x and y. And you should provide some examples. Notice I used examples not example cause if you put in an example it's actually looking for a file containing examples. But putting in @examples, then you can put the code right in line. For our example, you will just do addbase(1:10, 1:10). This way when end user looks at your help files they will see working examples. If the examples fail, the package won't build. Now that we're done inputting this function, and all of it's help information let's save the file, go to the console and load DevTools. Say require(DevTools). And what we're about to do requires the package R oxygen 2. We are simply going to type in document, () since we're doing it on this package. And then we'll automatically create Help Files and update the Namespace. Look at that, let's go check out our Namespace. Open, come to the root of the folder, go to Namespace. It automatically added export(addbase). That means this function will be available to the user. If we want to, we can build this package by saying build(), and that's all there is to it. But, we'll refrain. Let's come to the Build Tab in RStudio and click Build and Reload. We get a little warning, but that's okay and we see it built the package and loaded for us automatically. We could run addbase, let's say 1:10 and 1:10 and we get the numbers we expect. It is that simple to start building an R Package. All you need to do is have the proper description and License Files and let DevTools take care of the rest.