Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Deprecate NASIS column name aliases #369

Merged
merged 8 commits into from
Jan 11, 2025
Merged

Deprecate NASIS column name aliases #369

merged 8 commits into from
Jan 11, 2025

Conversation

brownag
Copy link
Member

@brownag brownag commented Dec 20, 2024

This PR introduces soft deprecation of aliases to address NASIS portion of #242; it supersedes #368 which is a branch that will only be used for testing that various soilDB usages in the wild are working without aliases.

The development and next CRAN release will have warning messages and duplicate columns. In order to ensure that a particular script is compatible with the future removal of aliases, be sure it runs with an install from the "remove-aliases" branch:

remotes::install_github("ncss-tech/soilDB@remove-aliases", dependencies=FALSE)

For the deprecation of column aliases, a warning message will be issued the first time an affected function is called in a session. e.g.

f <- get_vegplot_from_NASIS_db()
#> ------------------------------------------
#> NOTE: `get_vegplot_from_NASIS_db()` column aliases will be removed in the next soilDB release.
#> Please replace use of the following column names with NASIS physical column name:
#> 	 - site_id => usiteid
#> 	 - pedon_id => assocuserpedonid
#> 	 - vegplot_id => vegplotid
#> Set `options(soilDB.warn.aliases=FALSE)` to prevent this message from displaying in future sessions.
#> ------------------------------------------

Subsequent calls to functions in the same session will not display the message. Higher level functions like fetchNASIS() and fetchVegdata() will dump quite a few of these--one for each lower-level function that has aliases currently in use, which is kindof annoying but should make the fact that things are changing fairly obvious to users.

The message gives instructions on result column names that need to be changed. For now the old aliases and the new physical column names will be duplicated in the result, so nothing will "break" and users can switch to the suggested names without disruptions other than the messages.

To prevent the alias warning messages from displaying in future sessions, there is an option that can be set,
options(soilDB.warn.aliases=FALSE), which we may want to use in some cases to limit the more verbose output that will show up in tutorials or training materials. I suggest setting this option in an invisible code block so the user does not turn off the messages in their own session, but the messages are omitted from the knitted output.

I will create a webpage on the ncss-tech.github.io repository with some additional information about the justification and overall scope of this change, with links to NASIS metadata, etc. to add to the message. See https://ncss-tech.github.io/AQP/soilDB/bulletins/2025.01-1-soilDB-NASIS-column-aliases.html

@brownag brownag merged commit 9d57cda into master Jan 11, 2025
5 checks passed
@brownag brownag deleted the deprecate-aliases branch March 1, 2025 00:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant