Apa artinya "tidak berjalan" di halaman bantuan R?

112

Kadang-kadang pada halaman bantuan R, frase "tidak berjalan" muncul di komentar. Lihat ini dari halaman bantuan untuk "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**)

Apa yang dimaksud dengan "tidak berjalan" dalam kode contoh?

r Dan Goldstein
sumber
32
hanya tip terkait. Anda dapat menjalankan kode contoh dengan mengeluarkan "contoh (glm)".
Eduardo Leoni
4
Itu tip yang bagus. Dan saya berani bertaruh bahwa sebagian besar pengguna R tidak menyadarinya.
Dan Goldstein
1
tapi perhatikan contoh (fn) akan tetap tidak kode contoh yang dibungkusdontRun
tim
kecuali jika Anda menyetel run.dontrunparameter keTRUE
Moody_Mudskipper

Jawaban:

77

"tidak berjalan" menyertakan kode yang tidak boleh dijalankan dalam examplefungsi (mis. bagian kode yang memakan waktu, interaksi pengguna, ...).

lihat misalnya ?example:

Seperti yang dijelaskan di manual Menulis R Ekstensi , penulis halaman bantuan dapat menandai bagian dari contoh untuk dua aturan pengecualian

  • 'dontrun' menyertakan kode yang tidak boleh dijalankan.

  • 'dontshow' menyertakan kode yang tidak terlihat di halaman bantuan, tetapi akan dijalankan baik oleh alat pemeriksa paket, dan fungsi 'example ()'. Ini sebelumnya adalah 'testonly', dan formulir itu masih diterima.

rcs
sumber
3
... bagaimana saya tidak tahu tentang fungsi ini?
Matt Parker
5
Ini bukan hanya kode yang memakan waktu yang biasanya diletakkan di dalam \ dontrun {}. Kode yang membutuhkan input pengguna harus berada di dalam jangan dijalankan juga atau tidak akan lolosR CMD check
Dason
2
Atau: kode yang bergantung pada paket yang mungkin tidak diinstal di komputer pengguna. Ada banyak sekali alasan untuk menggunakan \ dontrun {}
Jason
25

Dalam manual "Menulis R Ekstensi" , di bagian tentang \ contoh {...} dikatakan bahwa

Anda bisa menggunakan \ dontrun {} untuk teks yang seharusnya hanya ditampilkan, tetapi tidak dijalankan, dan \ dontshow {} untuk perintah tambahan untuk pengujian yang tidak boleh ditampilkan kepada pengguna, tetapi akan dijalankan oleh example ()

Ketika Anda membangun sebuah paket maka semua kode di \ dontrun {} closure terlihat di bantuan sebagai 

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

edit: Jawaban ini sebelumnya.

Marek
sumber
15

Ini menambahkan \donttest{}dan diambil (kata demi kata) dari Paket R @ hadley .

Namun untuk tujuan ilustrasi, seringkali berguna untuk memasukkan kode yang menyebabkan kesalahan. \dontrun{}memungkinkan Anda memasukkan kode dalam contoh yang tidak pernah digunakan. Ada dua perintah khusus lainnya. \dontshow{}dijalankan, tetapi tidak ditampilkan di halaman bantuan: ini dapat berguna untuk pengujian informal. \donttest{}dijalankan dalam contoh, tetapi tidak dijalankan secara otomatis dalam pemeriksaan R CMD. Ini berguna jika Anda memiliki contoh yang membutuhkan waktu lama untuk dijalankan. Opsinya diringkas di bawah ini.

Command      example    help       R CMD check
\dontrun{}                 x
\dontshow{}       x                          x
\donttest{}       x        x
Tyler Rinker
sumber
2
Perhatikan bahwa donttest sekarang diuji
Tyler Rinker
1
Untuk pengiriman paket, apakah Anda harus memiliki komentar tambahan di .Rd yang membenarkan penghilangan blok kode? Saya mengalami pemeriksaan kegagalan paket karena contoh \ donttest {} dan saya bertanya-tanya apakah itu sesederhana mengubahnya menjadi \ dontrun {}. Fungsinya untuk mendownload data dari ftp dan komentar CRAN adalah: "Itu tidak dikomentari dalam file .Rd. Perhatikan bahwa contoh () akan menjalankan bagian ini".
Jeffrey Evans
Ya harus sesederhana itu.
Tyler Rinker
@TylerRinker maksud Anda bahwa fungsi tersebut diverifikasi sebagai berfungsi, atau kode dengan @donttest {} sekarang dijalankan oleh CRAN saat melakukan pemeriksaan?
Tim
2
Ya, inilah kutipan dari buku Hadley: "Untuk tujuan ilustrasi, sering kali berguna untuk menyertakan kode yang menyebabkan kesalahan. \ Dontrun {} memungkinkan Anda untuk memasukkan kode dalam contoh yang tidak berjalan. (Dulu dapat menggunakan \ donttest {} untuk tujuan yang sama, tetapi tidak lagi disarankan karena sebenarnya telah diuji.) "
Tyler Rinker
5

C & p dari Bab 5.4 (R File Dokumentasi) dari MUST-TO-READ Membuat Paket R: Tutorial oleh Friedrich Leisch:

Bagian contoh harus berisi kode R yang dapat dieksekusi, dan menjalankan kode secara otomatis adalah bagian dari pemeriksaan paket. Ada dua perintah markup khusus untuk contohnya:

dontrun : Segala sesuatu di dalam \ dontrun {} tidak dijalankan oleh pengujian atau example (). Ini berguna, misalnya untuk fungsi interaktif, fungsi mengakses Internet dll. Jangan disalahgunakan untuk mempermudah hidup Anda dengan memberikan contoh-contoh yang tidak dapat dijalankan.

Paolo
sumber
3

Contoh kanonis di sini mungkin ada di halaman bantuan untuk 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)

Jika ini berjalan tentu saja akan memiliki efek yang tidak diinginkan.

Michael Lugo
sumber