R 帮助页面中的“不运行”是什么意思？

What does "not run" mean in R help pages?

提问人：Dan Goldstein 提问时间：9/21/2009 更新时间：9/18/2018 访问量：24643

问：

有时，在 R 帮助页面上，注释中会出现短语“not run”。从“with（）”的帮助页面中查看以下内容：

Examples
require(stats); require(graphics)
#examples from glm:
**## Not run:** 
library(MASS)
with(anorexia, {
    anorex.1 <- glm(Postwt ~ Prewt + Treat + offset(Prewt),
                    family = gaussian)
    summary(anorex.1)
})
## End(**Not run**)

示例代码中的“不运行”是什么意思？

r

评论

38赞 Eduardo Leoni 9/22/2009
只是一个相关的提示。您可以通过发出“example（glm）”来运行示例代码。
6赞 Dan Goldstein 9/22/2009
这是一个很好的提示。我敢打赌，绝大多数 R 用户都不知道这一点。
1赞 tim 8/27/2015
但请注意 example（fn） 仍然不会包装在dontRun
1赞 moodymudskipper 6/29/2018
除非将参数设置为run.dontrunTRUE

答：

85赞 rcs 9/21/2009 #1

“不运行”包含不应在函数中执行的代码（例如，耗时的代码部分、用户交互等）。example

例如：?example

正如手册编写 R 扩展中所详述的那样，作者 帮助页面可以标记两个异常的部分示例 规则

  • “dontrun”包含不应运行的代码。

  • “dontshow”包含在帮助页面上不可见的代码，但会 由包检查工具运行，并且 'example（）' 函数。这在以前是“testonly”，并且 该表格仍被接受。

评论

5赞 Matt Parker 9/21/2009
...我怎么不知道这个功能？
6赞 Dason 10/12/2012
通常放在 \dontrun{} 中的不仅仅是耗时的代码。需要用户输入的代码也需要在 dontrun 中，否则它将无法通过R CMD check
2赞 Jason 9/12/2016
或者：依赖于可能未安装在用户计算机上的包的代码。有很多很多很多的理由来使用 \dontrun{}
0赞 mitchus 8/9/2022
@MattParker我知道，whattttt
28赞 Marek 9/21/2009 #2

在“编写 R 扩展”手册中，在关于 \examples{...} 的部分中说

您可以将 \dontrun{} 用于只应显示但不能运行的文本，并将 \dontshow{} 用于测试不应向用户显示但将由 example（） 运行的额外命令

当您构建包时，\dontrun{} 闭包中的所有代码在帮助中都可见为

## Not run:
...
## End(**Not run**)

编辑：这个答案更早。

5赞 Paolo 9/21/2009 #3

Friedrich Leisch 编写的《必读的创建 R 包：教程》第 5.4 章（R 文档文件）中的 C & p：

示例部分应包含 可执行的 R 代码，并自动 运行代码是检查的一部分 一个包。有两个特别的 示例的标记命令：

dontrun： \dontrun{} 里面的所有内容 未由测试执行，或者 例子（）。这很有用，例如，对于 交互功能、功能 访问互联网等。不要 滥用它来让你的生活更轻松 通过举例说明不可能 执行。

17赞 Tyler Rinker 8/14/2014 #4

这是从 @hadley 的 R 包中添加和获取的（逐字）。\donttest{}

但是，为了说明目的，包含导致错误的代码通常很有用。\dontrun{} 允许您在示例中包含从未使用过的代码。还有另外两个特殊命令。\dontshow{} 已运行，但未显示在帮助页面中：这对于非正式测试很有用。\donttest{} 在示例中运行，但在 R CMD 检查中不会自动运行。如果您有需要很长时间才能运行的示例，这将非常有用。这些选项总结如下。

Command      example    help       R CMD check
\dontrun{}                 x
\dontshow{}       x                          x
\donttest{}       x        x

评论

3赞 Tyler Rinker 1/28/2015
请注意，donttest 现已通过测试
1赞 Jeffrey Evans 1/30/2015
对于包提交，您是否必须在 .Rd 证明省略代码块是合理的？由于 \donttest{} 示例，我有一个包失败检查，我想知道它是否像将其更改为 \dontrun{} 一样简单。该函数用于从 ftp 下载数据，CRAN 注释为：“这未在 .Rd 文件。请注意，example（） 将运行这些部分”。
0赞 Tyler Rinker 1/30/2015
是的，它应该这么简单。
0赞 tim 8/27/2015
@TylerRinker您的意思是该函数被验证为正常工作，或者 @donttest{ } 中的代码现在由 CRAN 在进行检查时运行？
2赞 Tyler Rinker 8/27/2015
是的，这里引用了哈德利书中的一句话：“为了说明目的，包含导致错误的代码通常很有用。\dontrun{} 允许您在未运行的示例中包含代码。（您曾经可以将 \donttest{} 用于类似目的，但现在不再推荐使用它，因为它实际上已经过测试。
6赞 Michael Lugo 9/18/2018 #5

此处的规范示例可能在以下帮助页面中：rm

## Not run: 
## remove (almost) everything in the working environment.
## You will get no warning, so don't do this unless you are really sure.
rm(list = ls())

## End(Not run)

如果这样做，它当然会产生不良影响。

上一个：如何组织大型 R 程序？

下一个：如何在 ggplot2 中移动或定位图例