Grokbase Groups R r-help March 2002
FAQ
I have a large number of troff help files which are automatically converted to .Rd files. Many of these have examples which contain the printed output of the examples. This makes example(functionname) not work. Is there a way to avoid removing all this output by delimiting it in some way such that the output will not appear in R-ex? Secondly, it would be nice if there was a place where output would be placed so that users could check results on different platforms or after upgrading a package.

Frank
--
Frank E Harrell Jr Prof. of Biostatistics & Statistics
Div. of Biostatistics & Epidem. Dept. of Health Evaluation Sciences
U. Virginia School of Medicine http://hesweb1.med.virginia.edu/biostat
-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
r-help mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html
Send "info", "help", or "[un]subscribe"
(in the "body", not the subject !) To: r-help-request at stat.math.ethz.ch
_._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._

Search Discussions

  • John Fox at Mar 29, 2002 at 3:36 am
    Dear Frank,
    At 07:14 PM 3/28/2002 -0500, Frank E Harrell Jr wrote:
    I have a large number of troff help files which are automatically
    converted to .Rd files. Many of these have examples which contain the
    printed output of the examples. This makes example(functionname) not
    work. Is there a way to avoid removing all this output by delimiting it
    in some way such that the output will not appear in R-ex? Secondly, it
    would be nice if there was a place where output would be placed so that
    users could check results on different platforms or after upgrading a package.
    I've noticed that in many cases output in help-file examples is simply
    commented out, and I've followed this practice myself; for example:

    \examples{
    data(Kmenta)
    summary(tsls(Q ~ P + D, ~ D + F + A, data=Kmenta)) # demand equation

    ## 2SLS Estimates
    ##
    ## Model Formula: Q ~ P + D
    ##
    ## Instruments: ~D + F + A
    ##
    ## Residuals:
    ## Min. 1st Qu. Median Mean 3rd Qu. Max.
    ## -3.43e+00 -1.24e+00 -1.89e-01 -2.49e-13 1.58e+00 2.49e+00
    ##
    ## Estimate Std. Error t value Pr(>|t|)
    ## (Intercept) 94.6333 7.92084 11.947 1.076e-09
    ## P -0.2436 0.09648 -2.524 2.183e-02
    ## D 0.3140 0.04694 6.689 3.811e-06
    ##
    ## Residual standard error: 1.9663 on 17 degrees of freedom

    . . .

    }

    Of course, you'll probably have to add the #'s manually. (I agree that it
    would be nice if output were handled explicitly in .Rd files.)

    I hope that this helps,
    John


    -----------------------------------------------------
    John Fox
    Department of Sociology
    McMaster University
    Hamilton, Ontario, Canada L8S 4M4
    email: jfox at mcmaster.ca
    phone: 905-525-9140x23604
    web: www.socsci.mcmaster.ca/jfox
    -----------------------------------------------------

    -.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
    r-help mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html
    Send "info", "help", or "[un]subscribe"
    (in the "body", not the subject !) To: r-help-request at stat.math.ethz.ch
    _._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._
  • Prof Brian D Ripley at Mar 29, 2002 at 7:02 am

    On Thu, 28 Mar 2002, John Fox wrote:

    Dear Frank,
    At 07:14 PM 3/28/2002 -0500, Frank E Harrell Jr wrote:
    I have a large number of troff help files which are automatically
    converted to .Rd files. Many of these have examples which contain the
    printed output of the examples. This makes example(functionname) not
    work. Is there a way to avoid removing all this output by delimiting it
    in some way such that the output will not appear in R-ex? Secondly, it
    would be nice if there was a place where output would be placed so that
    users could check results on different platforms or after upgrading a package.
    I've noticed that in many cases output in help-file examples is simply
    commented out, and I've followed this practice myself; for example:
    It is better to use \dontrun{} to do this. (That did not exist when a lot
    of the examples you are seeing were prepared.)
    \examples{
    data(Kmenta)
    summary(tsls(Q ~ P + D, ~ D + F + A, data=Kmenta)) # demand equation

    ## 2SLS Estimates
    ##
    ## Model Formula: Q ~ P + D
    ##
    ## Instruments: ~D + F + A
    ##
    ## Residuals:
    ## Min. 1st Qu. Median Mean 3rd Qu. Max.
    ## -3.43e+00 -1.24e+00 -1.89e-01 -2.49e-13 1.58e+00 2.49e+00
    ##
    ## Estimate Std. Error t value Pr(>|t|)
    ## (Intercept) 94.6333 7.92084 11.947 1.076e-09
    ## P -0.2436 0.09648 -2.524 2.183e-02
    ## D 0.3140 0.04694 6.689 3.811e-06
    ##
    ## Residual standard error: 1.9663 on 17 degrees of freedom

    . . .

    }

    Of course, you'll probably have to add the #'s manually. (I agree that it
    would be nice if output were handled explicitly in .Rd files.)
    To do that needs much more markup, including have separate \example{}
    sections inside \examples{}.

    A much better way to achieve `users could check results on different
    platforms or after upgrading' is to use a tests directory in the package,
    which R CMD check will run and compare the results to the reference output.
    See e.g. rpart and nlme for examples.

    Brian

    --
    Brian D. Ripley, ripley at stats.ox.ac.uk
    Professor of Applied Statistics, http://www.stats.ox.ac.uk/~ripley/
    University of Oxford, Tel: +44 1865 272861 (self)
    1 South Parks Road, +44 1865 272860 (secr)
    Oxford OX1 3TG, UK Fax: +44 1865 272595

    -.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
    r-help mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html
    Send "info", "help", or "[un]subscribe"
    (in the "body", not the subject !) To: r-help-request at stat.math.ethz.ch
    _._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._
  • John Fox at Mar 29, 2002 at 1:17 pm
    Dear Brian,
    At 07:02 AM 3/29/2002 +0000, Prof Brian D Ripley wrote:
    On Thu, 28 Mar 2002, John Fox wrote:
    At 07:14 PM 3/28/2002 -0500, Frank E Harrell Jr wrote:
    I have a large number of troff help files which are automatically
    converted to .Rd files. Many of these have examples which contain the
    printed output of the examples. This makes example(functionname) not
    work. Is there a way to avoid removing all this output by delimiting it
    in some way such that the output will not appear in R-ex? Secondly, it
    would be nice if there was a place where output would be placed so that
    users could check results on different platforms or after upgrading a
    package.
    I've noticed that in many cases output in help-file examples is simply
    commented out, and I've followed this practice myself; for example:
    It is better to use \dontrun{} to do this. (That did not exist when a lot
    of the examples you are seeing were prepared.)
    Unless I've missed something, the problem with using \dontrun{} for all of
    the examples (assuming that all show output) is that none of the examples
    would be run. As well, with the output not differentiated visually from the
    input, it might be hard for the reader to distinguish the two.
    Of course, you'll probably have to add the #'s manually. (I agree that it
    would be nice if output were handled explicitly in .Rd files.)
    To do that needs much more markup, including have separate \example{}
    sections inside \examples{}.
    I personally wouldn't find it onerous to put output within something like
    \example{} or \output{} -- it would be less work than adding #'s.
    A much better way to achieve `users could check results on different
    platforms or after upgrading' is to use a tests directory in the package,
    which R CMD check will run and compare the results to the reference output.
    See e.g. rpart and nlme for examples.
    I agree that this is better for checking that the package is functioning
    properly. When I read help pages, however, I find that I often copy
    examples and paste them at the command prompt to see the result. Having the
    output in the help file would make this unnecessary. Not a large point, of
    course. In general, I find the package-building tools, including for
    documentation, very well thought out.

    Thanks,
    John

    -----------------------------------------------------
    John Fox
    Department of Sociology
    McMaster University
    Hamilton, Ontario, Canada L8S 4M4
    email: jfox at mcmaster.ca
    phone: 905-525-9140x23604
    web: www.socsci.mcmaster.ca/jfox
    -----------------------------------------------------

    -.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
    r-help mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html
    Send "info", "help", or "[un]subscribe"
    (in the "body", not the subject !) To: r-help-request at stat.math.ethz.ch
    _._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._
  • Ripley at Mar 29, 2002 at 7:03 pm

    On Fri, 29 Mar 2002, John Fox wrote:

    Dear Brian,
    At 07:02 AM 3/29/2002 +0000, Prof Brian D Ripley wrote:
    On Thu, 28 Mar 2002, John Fox wrote:
    At 07:14 PM 3/28/2002 -0500, Frank E Harrell Jr wrote:
    I have a large number of troff help files which are automatically
    converted to .Rd files. Many of these have examples which contain the
    printed output of the examples. This makes example(functionname) not
    work. Is there a way to avoid removing all this output by delimiting it
    in some way such that the output will not appear in R-ex? Secondly, it
    would be nice if there was a place where output would be placed so that
    users could check results on different platforms or after upgrading a
    package.
    I've noticed that in many cases output in help-file examples is simply
    commented out, and I've followed this practice myself; for example:
    It is better to use \dontrun{} to do this. (That did not exist when a lot
    of the examples you are seeing were prepared.)
    Unless I've missed something, the problem with using \dontrun{} for all of
    the examples (assuming that all show output) is that none of the examples
    would be run. As well, with the output not differentiated visually from the
    input, it might be hard for the reader to distinguish the two.
    Just put \dontrun{} around the output. I don't find it hard to
    distinguish the commands and output, and nor would I expect this to be a
    problem once people know what R commands look like.
    Of course, you'll probably have to add the #'s manually. (I agree that it
    would be nice if output were handled explicitly in .Rd files.)
    To do that needs much more markup, including have separate \example{}
    sections inside \examples{}.
    I personally wouldn't find it onerous to put output within something like
    \example{} or \output{} -- it would be less work than adding #'s.
    or \dontrun{}!

    --
    Brian D. Ripley, ripley at stats.ox.ac.uk
    Professor of Applied Statistics, http://www.stats.ox.ac.uk/~ripley/
    University of Oxford, Tel: +44 1865 272861 (self)
    1 South Parks Road, +44 1865 272860 (secr)
    Oxford OX1 3TG, UK Fax: +44 1865 272595

    -.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
    r-help mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html
    Send "info", "help", or "[un]subscribe"
    (in the "body", not the subject !) To: r-help-request at stat.math.ethz.ch
    _._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._
  • John Fox at Mar 29, 2002 at 8:01 pm
    Dear Brian
    At 07:03 PM 3/29/2002 +0000, ripley at stats.ox.ac.uk wrote:

    Just put \dontrun{} around the output. I don't find it hard to
    distinguish the commands and output, and nor would I expect this to be a
    problem once people know what R commands look like.
    I foolishly didn't think of that. Moreover, it is to block-indent the
    output in the help file to distinguish it visually from the commands.

    Thanks for the suggestion,
    John

    -----------------------------------------------------
    John Fox
    Department of Sociology
    McMaster University
    Hamilton, Ontario, Canada L8S 4M4
    email: jfox at mcmaster.ca
    phone: 905-525-9140x23604
    web: www.socsci.mcmaster.ca/jfox
    -----------------------------------------------------

    -.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
    r-help mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html
    Send "info", "help", or "[un]subscribe"
    (in the "body", not the subject !) To: r-help-request at stat.math.ethz.ch
    _._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._
  • Warnes, Gregory R at Mar 29, 2002 at 3:47 pm
    I would also find it usefult to be able to easily include the output of
    commands in the example section by using a markup command.

    Something like:

    \examples{
    x <- rnorm(1000)
    quants <- quantcut( x )
    table(quants) y _ rnorm(100)
    \output{
    quants
    [-3.64,-0.651] (-0.651,-0.0353] (-0.0353,0.615] (0.615,2.69]
    250 250 250 250
    }
    }

    Which might be rendered something like

    y _ rnorm(100)
    x _ cut(rnorm(100, mean=y, sd=0.25),c(-4,-1.5,0,1.5,4))
    table(x)
    # Output:
    # quants
    # [-3.64,-0.651] (-0.651,-0.0353] (-0.0353,0.615]
    (0.615,2.69]
    # 250 250 250
    250
    #

    In plain text, or with suitable font/highlighting changes in HTML / LaTeX.

    -Greg
    -----Original Message-----
    From: John Fox [mailto:jfox at mcmaster.ca]
    Sent: Friday, March 29, 2002 8:18 AM
    To: Prof Brian D Ripley
    Cc: Frank E Harrell Jr; rhelp
    Subject: Re: [R] Output from examples in help files


    Dear Brian,
    At 07:02 AM 3/29/2002 +0000, Prof Brian D Ripley wrote:
    On Thu, 28 Mar 2002, John Fox wrote:
    At 07:14 PM 3/28/2002 -0500, Frank E Harrell Jr wrote:
    I have a large number of troff help files which are automatically
    converted to .Rd files. Many of these have examples
    which contain the
    printed output of the examples. This makes
    example(functionname) not
    work. Is there a way to avoid removing all this output
    by delimiting it
    in some way such that the output will not appear in
    R-ex? Secondly, it
    would be nice if there was a place where output would be
    placed so that
    users could check results on different platforms or
    after upgrading a
    package.
    I've noticed that in many cases output in help-file
    examples is simply
    commented out, and I've followed this practice myself;
    for example:
    It is better to use \dontrun{} to do this. (That did not
    exist when a lot
    of the examples you are seeing were prepared.)
    Unless I've missed something, the problem with using
    \dontrun{} for all of
    the examples (assuming that all show output) is that none of
    the examples
    would be run. As well, with the output not differentiated
    visually from the
    input, it might be hard for the reader to distinguish the two.
    Of course, you'll probably have to add the #'s manually.
    (I agree that it
    would be nice if output were handled explicitly in .Rd files.)
    To do that needs much more markup, including have separate \example{}
    sections inside \examples{}.
    I personally wouldn't find it onerous to put output within
    something like
    \example{} or \output{} -- it would be less work than adding #'s.
    A much better way to achieve `users could check results on different
    platforms or after upgrading' is to use a tests directory in
    the package,
    which R CMD check will run and compare the results to the
    reference output.
    See e.g. rpart and nlme for examples.
    I agree that this is better for checking that the package is
    functioning
    properly. When I read help pages, however, I find that I often copy
    examples and paste them at the command prompt to see the
    result. Having the
    output in the help file would make this unnecessary. Not a
    large point, of
    course. In general, I find the package-building tools, including for
    documentation, very well thought out.

    Thanks,
    John

    -----------------------------------------------------
    John Fox
    Department of Sociology
    McMaster University
    Hamilton, Ontario, Canada L8S 4M4
    email: jfox at mcmaster.ca
    phone: 905-525-9140x23604
    web: www.socsci.mcmaster.ca/jfox
    -----------------------------------------------------

    -.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.
    -.-.-.-.-.-.-.-.-
    r-help mailing list -- Read
    http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html
    Send "info", "help", or "[un]subscribe"
    (in the "body", not the subject !) To:
    r-help-request at stat.math.ethz.ch
    _._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._.
    _._._._._._._._._

    LEGAL NOTICE
    Unless expressly stated otherwise, this message is confidential and may be privileged. It is intended for the addressee(s) only. Access to this E-mail by anyone else is unauthorized. If you are not an addressee, any disclosure or copying of the contents of this E-mail or any action taken (or not taken) in reliance on it is unauthorized and may be unlawful. If you are not an addressee, please inform the sender immediately.
    -.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
    r-help mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html
    Send "info", "help", or "[un]subscribe"
    (in the "body", not the subject !) To: r-help-request at stat.math.ethz.ch
    _._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
groupr-help @
categoriesr
postedMar 29, '02 at 12:14a
activeMar 29, '02 at 8:01p
posts7
users4
websiter-project.org
irc#r

People

Translate

site design / logo © 2017 Grokbase