R devel - Mar 2023 - Query: Could documentation include modernized references?

On 26/03/2023 11:54 a.m., J C Nash wrote:
> A tangential email discussion with Simon U. has highlighted a long-standing
> matter that some tools in the base R distribution are outdated, but that
> so many examples and other tools may use them that they cannot be
deprecated.
> 
> The examples that I am most familiar with concern optimization and
nonlinear
> least squares, but other workers will surely be able to suggest cases
elsewhere.
> I was the source (in Pascal) of Nelder-Mead, BFGS and CG algorithms in
optim().
> BFGS is still mostly competitive, and Nelder-Mead is useful for initial
exploration
> of an optimization problem, but CG was never very good, right from the
mid-1970s
> well before it was interfaced to R. By contrast Rcgmin works rather well
> considering how similar it is in nature to CG. Yet I continue to see use
and
> even recommendations of these tools in inappropriate circumstances.
> 
> Given that it would break too many other packages and examples to drop the
> existing tools, should we at least add short notes in the man (.Rd) pages?
> I'm thinking of something like
> 
>      optim() has methods that are dated. Users are urged to consider
suggestions
>      from ...
> 
> and point to references and/or an appropriate Task View, which could, of
course,
> be in the references.
> 
> I have no idea what steps are needed to make such edits to the man pages.
Would
> R-core need to be directly involved, or could one or two trusted R
developers
> be given privileges to seek advice on and implement such modest
documentation
> additions?  FWIW, I'm willing to participate in such an effort, which I
believe
> would help users to use appropriate and up-to-date tools.
I can answer your final paragraph:

Currently R-core would need to be directly involved, in that they are 
the only ones with write permission on the R sources.

However, they don't need to do the work, they just need to approve of it 
and commit it.  So I would suggest one way forward is the following:

- You fork one of the mirrors of the R sources from Github, and (perhaps 
with help from others) edit one or two of the pages in the way you're 
describing.  Once you think they are ready, make them available online 
for others to review (Github or Gitlab would help doing this), and then 
submit the changes as a patch against the svn sources on the R Bugzilla 
site.

- Another way could be that you copy the help page sources to a dummy 
package, instead of checking out the whole of the R sources.  You'll 
need to be careful not to miss other changes to the originals between 
the time you make your copy and the time you submit the patches.

Don't do too many pages, because you're probably going to have to work 
out the details of the workflow as you go, and earn R Core's trust by 
submitting good changes and responding to their requests.  And maybe 
don't do any until you hear from a member of R Core that they're willing
to participate in this, because they certainly don't accept all suggestions.

Duncan Murdoch

For one point of evidence about how much people pay attention to the 
documentation about what's outdated: Brian Ripley added a comment to 
nlminb.Rd in 2013 saying that the function was "for historical 
compatibility" 
<https://github.com/wch/r-source/commit/fd50cf2047b636e496551bcefd6bfa505f93f168>
but it's still widely used in new code ...

  But I agree that adding appropriate warnings/links to the 
documentation couldn't hurt.

   cheers
    Ben

On 2023-03-26 12:41 p.m., Duncan Murdoch wrote:
> On 26/03/2023 11:54 a.m., J C Nash wrote:
>> A tangential email discussion with Simon U. has highlighted a 
>> long-standing
>> matter that some tools in the base R distribution are outdated, but
that
>> so many examples and other tools may use them that they cannot be 
>> deprecated.
>>
>> The examples that I am most familiar with concern optimization and 
>> nonlinear
>> least squares, but other workers will surely be able to suggest cases 
>> elsewhere.
>> I was the source (in Pascal) of Nelder-Mead, BFGS and CG algorithms in 
>> optim().
>> BFGS is still mostly competitive, and Nelder-Mead is useful for 
>> initial exploration
>> of an optimization problem, but CG was never very good, right from the 
>> mid-1970s
>> well before it was interfaced to R. By contrast Rcgmin works rather
well
>> considering how similar it is in nature to CG. Yet I continue to see 
>> use and
>> even recommendations of these tools in inappropriate circumstances.
>>
>> Given that it would break too many other packages and examples to drop 
>> the
>> existing tools, should we at least add short notes in the man (.Rd) 
>> pages?
>> I'm thinking of something like
>>
>> ???? optim() has methods that are dated. Users are urged to consider 
>> suggestions
>> ???? from ...
>>
>> and point to references and/or an appropriate Task View, which could, 
>> of course,
>> be in the references.
>>
>> I have no idea what steps are needed to make such edits to the man 
>> pages. Would
>> R-core need to be directly involved, or could one or two trusted R 
>> developers
>> be given privileges to seek advice on and implement such modest 
>> documentation
>> additions?? FWIW, I'm willing to participate in such an effort,
which
>> I believe
>> would help users to use appropriate and up-to-date tools.
> 
> I can answer your final paragraph:
> 
> Currently R-core would need to be directly involved, in that they are 
> the only ones with write permission on the R sources.
> 
> However, they don't need to do the work, they just need to approve of
it
> and commit it.? So I would suggest one way forward is the following:
> 
> - You fork one of the mirrors of the R sources from Github, and (perhaps 
> with help from others) edit one or two of the pages in the way you're 
> describing.? Once you think they are ready, make them available online 
> for others to review (Github or Gitlab would help doing this), and then 
> submit the changes as a patch against the svn sources on the R Bugzilla 
> site.
> 
> - Another way could be that you copy the help page sources to a dummy 
> package, instead of checking out the whole of the R sources.? You'll 
> need to be careful not to miss other changes to the originals between 
> the time you make your copy and the time you submit the patches.
> 
> Don't do too many pages, because you're probably going to have to
work
> out the details of the workflow as you go, and earn R Core's trust by 
> submitting good changes and responding to their requests.? And maybe 
> don't do any until you hear from a member of R Core that they're
willing
> to participate in this, because they certainly don't accept all 
> suggestions.
> 
> Duncan Murdoch
> 
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
-- 
Dr. Benjamin Bolker
Professor, Mathematics & Statistics and Biology, McMaster University
Director, School of Computational Science and Engineering
(Acting) Graduate chair, Mathematics & Statistics
 > E-mail is sent at my convenience; I don't expect replies outside of 
