Resources
Feb 19, 2026 |
55 min
|
1.8k views
|

Using R package structure for data science projects | Kylie Ainslie | Data Science Lab

The Data Science Lab is a live weekly call. Register at pos.it/dslab! Discord invites go out each week on lives calls. We'd love to have you!

The Lab is an open, messy space for learning and asking questions. Think of it like pair coding with a friend or two. Learn something new, and share what you know to help others grow.

On this call, Libby Heeren is joined by Kylie Ainslie who walks through how structuring data science projects as R packages provides a consistent framework that integrates documentation for you and facilitates collaboration with others by organizing things really well. Kylie says, "I stumbled on using an R package structure to organize my projects a number of years ago and it has changed how I work in such a positive way that I want to share it with others! In a world where our attention is constantly being pulled in many directions, efficiency is crucial. Structuring projects as R packages is how I work more efficiently."

Hosting crew from Posit: Libby Heeren, Isabella Velasquez

Kylie's Bluesky: @kylieainslie.bsky.social
Kylie's LinkedIn: https://www.linkedin.com/in/kylieainslie/
Kylie's Website: https://kylieainslie.github.io/
Kylie's GitHub: https://github.com/kylieainslie

Resources from the hosts and chat:

šŸ”— posit::conf(2026) call for talks: https://posit.co/blog/posit-conf-2026-call-for-talks/
šŸ”— Kylie's posit::conf(2025) talk: https://www.youtube.com/watch?v=YzIiWg4rySA
šŸ”— {usethis} package: https://usethis.r-lib.org/
šŸ”— R Packages (2e) book: https://r-pkgs.org/
šŸ”— Paquetes de R (R Packages in Spanish):
https://davidrsch.github.io/rpkgs-es/
šŸ”— {box} package: https://github.com/klmr/box
šŸ”— extdata docs in Writing R Extensions: https://cran.r-project.org/doc/manuals/R-exts.html#Data-in-packages-1
šŸ”— Tan Ho's talk on NFL data: https://tanho.ca/talks/rsconf2022-github/
šŸ”— {rv} package: https://a2-ai.github.io/rv-docs/
šŸ”— Whether to Import or Depend: https://r-pkgs.org/dependencies-mindset-background.html#sec-dependencies-imports-vs-depends
šŸ”— {pkgdown} package: https://pkgdown.r-lib.org/
šŸ”— Edgar Ruiz's {pkgsite} package: https://github.com/edgararuiz/pkgsite

Attendees shared examples of data packages in the chat! Here they are:
https://kjhealy.github.io/nycdogs/
https://kjhealy.github.io/gssr/
https://github.com/deepshamenghani/richmondway
https://github.com/kyleGrealis/nascaR.data
https://github.com/ivelasq/leaidr

ā–ŗ Subscribe to Our Channel Here: https://bit.ly/2TzgcOu

Follow Us Here:
Website: https://www.posit.co
The Lab: https://pos.it/dslab
Hangout: https://pos.it/dsh
LinkedIn: https://www.linkedin.com/company/posit-software
Bluesky: https://bsky.app/profile/posit.co

Thanks for learning with us! šŸ’›

Timestamps:
00:00 Introduction
06:17 Reviewing the disorganized project example
10:01 Creating the package structure using create_package
17:50 Organizing external data and scripts in the inst folder
22:55 Adding a README and License
29:06 "What are the advantages to packaging a project?"
33:35 Writing Roxygen2 documentation
36:06 "Do you type return at the end of your functions?"
41:55 Handling dependencies with use_package
43:53 "Can you just use require(dplyr) at the top?"
47:45 Setting up a pkgdown site
50:11 Creating vignettes
52:22 "What is the role of the usethis package?"
54:18 Loading the package with devtools::load_all

image: thumbnail.jpg

Transcript#

This transcript was generated automatically and may contain errors.

I would love to introduce our esteemed guest, our lab manager for today, Kylie Ainslie. Kylie, would you like to say hello? Sure. Hi, everybody. Thanks for coming.

All right, Kylie, tell us a little bit of background about what you do in data science and what we are going to be talking about today, because it is sort of a nice expansion of the comp talk that you gave last year at PositConf.

Yep. So I am I don't necessarily consider myself a data scientist. I am an infectious disease modeler. So I basically use math, stats and R to study how diseases spread and how interventions can mitigate that spread. And I've just I'm currently in the Netherlands, which is why it's might seem a bit dark behind me. And I've just moved to Australia to work for the University of Melbourne. But I do a lot of coding stuff.

And so I was really actually excited that Libby asked me to be here today because I would like to talk about sort of a workflow that I kind of happened upon accidentally. So I was working in a really messy way and I just got really frustrated because all of my coding projects had different organization. And so today I sort of want to talk about the way that I've found to make that messiness go away and keep everything consistent and more efficient. So I'll leave it at that for now and then we can dive in.

