Что означает «не запускается» на страницах справки R?

112

Иногда на странице справки R в комментариях появляется фраза «не запускается». Посмотрите это на странице справки для "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 Дэн Гольдштейн
источник
32
просто соответствующий совет. Вы можете запустить пример кода, введя «example (glm)».
Эдуардо Леони
4
Это хороший совет. И я готов поспорить, что подавляющее большинство пользователей R об этом не знают.
Дэн Голдштейн,
1
но обратите внимание, что пример (fn) по-прежнему не будет пример кода, завернутого вdontRun
tim
кроме случаев, когда вы устанавливаете run.dontrunпараметр наTRUE
Moody_Mudskipper

Ответы:

77

«не запускать» включает в себя код, который не должен выполняться в exampleфункции (например, требующие много времени части кода, взаимодействие с пользователем, ...).

см. например ?example:

Как подробно описано в руководстве Написание расширений R , автор страницы справки может размечать части примеров для двух правил исключения.

  • 'dontrun' включает код, который не следует запускать.

  • 'dontshow' включает код, который невидим на страницах справки, но будет запускаться как инструментами проверки пакетов, так и функцией 'example ()'. Ранее это было «только тест», и эта форма все еще принимается.

система охлаждения реактора
источник
3
... как я не узнал об этой функции?
Мэтт Паркер,
5
Это не просто трудоемкий код, который обычно помещается в \ dontrun {}. Код, требующий ввода данных пользователем, также должен находиться внутри dontrun, иначе он не пройдетR CMD check
Дейсон
2
Или: код, зависящий от пакета, который может не быть установлен на машине пользователя. Есть много-много-много причин использовать \ dontrun {}
Джейсон
25

В руководстве "Написание расширений R" в разделе о \ examples {...} сказано, что

Вы можете использовать \ dontrun {} для текста, который должен только отображаться, но не запускаться, и \ dontshow {} для дополнительных команд для тестирования, которые не должны отображаться пользователям, но будут запускаться с помощью example ()

Когда вы создаете пакет, весь код в закрытии \ dontrun {} отображается в справке как 

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

изменить: этот ответ был ранее.

Марек
источник
15

Это добавлено \donttest{}и взято (дословно) из пакетов R. @ hadley .

Однако в целях иллюстрации часто бывает полезно включить код, вызывающий ошибку. \dontrun{}позволяет вам включать в пример код, который никогда не используется. Есть еще две специальные команды. \dontshow{}запускается, но не отображается на странице справки: это может быть полезно для неформальных тестов. \donttest{}выполняется в примерах, но не запускается автоматически при проверке R CMD. Это полезно, если у вас есть примеры, выполнение которых требует много времени. Возможные варианты приведены ниже.

Command      example    help       R CMD check
\dontrun{}                 x
\dontshow{}       x                          x
\donttest{}       x        x
Тайлер Ринкер
источник
2
Обратите внимание, что теперь тестируется donttest
Тайлер Ринкер
1
При отправке пакета должны ли вы иметь какие-либо дополнительные комментарии в .Rd, оправдывающие отсутствие блока кода? У меня была проверка на сбой пакета из-за примера \ donttest {}, и мне интересно, можно ли просто изменить его на \ dontrun {}. Функция предназначена для загрузки данных с ftp, а комментарий CRAN следующий: «Это не комментируется в файлах .Rd. Обратите внимание, что example () запустит эти разделы».
Джеффри Эванс,
Да, это должно быть так просто.
Тайлер Ринкер
@TylerRinker, вы имеете в виду, что функция проверена как работающая, или код в @donttest {} теперь запускается CRAN при выполнении проверок?
Tim
2
Да, это цитата из книги Хэдли: «В целях иллюстрации часто бывает полезно включить код, вызывающий ошибку. \ Dontrun {} позволяет вам включать в пример код, который не выполняется. (Раньше вы может использовать \ donttest {} для аналогичных целей, но это больше не рекомендуется, потому что это действительно проверено.) »
Тайлер Ринкер
5

C & p из главы 5.4 (Файлы документации R) документа ОБЯЗАТЕЛЬНО ПРОЧИТАЙТЕ Создание пакетов R: Учебное пособие Фридриха Лейша:

Раздел примеров должен содержать исполняемый код R, и автоматический запуск кода является частью проверки пакета. Для примеров есть две специальные команды разметки:

dontrun : Все внутри \ dontrun {} не выполняется ни тестами, ни example (). Это полезно, например, для интерактивных функций, функций доступа к Интернету и т. Д. Не используйте его неправильно, чтобы облегчить вам жизнь, приводя примеры, которые невозможно выполнить.

Паоло
источник
3

Канонический пример здесь может быть на странице справки для 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)

Если бы это произошло, это, конечно, привело бы к нежелательным последствиям.

Майкл Луго
источник