working hours.

>>>>> Duncan Murdoch 
>>>>>     on Sun, 26 Mar 2023 12:41:03 -0400 writes:
    > On 26/03/2023 11:54 a.m., J C Nash wrote:
    >> A tangential email discussion with Simon U. has
    >> highlighted a long-standing matter that some tools in the
    >> base R distribution are outdated, but that so many
    >> examples and other tools may use them that they cannot be
    >> deprecated.
    >> 
    >> The examples that I am most familiar with concern
    >> optimization and nonlinear least squares, but other
    >> workers will surely be able to suggest cases elsewhere.
    >> I was the source (in Pascal) of Nelder-Mead, BFGS and CG
    >> algorithms in optim().  BFGS is still mostly competitive,
    >> and Nelder-Mead is useful for initial exploration of an
    >> optimization problem, but CG was never very good, right
    >> from the mid-1970s well before it was interfaced to R. By
    >> contrast Rcgmin works rather well considering how similar
    >> it is in nature to CG. Yet I continue to see use and even
    >> recommendations of these tools in inappropriate
    >> circumstances.
    >> 
    >> Given that it would break too many other packages and
    >> examples to drop the existing tools, should we at least
    >> add short notes in the man (.Rd) pages?  I'm thinking of
    >> something like
    >> 
    >> optim() has methods that are dated. Users are urged to
    >> consider suggestions from ...
    >> 
    >> and point to references and/or an appropriate Task View,
    >> which could, of course, be in the references.
    >> 
    >> I have no idea what steps are needed to make such edits
    >> to the man pages. Would R-core need to be directly
    >> involved, or could one or two trusted R developers be
    >> given privileges to seek advice on and implement such
    >> modest documentation additions?  FWIW, I'm willing to
    >> participate in such an effort, which I believe would help
    >> users to use appropriate and up-to-date tools.

    > I can answer your final paragraph:

    > Currently R-core would need to be directly involved, in
    > that they are the only ones with write permission on the R
    > sources.

    > However, they don't need to do the work, they just need to
    > approve of it and commit it.  So I would suggest one way
    > forward is the following:

    > - You fork one of the mirrors of the R sources from
    > Github, and (perhaps with help from others) edit one or
    > two of the pages in the way you're describing.  Once you
    > think they are ready, make them available online for
    > others to review (Github or Gitlab would help doing this),
    > and then submit the changes as a patch against the svn
    > sources on the R Bugzilla site.

    > - Another way could be that you copy the help page sources
    > to a dummy package, instead of checking out the whole of
    > the R sources.  You'll need to be careful not to miss
    > other changes to the originals between the time you make
    > your copy and the time you submit the patches.

    > Don't do too many pages, because you're probably going to
    > have to work out the details of the workflow as you go,

(indeed!)

    > and earn R Core's trust by submitting good changes and
    > responding to their requests.  And maybe don't do any
    > until you hear from a member of R Core that they're
    > willing to participate in this, because they certainly
    > don't accept all suggestions.

    > Duncan Murdoch

Thanks a lot, Duncan, for this (as usual from you) very precise
and helpful information / explanations.

I am "happy"/willing to get involved a bit here, as I do want to
spend some time re-reading about current state of (some, notably
optim-related) optimizers.

(But I will be mostly offline for the next 60 hours or so.)


Martin

--
Martin Maechler
ETH Zurich  and  R Core team