Awesome. Yeah, I think that this this is something that I feel might be common where you like give a conf talk and there's a bunch of stuff you wish you could have done live that you can't because it's a conf talk. You're like I have 15 minutes and I can't live code. It's going to be all messed up if something goes wrong. This is a place where things can go wrong and it's totally fine because we are just going to be sharing screens willy nilly and being like messy and transparent and open.

So with that in mind, everybody, this is the place to stop and ask questions. This is not a like wait till the end and raise your hand type of deal. This is a place where we put questions in discord and I can like interrupt Kylie and we can ask a question. So if you have clarifying questions, this is the place to ask them and be completely open and totally fine.

I wanted to let everybody know that I can't see very well out of my left eye today and I am just going to be like squinty and weird. Don't worry about me. I'm fine. I had an allergy thing last night. But if I'm a little slow today, that's what's going on. So Kylie, I will hand it back to you if you would like to go ahead and share your screen. And then if you ever want to throw it back to me or Isabella to share something, I am happy to share as well.

All righty. I have now lost my share button because I moved my Zoom chat to a different screen. There it is. OK, I'm going to be brave and just share my desktop because I have a number of different windows that I'd like to share.

Oh, look, it's Positron. Hooray. Well, we'll get to Positron later. But actually, and that's my dog. But so where I wanted to start is kind of how I came up, I came across this. So basically the the single line of this data science lab is that I want to show you how to use the R package structure to work, work better, more efficiently and to be better able to share the work that you do.

And I want to preface that with when I say R package, I don't mean to make an R package that is production ready. I mean, simply using how an R package is structured and some of the advantages that come with that to work better.

And I want to preface that with when I say R package, I don't mean to make an R package that is production ready. I mean, simply using how an R package is structured and some of the advantages that come with that to work better.

The messy PhD project folder

And so I came across this when I was doing my PhD. And this is an old project folder from one of my projects in my PhD. So we're looking here and it's got a million different files that all have that are like different versions of the same file. I had not discovered GitHub yet. You've got random like files. I don't know what these are. This is some data file. This is an R file. Oh, my God. It's a SAS file. Like and then and then I have some kind of something called FluSim, which has some code, maybe an R project. And then I've got like presentations, but then more code with the same folder as as over here.

And then there's different things. I mean, just insanity going on and then different simulations. It's like, what does MD5 mean? I have no idea. And so when I was doing it, clearly I knew what I was doing and I could, I guess, remember what these meant. But then when I had to go back a few months later to actually write up the manuscript, I had no idea where anything was.

And so after I finished my PhD, I was like, OK, I've got to do something different. And so I discovered the R package structure and I worked in a in a group that had some pretty sort of tech savvy people and they kind of helped me through it. And I guess the way that I wanted to start is rather than sort of sit here and just talk at you about, oh, this is what an R package is and this is how it's structured. I thought we could just kind of try to I can show you sort of how to set up the project, what the different folders are, what things go in them and how easy it can be to actually set it up.

Because one of the things I think that gets in the way of people using this is they think, oh, I don't know how to make an R package. And I with the sort of modern tools at our disposal, it's really, really easy. So I thought we'd just try to do it.

So actually, a friend of mine gave me a little he gave me some code that he thought would make a nice package. And I was like, great, we're just going to use this. And this is what's in it. It's just got some R files, some what looks to be data files, CSV files and a little description of what some of the functions do. And I've taken that. So this is this might look very similar to what you have for your projects, just kind of a folder with some different files in it of different types that do different things. Some of these are functions. Some of these are scripts. Some of this is data.

So what I've gone and done is I've tried to make it a little bit easier for us to see. So I've just created a folder that has some data in it. I've split out the single R script that had a bunch of different functions into individual functions. And then I've just put the scripts in a folder. So now we're going to move over to Positron.

And please stop me if I'm moving too fast or I think we're OK, but let's let me I'm going to go through Discord really quickly and make sure there's lots of people just saying like, oh, my gosh, that first messy one. Either is like cleaner than my Ph.D. was or is like, oh, no, this is giving me heart palpitations.

Kieran is being our comedy relief today, as always, with the hilarious file names like final, final, edit, final. I have shared my current project structure that I have on my screen for everybody to see. I have so many different working bays. I call my my files that are not final working bay as if I'm in Star Wars and I'm working on a spaceship. I think that we're OK as far as questions.

Yeah, awesome going. All right. Let's get started.

Setting up the package with usethis

