Customized Strategy to Deprecate Multiple Arguments in An R Package

Recently, I switched my job to a new lab where they have an R package that needs maintainance. I won't talk about the detail of my to-do list, but here is a point that worth taking a note.

The scenario is, there are arguments, a lot of, that need to be renamed. One reason for renaming them is that we are trying to keep a nice and consistent coding style. Another reason, more importantly, is that some arguments are super confusing. There are arguments meaning the same thing across different functions (e.g., "the maximum number of nearest neighbors to search", seen in UMAP, graph based community detection and etc.), but named differently (e.g. k, nNeighbor, knn_k and etc.). Nevertheless, there are arguments meaning different things but named in the same way (e.g. k for number of dimensions to use in function 1, k for number of nearest neighbors to search in function 2, and etc.). All of these makes our package confusing for users.

Changing argument names is not really a big deal. The pain point is that users might find their scripts fail with unused-argument-error if we just simply rename the problematic arguments. We need to utilize some lifecycle control tools to notify users that some arguments are being renamed, and finally make it comes true until a period of time has passed, when we are pretty confident that most of our users have seen this message.