Что означает «не запускается» на страницах справки 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)

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

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