So basically the two things that I. Use the most or did use the most in trying to create this was they use this package, which is amazing and actually make setting up the actual R file structure just really, really simple and has some really nifty. Advantages to like and allows you to connect with GitHub and all sorts of stuff, so it's fun. So we'll first just. Install some relevant packages here because I don't actually know if they're installed yet.

Live coding. Yes, so I always let a candle in anyone's life coding. It's like a superstitious thing, but I didn't like when something's gonna go wrong. Well, it probably will because I'm also pushing myself to use Positron and I usually use RStudio, but I thought, you know what? You know what? Live coding is the time to do something brand new. You're right. Yeah.

This is going to be me in about a week when we have Edgar Ruiz on to talk about the mall package as I. As I live work with LLMs, I'm sure something's going to go wrong. LLMs are so cool.

OK, it looked like that worked. So basically. We've got that. We're just going to create. I'll just do this just so people can see what package I'm using. So actually, in order to create the package is really easy. It's just. You write use create package and I'm going to call it isolator because this is actually a project that was about testing and quarantine during the COVID pandemic and the strategies to do that so that people can get out of quarantine faster.

Huzzah, look at that. I've just got a it's already made my package and. It has an R directory. It's got a couple of folders and R directory currently has nothing in it. It's got get ignore. Build ignore. These are things for GitHub and the R package build. It's got a description file, and if you've never written an R package, the description file basically tells what the package does. So we can just say. Analyzes. Sorry, guys, it's an Australian group, so I have to use an S, not a Z. Analyzes quarantine testing strategies or whatever. OK, and then we'll just put. My name, even though it's really my colleagues, but I didn't actually ask if he wants me to reveal himself. So OK, that's fine. I will. We'll pretend that this is sure, but we know we know. Should I put my email? This is being recorded. OK, great. So it's just just my name. I don't have an email. No API keys and no email needed.

Great OK description. This package does stuff. You know you write what it does. OK, cool, that's great. We did that and then the namespace space. If you also aren't familiar with it is just it's something that's automatically generated, so you don't need to mess with it, but it essentially tells what is exported and I believe imported for the package to work. So how it interacts with other packages and functions. I will come back to that. Do not edit by hand. I need that warning, because that's something I would absolutely do. Yeah, yeah, so just don't touch it. I will do stuff later and come back to it and show you what pops up there.

OK, so we don't currently have anything in this, so let's. Go back to my console. It's a new console. Great, OK. Oh yeah, different console now.

OK, what can we? What should we do next? So one of the things I want to do is just move some files, right? OK, so I now have this isolator thing and it's got an R directory. So what goes in the R directory? What goes in the R directory are the functions. So all the things that I have in this folder. Except for that readme there. Go into. Isolator. R. To be clear, we're moving from quarantine testing one. No, it's OK, we can do it. There we go. Yeah, we did it. OK, so we're going from quarantine testing to isolator.

Yes, so the quarantine testing was just. A name of a folder that I gave myself. You can create a package in the same directory that you're working in, but I like to give packages fun names, so I came up with isolator. So I thought I'll just let it. I'll just let it make a new package and that's actually a really good point. So when I ran the create package command, I just let it put the folder in my current working directory. Because I was already, but you can actually tell it where to put it if you use the create. Package. Path.

David says. Creating his first package. He wasted a lot of time editing the namespace file and then noticed it wasn't necessary when running devtools document. Yeah, see that would be me too. Yeah, and so that's actually one of the really nice things about the sort of our workflow that I'll show you is that it can actually help you catch mistakes and it'll point out some issues for you. But if your package isn't wrapped into it, or if your code isn't wrapped into a package, there's no real way to do that. And so that's one of the nice things is just sort of catching little things like, oh, you've written the wrong thing in the namespace file or you forgot to annotate what input you need here. So that's it's really helpful.

OK, so we've got our R.

I don't know why it didn't. Create the man directory. But anyway, we'll continue.

So I also one of the first things that I do is. I'll just use is I like to connect it to GitHub. So that. Of course not. Oh, you gotta use get first and then use GitHub, although it already has a get ignore file in here. I always just do it anyway. There we go. Just initializes with usethis. Yeah.

OK, so I just said use get. And so what it did is it then created or it added. Some things to my get ignore because that was previously, I think, had just this R project user line. I think so. Yeah. It added some stuff to my build ignore. I think. Yes. I don't think it did anything to my. Didn't do anything else. OK.

And then use. And Megan is saying that you might need to run document to generate the main folder. Oh, OK. Fair. Although we don't have any. So, OK, cool. We'll we'll get there. We'll get there. Everybody. Let's see if this works. If it doesn't, I'll just leave it.

I don't want to do it. I don't have to do it. I'm going to do it. I'm going to do it. I'm going to do it. I'm going to do it. I'm going to do it. I'm going to do it. I'm going to do it. I have a set up. That's OK. We can get this. We'll skip this.

