search

vegandevs / vegan

R package for community ecologists: popular ordination methods, ecological null models & diversity analysis
https://vegandevs.github.io/vegan/
GNU General Public License v2.0
452 stars 98 forks source link

CRAN release & adonis deprecation: Request for Comments #523

Open jarioksa opened 2 years ago

jarioksa commented 2 years ago

I am planning a new CRAN release of vegan in the latter half of August. There are quite a few changes, although nothing very dramatic. For most users the main thing may be wider and robuster support for tidy dialect and ggplot graphics. See NEWS for details of the numerous other changes.

For release the main thing may be that I had planned to deprecate adonis in favour of adonis2 in this release. adonis2 was released in vegan 2.4-0 on Jun-15 2016 or more than six years ago, but it seems that most dependent packages still use adonis. I ran reverse dependence tests, and found out that six packages will issue a WARNING if adonis is deprecated: betaper, GUniFrac, microbial, RVAideMemoire, SigTree and smartsnp. In addition, QFASA passes tests without WARNING, but uses adonis without explicit import as vegan::adonis(). Similar test is performed in CRAN and new WARNINGs are flagged as changes to "worse", and may cause ripples in the smooth submission process. Therefore I'd like to avoid those changes to "worse". I planned to deprecate adonis already in the current release 2.6-2, but just to avoid problems I changed warning() to message("'adonis' will be deprecated: use 'adonis2' instead") which is not flagged in the CRAN process. I also emailed to those package authors on 15-Apr 2022. My dependence tests were less complete then, and did not include many packages dependent on BioConductor, and I only found five "worse" cases. Two of these were fixed promptly (dispRity and microeco), but three are still in the current list of regressions.

I'm still uncertain what to do or what should be the deprecation policy. My initial plan was just to phase out and remove adonis and leave only adonis2. However, dispRity defines an S3 method for adonis (and correctly handles adonis2), and obviously prefers to keep the name. One choice is to keep the name adonis in vegan, but eventually synonymize it with adonis2. The API is similar in both and if the function is just used via vegan API, users should see no difference (adonis2 offers more choices, but default is similar as old adonis). However, if packages try to access the internal structures of the result object, they will fail because intestines of adonis and adonis2 are completely different.

One way to proceed is:

  1. Keep the 2.6-2 behaviour in the next release: print message() of future deprecation, but run adonis.
  2. In a future release, print message, but run adonis2. That is, to remove adonis code and make commands adonis and adonis2 synonyms. This will give an error if there is a package that tries to access internals of the result object, but normal use should see no difference.

I just wonder, if there should be one release in between with warning to alert those package authors that access the adonis2 result object directly.

CC: @cstewartGH @ChristianHuber @TGuillerme @ChiLiubio

TGuillerme commented 2 years ago

Thanks for the heads up @jarioksa! I'm happy to go with either option (i.e. the release in between with warning or the straight synonymy). I'm also happy to change the S3 in dispRity to .adonis2 if that helps (I kept it as .adonis since I imagine people are familiar with that function name - but I might be wrong). I'm going to publish a release (1.7) this week so I can quickly add the change before it goes to CRAN.

cstewartGH commented 2 years ago

Hi Jari,

Thank you so much for this email and an opportunity to provide feedback on this issue. I apologize for the late response, but I have been on vacation and it has taken me some time to get through my emails.

I was also planning a new QFASA CRAN release and aiming towards the end of the summer or early fall. I will plan to simply switch the adonis function calls to adonis2 in the new version - hoping that this can be done without any major issues. As such, it should not make too much of a difference for QFASA how you decide to proceed.

I do have one question, if you don’t mind. I am by no means an expert on R packages and I’m wondering if you could elaborate on your comment: In addition, QFASA passes tests without WARNING, but uses adonis without explicit import as vegan::adonis(). In particular, I was wondering if the QFASA R package is doing something unusual that should be fixed?

Thanks again! Connie

Dr. Connie Stewart Professor • Department of Mathematics and Statistics Ganong Hall, Room 200 • Saint John T 506 648-5725 [University of New Brunswick] [Facebook]/uofnbhttps://www.facebook.com/uofnb [Twitter] @unbhttps://twitter.com/UNB [Instagram] @discoverunbhttps://instagram.com/discoverunb/ UNB.cahttp://www.unb.ca/ Confidentiality Note: This email and the information contained in it is confidential, may be privileged and is intended for the exclusive use of the addressee(s). Any other person is strictly prohibited from using, disclosing, distributing or reproducing it. If you have received this communication in error, please reply by email to the sender and delete or destroy all copies of this message.

