Birthing the pregnancy package (Ella Kaye, University of Warwick) | posit::conf(2025)
Birthing the pregnancy package Speaker(s): Ella Kaye Abstract: When I was pregnant, I wrote a personal, private package for date and medication calculations, hard-coded with my data. I thought it would be easy to adapt for general use, but no! I wanted the user experience to be excellent, but how to avoid them repeatedly entering the same due date and meds? How to print useful, nicely formatted, grammatically correct information to the console? How to test a package that relies on the current date? Using the pregnancy package as a case study, I'll show how to take advantage of base R features such as global options and %||%, how the cli and rlang packages came to the rescue for messages and how testthat's new mocking features saved the day (literally!) to create a package that's a pleasure to use. Slides: https://github.com/EllaKaye/pregnancy-lightning-talk posit::conf(2025) Subscribe to posit::conf updates: https://posit.co/about/subscription-management/
image: thumbnail.jpg
Transcript#
This transcript was generated automatically and may contain errors.
Hello, I'm Ella Kaye. I'm a research software engineer, an R package developer and a mother. This is the very first photo of my child. I was so happy and excited to be pregnant that I did what surely any self-respecting R package developer would do. I wrote myself a package to keep track of dates and medications in my pregnancy.
I could do things like call the howfar function that would print out the progress of my pregnancy and it could do the calculation because I had hardcoded my due date into my package. The package could do other things as well and it was useful to me so I thought it might be useful for others. I decided to generalise and release the package but I wanted to make sure, as it was for me in my version of the package, that it was easy to use and that it felt personal as well. But mostly I wanted to make sure that the package was a pleasure to use.
But mostly I wanted to make sure that the package was a pleasure to use.
So today I'm going to introduce the pregnancy package, the general version, and also provide some tips and tricks that I think make a package a pleasure to use in general. In particular I'm going to talk about options and the null coalescing operator, about rlang and cli for nicely formatted and informative messages, and using utility and helper functions.
The pregnancy package in action
So here's the pregnancy package. Just like you could in my private version, you can call howfar and you will see a progress message about the pregnancy with a given due date addressed in the second person. You are so many weeks pregnant. Let's try that again for a completely different pregnancy. Again, howfar, no arguments, different due date, still the appropriate calculations, this time addressed in the first person, I am.
What if you want to use this package not about you, but say, see your partner's name reflected in the messages? That's fine too, you can do that, and you can also do more complex date calculations that you might get in online pregnancy apps. So for example, howfar a pregnancy is going to be on a given date, or the date when a particular pregnancy milestone is going to be reached.
How it works: options and the null coalescing operator
So how does it work? How can we make the package a pleasure to use by making it easy to call these functions without needing to specify these arguments like the due date and the person that aren't going to change each time you use the package?
This is the function signature for howfar, and you'll see that the due date and person arguments are both set by default to null. And then in the function code, we have the following, because we do need to have a due date to do the calculations. So first of all, on line 1, it's going to look to see whether the due date has been passed as an argument to the function. And if it has, it's good, we're good, we're done on line 1. But if it's null, as it will be by default, the null coalescing operator at the end of line 1 kicks in, and it was going to look for an option to see if that's been set, the pregnancy due date option.
If it has, again, we're good, we're done on line 2, but if not, that option is null, and the null coalescing operator at the end of line 2 kicks in, and we look for line 3, in which case we're going to get an error message as generated by the datestop utility function.
So what does that do? Well, we're using rlang and cli, and it's going to inform us exactly what the problem is, and then it's going to tell us how we can fix it. You can set the due date argument. In the second bullet, it says you can set the pregnancy.dueDate option using a helper function provided by the package, the setDueDate function, or the recommended approach is to set options pregnancy.dueDate in your R profile, because if you do that, you just need to do that once, and then in every R session in the future, that R will find that due date, and you can call any of the functions in the pregnancy package, and you will never have to specify your due date again, because it will pick it up from that option, and you get a link to the documentation to provide more details.
So if this sounds like a pure street and the package will be useful to you now or sometime in the future or for someone you know, then check out the pregnancy package, but even if not, I hope I have provided you with some useful tips and tricks to help you think about how you can make your package a pleasure to use. Thank you very much.