Just know that if you do have a personal access token set up or any other form of security into GitHub, then you can do use this. Use GitHub. And it's going to create your remote repo for you on GitHub.com. It will open it in the browser. And that is about all that happens. So I think we're good. We can skip it. Yeah, it's all good.

Organizing files in the inst folder

The other thing that I thought would be good is that, so remember we had some different kinds of files. So we had, I've of course now closed my finder, but we had some scripts and we had some data. And those aren't necessarily automatically added, but it's quite easy to add them yourself. So in an R package, all of that sort of other stuff that doesn't have a specific place. So like the help files, which we'll generate later, the code files and other types of things go into the inst folder.

And then within the inst folder, you can have a play. You can have whatever you want. I typically have a folder called X data or external data. And then one that's called like examples or scripts. So we'll call this one examples. And then we can go into our, oh, here it is. So we had data and we had scripts. And these are often really useful.

I mean, it's very useful to keep all of your files for a given project together. But an R package wants them put in a very specific place. So for our scripts, which have really fun names, don't blame me. We will put them in examples.

I'm really struggling with moving files today. It's okay. One thing that I have, like, I remember I took a fundamentals of package dev workshop in 2023 from Andy Tuescher, which was amazing at Conf. And one thing I feel like he explained, but I forgot is what all of the abbreviations mean. And I don't remember them anymore. I don't know if anybody does. But like man manifest manual. Manual.

I think there's the the inst where I'm like, is inst always. Instance instantiate, like, I don't even know. Tell me all of the names and what they mean. Discord.

Because sometimes there is a manifest in a project, but this is manual. Yeah, exactly. That's why that's why I thought it'd be nice to kind of go through the structure, because it's for the first time you're seeing it. It's not necessarily intuitive, particularly. Because there's a man folder. And then if you do certain if you use certain kinds of documentation like vignettes, then there's a docs folder.

So if we don't have it yet, that'll inst folder, which has examples and X to data. And I'm guessing X to data external data. Yep. And that's that's just an old convention, but you don't actually have to call it that. You can call it data. You can you can call it whatever you want. So I kind of think of the inst folder as sort of my special folder where I can really do whatever I want.

So basically the R package build kind of now somebody correct me if I'm wrong, but the R package build kind of ignores it. It's like, OK, this is other stuff and doesn't put too many regulations on what that stuff is. So it is not going to be accessible through the package as data that's built in. No, not unless you assign it as such.

But if it's if this package is wrapped in a GitHub repo, then it's available via the GitHub repo. Yeah. So I haven't I haven't found a I know there's ways to make data accessible, but that's a part of the workflow that I'm. I'm not I haven't gotten to yet.

So the other thing about this is that I've been using this approach for years and it's I've slowly improved, but it's it's not like I have all the answers or I do it perfectly. So I'm so glad you're here. If you if you look back at my older projects, they're they're kind of they're terrible. You know, the documentation is kind of rubbish and there's stuff all over the place. And then as I've tried to just sort of iterate this with future with with more projects, it's slowly gotten better. I've learned different things. I've learned best practice, best practices by copying other people, all that.

So the other thing about this is that I've been using this approach for years and it's I've slowly improved, but it's it's not like I have all the answers or I do it perfectly.

OK, fantastic. And that question about X to data also came from Sam. Sam, thank you for asking. I think that we will get around to other stuff. But also, if anybody has details about writing a package that is a data package and what that looks like, please answer Sam in the discord. And I'm going to go grab an example of a data package and how it's structured right now.

Adding a readme and license

All right. Take it. Take it away, Kylie. All right. Awesome. Yeah. So one of those things that's really great to sort of best practices that I just mentioned that I've gradually learned is having things like a readme to tell you tell anyone who's looking at your package what it does and maybe how to use it or how it's structured, any sort of data sources. And so you can also use this, use this to add some of these features. So you can add a readme file.

And I like to use the RMD. And so this creates a readme file. And then the other thing that's also really good to have, particularly if you want to make your code public, is a license file. And that tells people how they can and cannot use your code.

And there you see here we've got now a license. And I've just picked the MIT, which is a pretty standard, gives people a lot of freedom to use. Yeah. But you can see that there. And then now this line has been added to our description folder that says this package is covered by the MIT license. So it's just as easy as that. There are different licenses. You can pick which one your organization may have a specific one that they want you to use.

So those are all good things. So I guess one thing that I think is really nice is the readme. So obviously there's nothing in here right now.

And while you are looking for that, everybody in the chat, thank you so much for sharing examples of data packages. Sam had asked about, like, where does the data go that you want your user for your package to be able to see. And a bunch of us shared different data packages. I shared the Richmond Way package by Deepshim and Ghani, which is a count of all the times Roy Kent says the F word in DevOsso. So if you want to go play with that, please go do.

