Thread by @neilgcurrie

You've probably installed a bunch of packages in R.

But did you know they are a fantastic way to organise your own analysis?

A thread on how to write your own package in R.

#rstats #coding #datascience

Packages are collections of code and data, combined together into one tidy bundle.

This makes them great for analysis projects - not just for downloading packages like dplyr or data.table.

Writing a package might sound intimidating but I'll show you how.

1/20

Let's say you have code, data and outputs for some analysis in a single folder.

If you aren't working inside an R project already click File > New Project > Existing Directory > Browse (select the folder) > Create Project.

2/20

You are now working inside an R project.

To double check look and see if an .Rproj file has appeared in your directory. In the top left hand corner you should also see the name of your project.

3/20

Now we will turn this project into a package.

From inside the project we need to run usethis::create_package(getwd(), check_name = FALSE).

There are some rules around the format of package names for uploading to CRAN. We won't upload to CRAN so check_name = FALSE here.

4/20

A prompt may appear asking you overwrite the .Rproj file - answer yes by typing the correct number.

Your project is now a package.

But what does that mean practically?

5/20

You should see the following has appeared in your directory:

- a DESCRIPTION file
- a NAMESPACE file
- an 'R' folder

6/20

The key thing that identifies this as a package to R is the DESCRIPTION file.

You will want to edit the package and other information in here.

Additionally, you will want to add any other packages which your analysis uses in here under Depends.

7/20

When we come to load our package later this means you don't need to load the other packages you were using manually. They will be loaded automatically.

The NAMESPACE file we don't need to worry about for now. R will edit this automatically.

8/20

Before creating a package you might have stored functions in one file (and called source to read them to memory) or maybe they were in your analysis file?

In a package functions live in the 'R' folder.

You can organise them anyway you want really.

9/20

I like having a file for each function unless it makes sense not too.

For instance, I include helper functions in with its 'parent' function and, where it makes sense, I will group 'families' of functions together.

10/20

Packages make documenting your functions super easy - this is an important and often overlooked part of software development.

You can do this with the roxygen2 package. Explaining in depth would take a while so I will leave for a future thread.

11/20

In the mean time have a look at:

cran.r-project.org/web/packages/r…

When you have written your documentation you can run devtools::document() to update it.

Now when you run:

?functionname

your help files appear in the Help pane, just like the pro packages you already know.

12/20

Packaging your code also makes unit testing easy.

Inside your package you can run all your tests at once using devtools::test() in the console.

I wrote a thread about unit testing last week if you aren't familiar with it or need a refresh.

13/20

https://twitter.com/neilgcurrie/status/1569717576112181250

Now it's time to organise our files into something more sensible.

I have created the following folders (though feel free to change this setup):

- analysis, analysis scripts live here
- data, raw data goes here
- output, outputs from our code go here.

14/20

Some good practice tips:

- treat the raw data inside the data folder as read only i.e. don't modify it

- anything produced in the output folder you should be able to recreate by running your scripts

15/20

When working on your analysis script use devtools::load_all() or the keyboard shortcuts (Ctrl/Cmd + Shift + L) to load all your functions into memory.

This will also load any packages you specified in the DESCRIPTION file under Depends.

16/20

Putting it altogether your workflow will look something like this:

1. Edit functions
2. Write tests
3. devtools::test
4. Write documentation
5. devtools::document
6. Ctrl/Cmd + Shift + L or devtools::load_all
7. Edit analysis scripts.

And repeat. The order will vary.

17/20

I appreciate that was a very quick introduction of how to build a package.

Some of the tips here might change if you were writing a package for CRAN.

I hope that is enough to get you up and running, and shows you how achievable creating a package is.

18/20

To recap:

- Packages are a great way to organise analysis projects
- You can turn existing analysis into packages
- Testing and documenting functions is easy with a package
- Packages improve your workflow
- Writing a package sounds intimating but it's not too tricky

19/20

Thanks for reading, if you liked this thread follow me @neilgcurrie for mainly R and data tweets.

No code for this one, but code and links to my other threads can be found here:

github.com/neilcuz/thread…

20/20

https://twitter.com/neilgcurrie/status/1572254358397681665