Що означає "не працює" на довідкових сторінках R?

112

Іноді на довідковій сторінці R у коментарях з’являється фраза "не запускати". Перевірте це на сторінці довідки для "з ()":

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 ()'. Раніше це було "тестон", і ця форма все ще приймається.

— rcs
джерело

3

... як я не знав про цю функцію?

— Метт Паркер

5

Це не просто трудомісткий код, який зазвичай вводиться всередину \ dontrun {}. Код, який вимагає введення користувачем, повинен бути також усередині dontrun, інакше він не пройдеR CMD check

— Dason

2

Або: код, який залежить від пакета, який може бути встановлений на машині користувача. Є багато і багато причин використовувати \ dontrun {}

— Джейсон,

25

У посібнику "Написання розширень R" у розділі про \ приклади {...} сказано це

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

Коли ви створюєте пакет, то весь код у \ dontrun {} закритті видно у довідці як

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

редагувати: Ця відповідь була раніше.

— Марек
джерело

15

Це додає \donttest{}і береться (дослівно) від @ Хедлі R пакетів .

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

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

— Тайлер Рінкер
джерело

2

Зауважте, що зараз протестується тест

— Тайлер Рінкер

1

Чи потрібно мати для подання пакета якісь додаткові коментарі до .Rd, що виправдовує пропуск блоку коду? У мене відбулася перевірка помилок у пакеті через приклад \ donttest {}, і мені цікаво, чи це просто, як змінити його на \ dontrun {}. Функція призначена для завантаження даних з ftp, а коментар CRAN: "Це не коментується у файлах .Rd. Зауважте, що приклад () буде запускати ці розділи".

— Джефрі Еванс

Так, це повинно бути так просто.

— Тайлер Рінкер

@TylerRinker Ви маєте на увазі, що функція перевірена як робоча, або код з @donttest {} тепер керується CRAN під час перевірки?

— час

2

Так, цитата з книги Хедлі: "Для ілюстрації часто корисно включати код, що викликає помилку. \ Dontrun {} дозволяє включити код у приклад, який не запускається. (Ви раніше були вміє використовувати \ donttest {} для подібної мети, але це більше не рекомендується, оскільки він фактично тестується.) "

— Тайлер Рінкер

5

C & p з глави 5.4 (Файли документації R) ПОВИНЕНО ЧИТАТИ Створення R пакетів: Навчальний посібник Фрідріха Лейша:

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

dontrun : Все, що знаходиться всередині \ dontrun {}, не виконується тестами або прикладом (). Це корисно, наприклад, для інтерактивних функцій, функцій доступу до Інтернету тощо. Не зловживайте цим, щоб полегшити вам життя, наводячи приклади, які неможливо виконати.

— Паоло
джерело

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)

Якщо це відбудеться, це, звичайно, матиме небажані ефекти.

— Майкл Луго
джерело