And there are lots of questions and answers in the Discord. So thank you, everybody, for being amazing answerers. And please tag me in a reply to something if I have just missed it and it's a question for Kylie.

All right. I'm just filling out the readme a little bit. So because basically I have two different files here. One is an MD and one is an RMD. And an RMD is an R Markdown file. MD is a Markdown file. And an R Markdown file just looks a bit nicer. Or at least you can look at it a bit easier.

And so now we have some very basic stuff. Almost nothing on our readme, but we can actually build it. Let's see if this works. Oh, fingers crossed. I have no idea. But notice what it's doing. It's installing your package in a temporary library and building out the readme file in the isolator folder. Now, did it work?

Also, things might look different in Positron versus RStudio for the RMD. Yeah, so it should actually have a. It should sort of pop it up. Does anyone know how to look at a. Like it should have. So this is just the raw version, but it should actually. Yeah, so at the top there's a source and visual as well. So you could check out the visual rendering of it if you wanted to. Or you could render it, which is the top left button in your pane.

Which is like right under the description M. There's like a little button. Under description. Yeah. Sorry, the meeting. Oh, or is it covering everything? It's just above. It's at the top left of your source pane. Top left source pane. Yeah. Help. This is my source pane. Yes. So to the left. OK. To the top left. Visual render on save. Yep. The button to the left of render on save. Sure. Use visual mode. Here. There it is. OK.

Yeah, I mean, it doesn't look great, but it's close enough. But basically it makes it look nice, and you can tell people how to install your package. You can have examples, all that kind of stuff. And you can have it with your project. And so it's a really powerful tool because you can actually tell people what your code does. You can show them how it works, and you can show them what to expect from it.

A finished readme example

So to give you a better example of a more finished version is that I wrote my first CRAN package last year. And so my readme has things like what the package does. It's called Mighty. It's based on a Scabies project. It's so fun. How to install it. Yeah, it's a super might. And some features about how long it should take, the main functions. So if people are just trying to get oriented, which functions they're probably going to use. It's not a very big package. And then how you use it. And so all this is available when someone is just looking at this package. It's not hidden anywhere. It's right front and center.

And so I found that to be really helpful for myself, but also for anyone else who I might want to collaborate with. I can show them, hey, this is what I'm working on, or anyone who may want to actually use the package. Yeah, and if you are just creating a project that is not a package and you are still using this project structure to keep yourself straight, that readme might not look the same. You might not be, like, instructing people to use things. But you could have descriptions of the main questions in your data, the main findings in your analyses, things like that.

Advantages of R package structure over templated folders

And there was a question. Yeah, although. Oh, go ahead. No, I was going to stop really quickly. There was one from James that was, what are the advantages to packaging a project compared to more generalized templated folder structure like R Markdown data and R? Or, like, you know, some people will have, like, instead of R, it'll be called source. And then you might have a data with a data raw and data final or just data. So what are the advantages of doing it in the R package style?

Yeah, so that's a great question. So I would say the biggest advantage is how you share it and how other people can access it. So if you have that file structure that you mentioned where you've just got everything nice and organized and neat, if somebody wants to use your code, they still have to download all of those files. But if you have it wrapped in an R package and you have it somewhere that they can access it, whether that's a shared network drive at work or GitHub or GitLab, all they have to do to use the code or to reproduce what you've done is a single line of code that's installed from GitHub or install packages.

So I would say the biggest advantage is how you share it and how other people can access it. But if you have it wrapped in an R package and you have it somewhere that they can access it, whether that's a shared network drive at work or GitHub or GitLab, all they have to do to use the code or to reproduce what you've done is a single line of code that's installed from GitHub or install packages.

And so it just makes it so much easier to use.

The other really added benefit is that when it's in a package structure, it sort of forces you to do some documentation things, which I'll go through next, like documenting, you know, functions, inputs, outputs, expected behavior and things like that, that you don't have to do if you're just working sort of by yourself in your own project. But that then make your package way, way easier to use.

And they're automatically generated. And they're automatically generated when you build the package, which doesn't happen if you just use a nice organized file structure.

So if you want, we can go through a quick example of sort of the benefits of some of that documentation, because I think that's really one of the main benefits of using this approach is that there are different ways to document what you're doing, and they help you because then you have to actually explain what you've done. So if you come back to it, you know what you did, you know what decisions you made, maybe during an analysis. You know what you did.

But also anyone else. I mean, what if you have to hand over a project to someone? Then you're like, oh, I've got to write handover notes. But actually, you can build all that into an R package and say, here you go. It explains what to do.