From: Jari Oksanen @.> Sent: August 8, 2022 7:58 AM To: vegandevs/vegan @.> Cc: Connie Stewart @.>; Mention @.> Subject: [vegandevs/vegan] CRAN release & adonis deprecation: Request for Comments (Issue #523)

✉External message: Use caution.

I am planning a new CRAN release of vegan in the latter half of August. There are quite a few changes, although nothing very dramatic. For most users the main thing may be wider and robuster support for tidy dialect and ggplot graphics. See inst/NEWS.Rd for details of the numerous other changes.

For release the main thing may be that I had planned to deprecate adonis in favour of adonis2 in this release. adonis2 was released in vegan 2.4-0 on Jun-15 2016 or more than six years ago, but it seems that most dependent packages still use adonis. I ran reverse dependence tests, and found out that six packages will issue a WARNING if adonis is deprecated: betaper, GUniFrac, microbial, RVAideMemoire, SigTree and smartsnp. In addition, QFASA passes tests without WARNING, but uses adonis without explicit import as vegan::adonis(). Similar test is performed in CRAN and new WARNINGs are flagged as changes to "worse", and may cause ripples in the smooth submission process. Therefore I'd like to avoid those changes to "worse". I planned to deprecate adonis already in the current release 2.6-2, but just to avoid problems I changed warning() to message("'adonis' will be deprecated: use 'adonis2' instead") which is not flagged in the CRAN process. I also emailed to those package authors on 15-Apr 2022. My dependence tests were less complete then, and did not include many packages dependent on BioConductor, and I only found five "worse" cases. Two of these were fixed promptly (dispRity and microeco), but three are still in the current list of regressions.

I'm still uncertain what to do or what should be the deprecation policy. My initial plan was just to phase out and remove adonis and leave only adonis2. However, dispRity defines an S3 method for adonis (and correctly handles adonis2), and obviously prefers to keep the name. One choice is to keep the name adonis in vegan, but eventually synonymize it with adonis2. The API is similar in both and if the function is just used via vegan API, users should see no difference (adonis2 offers more choices, but default is similar as old adonis). However, if packages try to access the internal structures of the result object, they will fail because intestines of adonis and adonis2 are completely different.

One way to proceed is:

  1. Keep the 2.6-2 behaviour in the next release: print message() of future deprecation, but run adonis.
  2. In a future release, print message, but run adonis2. That is, to remove adonis code and make commands adonis and adonis2 synonyms. This will give an error if there is a package that tries to access internals of the result object, but normal use should see no difference.

I just wonder, if there should be one release in between with warning to alert those package authors that access the adonis2 result object directly.

CC: @cstewartGHhttps://github.com/cstewartGH @ChristianHuberhttps://github.com/ChristianHuber @TGuillermehttps://github.com/TGuillerme @ChiLiubiohttps://github.com/ChiLiubio

— Reply to this email directly, view it on GitHubhttps://github.com/vegandevs/vegan/issues/523, or unsubscribehttps://github.com/notifications/unsubscribe-auth/AEUC2MAUJXP52EFNLNM4D43VYDR2JANCNFSM554VYPIA. You are receiving this because you were mentioned.Message ID: @.**@.>>

gavinsimpson commented 2 years ago

I've done a PR on QFASA to add an importFrom(vegan, adonis) statement: cstewartGH/QFASA#13 But I assume this isn't a major problem other than the fact that it still uses adonis() and @jarioksa you wanted to throw deprecation messages that would complicated getting this on CRAN?

I think a recent commit (23f683329772f2d26e6534728514113be1ad6bb5) from you @jarioksa has loosened the deprecation warnings to just a message. So I assume you are going with something like your wondering "if there should be one release in between with warning to alert those package authors that access the adonis result object directly."

My personal opinion would be that we eventually make adonis() defunct (so we must deprecate it first) - I want old code to error rather than silently (or otherwise) return a different object if the version of vegan I am using has changed that much.

I appreciate this will cause some CRAN headaches but so long as we follow the approved route of contacting maintainers, then deprecating adonis() officially for a point release before making it defunct in a later point release, the problem will become that of other package maintainers to either update their code to use adonis2() or find some other solution.

cstewartGH commented 2 years ago

Thank you for this! I have updated the QFASA package with adonis2() (which required a few changes to my code) but I am still in the process of making other changes to the package and haven't submitted it to CRAN yet.

jarioksa commented 2 years ago

vegan 2.6-4 is now on CRAN. It will extend the mercy period and only print a message of future adonis deprecation. That deprecation will happen when the current devel version (2.6-5) will be released. The following packages still use adonis according to reverse dependency tests: betaper, GUniFrac, microbial, RVAideMemoire, SigTree, smartsnp.

christianangulo450 commented 1 year ago

Hello, dear friends. I would like to know how I can get the pdf. file to learn how to use vegan.

jarioksa commented 6 months ago

I am about to publish next version of vegan (finally) with deprecation of adonis. Reverse dependence tests still found five packages that call adonis.

RVAideMemoire is actively maintained, and one of its core functions switched to adonis2. There is still one function to call adonis, but the issue looks easy to handle, and I have emailed the maintainer with suggestions.

Packages betaper, microbial, SigTree and smartsnp have not been fixed. I emailed to maintainers in 2022, but none of them answered. The latest CRAN versions of these are from 2017 to 2021, and the packages may be forgotten and unmaintained. I'll mail these maintainers again, but I do not expect responses now (I did not get any responses in 2022).

I have not looked at the source code of these four packages, and I do not know how adonis is used there and how simple the fixes can be. I do not see much reason to check this if I cannot reach the maintainer. I did look at the RVAideMemoire code because it had more recent versions and the maintainer could be reached.