Prioritizr Now Supports Code Vendoring!

Hey folks! Ready to dive into some exciting news about prioritizr? As a developer, I've been super stoked about the latest update, and I think you'll find it pretty cool too. Basically, prioritizr now supports code vendoring for its internal functions. This means it's now easier than ever to incorporate prioritizr's powerful features into your own packages. Let's break down what this means, why it matters, and how you can start using it right away.

What is Code Vendoring and Why Should You Care?

So, what exactly is code vendoring? In a nutshell, it's a technique that lets you directly copy and paste the source code of a function from one package (in this case, prioritizr) into your own. This is a brilliant strategy for a few key reasons. First off, it eliminates the need to reinvent the wheel. Instead of rewriting code for things like data validation or handling spatial data, you can simply use the battle-tested functions already in prioritizr. Secondly, it keeps your package lean and focused. You're not relying on a public API, so you're less likely to be affected by changes to the original package's interface. Finally, it gives you more control. You have a local copy of the code, so you can adapt it to your needs without waiting for updates from the original package.

Code vendoring is a major step forward, especially for those of us working with spatial planning and conservation planning tools. Prioritizr has a lot of internal functions that are incredibly useful, but weren't easily accessible before. This update changes that. You can now tap into functions for crucial tasks like parameter validation, handling CRS information from both sf and terra objects (big win!), and checking for spatial overlaps in your data. It's like having a secret weapon at your fingertips!

This update is particularly useful for anyone developing packages that build off prioritizr. It simplifies the process of integrating prioritizr's internal functionalities. The main idea here is that the source code for these functions can be directly copied into other packages, enabling users to leverage prioritizr's internal functions without the need for reimplementation or exposing these functions as part of the public API. For example, the user can utilize the validation function for validating the parameters and data, handling the spatial data, such as CRS information from both sf and terra objects. Overall, by implementing the code vendoring approach, users can streamline their package development process, avoid redundant code, and maintain control over the functions they use.

Getting Started with usethis::use_standalone()

Now, let's get into the nitty-gritty of how to use this new feature. The magic happens thanks to the usethis::use_standalone() function. This handy tool simplifies the process of downloading the necessary files from the prioritizr GitHub repository and storing them in your package. It also makes updating these local copies super easy, so you can quickly incorporate any improvements or changes from prioritizr.

To use a function, you can use the usethis::use_standalone() to automatically download a file from the prioritizr GitHub repository and store it in your package. For example, if you want to download the R/standalone-assertions_handlers.R file, you can do so by running the following command in your R console:

usethis::use_standalone("prioritizr/prioritizr", "R/standalone-assertions_handlers.R")

If you want to make a local copy of all the supported files, you can use the following code:

files  <- c("standalone-all_binary.R", "standalone-all_columns_any_finite.R", 
"standalone-all_columns_inherit.R", "standalone-all_finite.R", 
"standalone-all_positive.R", "standalone-all_proportion.R", "standalone-any_nonNA.R", 
"standalone-any_nonzero.R", "standalone-as_Matrix.R", "standalone-assertions_class.R", 
"standalone-assertions_ConservationProblem.R", "standalone-assertions_functions.R", 
"standalone-assertions_handlers.R", "standalone-assertions_misc.R", 
"standalone-assertions_raster.R", "standalone-assertions_sf.R", 
"standalone-assertions_solvers.R", "standalone-assertions_vector.R", 
"standalone-cli.R", "standalone-get_crs.R", "standalone-is_numeric_values.R", 
"standalone-is_same_crs.R", "standalone-is_spatial_extents_overlap.R", 
"standalone-repr.R")

lapply(files, usethis::use_standalone, repo_spec = "prioritizr/prioritizr")

This will download all the relevant functions into your package, ready for you to use. Make sure you have the usethis package installed before you start.

Deep Dive into the Code: Understanding the Files

Let's take a look at the file structure. You'll notice that the files you can vendor start with the prefix standalone-. This is a clear signal that these functions are designed to be used independently. You'll find these files in the R directory of the prioritizr repository (e.g., R/standalone-cli.R, R/standalone-assertions_handlers.R).

The standalone- prefix makes it easy to identify the functions that are safe to copy and use. These functions are typically self-contained and don't rely on other internal parts of prioritizr that might change. This design ensures that your vendored code will continue to work reliably even as prioritizr evolves.

Practical Use Cases: Where Code Vendoring Shines

So, where can you actually apply this new code vendoring feature? Here are a few practical use cases to get your creative juices flowing:

1. Data Validation: Imagine you're building a package that processes spatial data. You can use the vendored functions to validate the format and content of your data, ensuring it meets the required standards. This helps prevent errors and makes your package more robust.
2. CRS Handling: Dealing with Coordinate Reference Systems (CRSs) can be tricky. With vendored functions, you can easily handle CRS transformations and checks, ensuring that your spatial operations work correctly with both sf and terra objects. This is a game-changer for spatial data processing.
3. Spatial Overlap Checks: Need to determine if two spatial objects overlap? Vendored functions can do this for you, simplifying the process of identifying spatial relationships in your data. This is super useful in tasks like conservation planning, where understanding spatial relationships is critical.

By leveraging the vendored functions, you can streamline your workflow and focus on the core functionality of your package. You'll spend less time on tedious tasks and more time on the fun stuff – building amazing tools!

Conclusion: Embrace the Power of Vendoring!

In short, the addition of code vendoring to prioritizr is a fantastic improvement. It's a win-win for developers, making it easier to build robust and efficient packages. By using usethis::use_standalone(), you can easily incorporate prioritizr's internal functions into your own projects, saving time and effort. I hope this helps you guys, and I hope you will enjoy it. I can't wait to see the cool stuff you all create with this new feature! And as always, if you have any questions or run into any problems, don't hesitate to reach out. Happy coding!