And Tan made a great point, which is tooling for R packages is very robust, right? So like you're not on your own. You have roxygen2 for commenting. You have tests that you have usethis especially, which is already like building you whole structures and skeletons. So I agree. I think that's a really big benefit.

You also have a whole textbook. You do have a whole textbook. Which is excellent. And this book is excellent. It's really helped me.

So you have help. So that's why I say actually using this structure may seem like a bit of work at first, but it really has some benefits if you just get over that hump. And the likes of Jenny and Hadley have made that hump so much smaller in recent years.

I remember back when I first made an R package and I had to use something called R package skeleton or something. And I don't know what package it came from. I think that was the function name. And it was very confusing. Also, devtools hadn't been broken apart yet. So it was really big. It was much harder back then. Things always get better over time.

Writing roxygen2 documentation

We have about 22 minutes left. Let's see how much further we can get in our example project here. I told you I could fill 50 minutes, Libby. I told you.

So I'm going to try to just write some quick R oxygen preamble. So the first thing I've done is I've just added this apostrophe rather than just a typical comment. So this is recognized by roxygen2. Is it roxygen2? R-Oxygen? How do you all say it? I say roxygen2. I also say roxygen2.

I say R-Oxygen, but I think the correct is roxygen2. It's just I've been programming for like 15 years and now I have to change how I say something. It's really hard. It does not matter. You know what? Code is a written language, not always a spoken one. And I say say it however you want.

So anyway, we'll go through this. So hopefully we can generate a man file. So basically with roxygen2 preamble, you write it before any of your functions. And it should have sort of a title-ish or a very brief statement of what the function does and then more details on the function. This is a really simple one that just abbreviates Australian state names. But then you can use you can specify what goes into the function. So in this case, the parameter is any sort of input argument, and that is state names, if I can spell.

And then name. Oh, we can say also don't judge me on how these functions are. I didn't write them. Not that they're bad. Just yeah. So I'll just do character string.

Kylie will not be taking questions at this time about the code. I actually got this tip from Jenny Bryan because I watched a talk of hers about making packages, and she put the type of argument and then what it does. And I thought, oh, actually, that's really helpful because just saying maybe number of, I don't know, scabies mites on your skin doesn't necessarily tell you if it needs to be a character string or a number or an integer or something. So I've started to use that name of Australian state.

Luckily, this one only has a single parameter. So then we also want to put what we expect the function to return, which this function was written poorly and there is no return. So I guess it returns. There's an implicit return here, not an explicit.

I got into it one time with somebody over implicit versus explicit returns. I would love to see people in the chat. Tell me, do you type return at the end of your functions or do you leave it implicit? I am an explicit girly. Every single person. Every single thing I do. I want it to be like clearly typed, clearly telling you what you're going to get. Everybody in the chat is saying explicit. Thank you. Thank you, y'all.

I mean, I'm kind of tempted to just. Like, change this or actually, why don't we just do this? Let's just do to RTN. And then return RTN. Yep. It's classic.

I actually don't know what state names is supposed to be like. Is it a vector? I actually don't know. Your question. Anyway. We'll figure this out later. But converted state names.

So the other thing is that you can specify what dependencies it has. So in this case, we need to import. Does anyone know what package case when is from? dplyr. Okay. So we can import from. dplyr.

I was writing trivia for virtual day last year. This is great. I'm going to start just taking over the data science lab to do my own projects and ask live questions. This is the power of not vibe coding, but pair coding where you get, you know, extra brain or in this case, extra 60 something brains that are helping you.

This is the power of not vibe coding, but pair coding where you get, you know, extra brain or in this case, extra 60 something brains that are helping you.

I think that's good. And then you export it, which basically means you want the function to be sort of visible. If anyone has a better explanation, please. Export. It means like it's accessible through a double colon with your namespace. So when you type out isolator and then your double colon, it's like not hidden and accessible as a function in your package. I think that that's right. To stop me if I'm wrong. I see Megan nodding. So I'm like, yeah, okay. I think I'm right.

Running devtools::document()

I'm going to try to basically sort of implement this preamble that I've just written by doing devtools document. Oh, what? Oh, no. Oh, no. What is happening? Install. I thought you lit a candle. And we weren't going to have any live coding problems.

Okay. Did this work? I think so. Let's try it again. I mean, wait, library, library. Oh, sorry, guys. Sorry. Sorry. I'm losing it. Can't see out of one eye. Having live coding problems. Okay. It worked. It's fine. It's fine. I knew I was taking a risk. All right. Let's try it. Things will probably break. Oh, okay. Nothing broke. Okay. Let's go look.

Okay. Whoever said the man folder would appear when we did document. Megan. Absolutely right. Thank you, Megan. We have a man folder. And I don't know why it has figures, but sure, that's great. Oh, there must be figures in my readme file. And then we have this automatically generated RD file, which has all the information that we put in. And because we hit export, let's go look at our namespace. It had export and import. So that's awesome.

And the cool thing is I think isolator is already loaded. So the other great thing about an R package that you don't get with a different file structure is that if you're using your own package or someone else's and you think, what does this function do? Or what type of argument do I need? You should be able to use abbreviate states. I think we misspelled abbreviate.

Booyah, look at that. Automatically generated help file that you can access by just using a question mark and the name of the function, rather than having to go search through some sort of file structure to find a readme or go through comments in the code. It's right there. Amazing. So that's, yeah. I love it.

I see somebody wondering this package that like doesn't exist on CRAN is being installed on Kylie's machine locally by the devtools package. So creating R packages is its own whole thing. And like they exist in like temporary folders while you are building them and stuff. So that's a little bit more complicated, but just rest assured that's what's happening in the background.

And the other thing that now we need to deal with is that because I've told the package gods that I need to import from dplyr, now I need to make sure that in our description file we have the dependencies listed. So there should be a section for the packages that your package depends on, or if you have a vignette, what packages that needs. And usethis makes this really easy. Sorry if I'm not explaining it very well. So you just say use package, dplyr, and type equals imports.

So that means that when your package is installed, it will also install dplyr because in order for our functions or this particular function to run, we need dplyr and we do that. And now look at that. Our description file has imports dplyr. That's amazing. So it's really, really easy. And so roxygen2 rocks.

But the other piece about it that I talk about in my talk, which I'm sure is a more eloquent version of this lab, is that you can actually write that preamble as your live coding. You know, you're writing a function to do stuff, and you can actually just quick do, let's see if I can find it again. You can just quickly say, okay, what parameters, what kind, what do I expect?

Because I don't know about you, but with me, I'll write a function and then I'll change my mind and I'll say, oh, I have this as a matrix. Oh, but I think a data frame would be better or I had a character, but this is getting too confusing. It's a string. I need a number. I'll just convert it. So I change my mind and I can kind of keep track of all of that by just updating the preamble. And then, you know, if you use something like GitHub or version control, you can obviously keep track of the changes that you've made, but it's always there. And so you can just do that as you're writing. And so it's something that I've started to do. It's like I'm making a function. And rather than writing all of my code and then going back and documenting it, I'm starting to do it as I code.

Yeah, that's another great benefit. All right, I want to stop really quickly and ask Jen's question, which was, can you just use require dplyr at the top? And that's a good question. I don't use require a lot. And I am the worst person to answer this question. I don't either, but at the top of what? At the top of like the function page or the function script?

That is, I think what it is, because we were requiring case when for our function. And so I think that the question was like, could you just put require dplyr at the top instead of that sort of like dependency of needing to have the package use dplyr?

So my intuition, and I can't explain why is that something would break because isn't require like require just only works if you're running that script, right? So if you actually like source that script, then it will run require. Whereas this actually is embedded in the information of the package. So when you download the package, even if you never, ever use this function, you'll still be able to use it because all of the necessary dependencies have been installed. Yeah, I think that that is correct. I know that you cannot use library within a package. That's not something that you're going to be doing.

I do not use require. I think I've only ever used import. So if you, oh yeah. Ken says in the actual function itself, not in the comments to it. So yeah, if anybody has extra information on when you use require. And how you use import pop it in the chat.

So I tan says that library and require actually modify the user's namespace, which is in capitals. Very, very proud upon. So again, we're, I'm not a software developer. So when we get to some of these technical things, I've just kind of followed standard practice and tried not to break things. So explaining, but yeah, it's a great question. I'm just not super able to answer it.

And Daniel also says like require returns true false. So if the package doesn't exist, it's just going to be false and it's not going to error. So then you'll have a really bad time when you actually try to use the function. So for packaging it's better to do your, your requirements and your imports and stuff.

And David under also says like requiring library are going to work locally, but when you install the package, it will not install those dependent packages because they are not in that sort of import dependency. Thank you everybody for hopping in the chat and helping us all learn together.

Building a pkgdown website

There's two things that I want to try to do in the next eight minutes. So one Libby, this one's for you is we can make a pkgdown website. That's my favorite part. So you can make, if you want to, you can make a pkgdown website. And I hope this works because you know, I haven't connected it to anything. Fingers crossed. We don't have a, we don't have a kit of repo.

Oh, it's not an exported object from namespace. Use this. Oh, because I didn't install it. Down package. I just stuck package down as a package in the chat. It's also one of my favorite tech stickers. That little brown box is so cute.

I'm just not firing on all cylinders here. It's the curse of coding. There we go. Doesn't working. So now we have, we've done use package down. It's added some stuff to our directory.

Oh, added docs. We don't have any docs. Okay. Well, we don't have anything to actually show, but it's got this pkgdown YAML, which is great. And it's just done some setup for us. And then let's all fingers crossed that this works. We can actually just in two lines of code, I think we should be able to build a site.

Everybody cross your fingers. Installing a temporary copying. Oh my God, everybody. No. Fancy. What is fancy? Do we have a dependency somewhere? Probably. That we have not explicitly imported. Probably because there's a billion. That stinks. I really wanted to. That's okay. Well, anyway, it is that easy. If you don't have, you know, I'm just going to install fancy. I don't know where it came from, but.

Let's see if that allows us to do it. Daniel Chen says install packages until it works. Who knows what fancy is, but it needed it and we did it. Yeah, so this is nonsensical because this is basically just the basic readme with the title. My name, our license, but it was that simple. So now you can have.

This and you can. Yeah, this shows what functions we've only exported one function. You know, it's not very fun bunch of functions in there. That reference then becomes like, hey, here is a web page for each of your functions and like all the information about it. And for that to be automatic is amazing.

And for that to be automatic is amazing.

Vignettes as analysis notebooks

Yeah, and then when you want to the next. And one of my favorite aspects of our package is the vignette. So I was talking about how the readme you can combine code and results and text and everything. You can also do that. Well, it's the same file, same file format. So with a vignette, you can have our markdown file, which shows which has the analysis that you've done. And actually, I can show an example.

So this is the package that I made. So this is the readme that I showed you earlier, which is always the homepage of the pkgdown site. But then I have some vignettes and some of them is like a quick start guide. So, you know, welcome to my package. Let's load some required stuff. Let's. This is what it's going to do. Here's some useful information. And then let's start doing stuff with data. Let's simulate some data. Let's look at it. Let's visualize it. And then let's use the package to do stuff. And that's really awesome.

So you could think of actually this, this could be your sort of lab notebook. You could use this as like, I'm doing my analysis, right? And you can, you can just kind of work, work through it. And to set up the vignettes is again, very, very simple. It is just news.

And you can use different engines inside of use vignette. So like, if you wanted to use Quarto as your engine, you could, or Markdown is your engine. I am not an expert in all of that, but you can go check out the vignette engines and Google away and you will find lots of info.

Libby's talking about this particular here. There you go. Yeah. Our engine. Yeah. For a long time, Quarto wasn't, wasn't supported. And so. But nowadays, which is awesome. Cause I was looking to switch. I've run into some snags with the Quarto engine just lately, specifically around using the library function. So. There might be some snags still or some rough edges, but it's going in the right direction.

use_package and declaring dependencies

There was a question earlier, we only have 3 minutes left. It was, what is the role of the use this of use package in everything that we did? Because I've always strayed away from require slash library, but wondering if I'm off the use package. I think that's what we talked about earlier where like, we want it to be sealed into our package as a dependency and have our package be able to access it. So that can use it in other functions.

Yeah. So the, so the, the use package, all it does is just. Tells it adds a line to your description file and basically says that in order to use the functionality of the package that you're making, you need to use functions from other packages. So it's just declare. Yeah. It's just declaring those dependencies. That's all it's doing. So it's, it's not. And then it actually, then when you, when you load the package or install the package, then if those dependencies aren't already installed in your machine, it will then make sure that you. That they are installed and they're all wrapped up in packages with your actual package.

Yeah. We only have a minute left. If there's one more thing we can button up, then we're good. And then everything else that didn't get answered. We will try to answer in the chat.

Yeah. So I guess the other great thing about this is now that we have this package while we're testing it, you can actually install everything in one line. So if, if it's on GitHub or something, this changes. But while you're, while you're working, let's say, you know, you go away, you close your computer, you come back and you want to start using this rather than having to source all those different files or write a file. That sources all of them. You just go into your package directory and type devtools load all and it loads everything. So it. So then now you can just use it as if you were using any other package, even though this is very much being built. And I found that saves a lot of time when just working on something.

You just go into your package directory and type devtools load all and it loads everything. So then now you can just use it as if you were using any other package, even though this is very much being built.

I love it. Yeah. I hope everybody learned a lot. We're at the top of the hour. So we will let you go. We know that you have meetings to go to Kylie. Thank you so much for joining us today and walking us through and being vulnerable and live coding. I hope that you learned a ton. Please hop in the chat and thank Kylie for being so, so brave to live code in front of the entire Internet.

If you have extra questions, pop them in the chat. We will come through and attempt to answer them. Thank you for spending time with us. See you on Thursday. Hang out if you would like to come to that and then see you next week where I think we have Edgar going through the mall package and Elmer. Thank you so much. We'll see you in a couple of days or a week. Bye, everybody. Bye, everybody. Thanks for joining.