Cosa significa "non eseguito" nelle pagine della guida di R?

112

A volte su una pagina della guida di R la frase "non eseguito" appare nei commenti. Dai un'occhiata alla pagina della guida per "con ()":

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**)

Cosa significa "non eseguito" nel codice di esempio?

r

— Dan Goldstein
fonte

32

solo un suggerimento correlato. È possibile eseguire il codice di esempio immettendo "example (glm)".

— Eduardo Leoni

4

Questo è un buon consiglio. E scommetto che la stragrande maggioranza degli utenti R non ne è a conoscenza.

— Dan Goldstein,

1

ma nota che l'esempio (fn) non sarà ancora il codice di esempio racchiuso indontRun

— tim

tranne se imposti il run.dontrunparametro suTRUE

— Moody_Mudskipper

77

"non eseguito" racchiude codice che non dovrebbe essere eseguito nella examplefunzione (es. parti di codice che richiedono molto tempo, interazione con l'utente, ...).

vedi ad esempio ?example:

Come descritto in dettaglio nel manuale Scrittura di estensioni R , l'autore della pagina della guida può contrassegnare parti degli esempi per due regole di eccezione

"dontrun" racchiude il codice che non dovrebbe essere eseguito.
"dontshow" racchiude codice invisibile nelle pagine della guida, ma verrà eseguito sia dagli strumenti di controllo dei pacchetti, sia dalla funzione "example ()". In precedenza era "solo test" e tale forma è ancora accettata.

— rcs
fonte

3

... come non sapevo di questa funzione?

— Matt Parker,

5

Non è solo un codice dispendioso in termini di tempo che viene solitamente inserito in un \ dontrun {}. Il codice che richiede l'input dell'utente deve essere anche all'interno di dontrun, altrimenti non passeràR CMD check

— Dason

2

Oppure: codice che dipende da un pacchetto che potrebbe non essere installato sulla macchina dell'utente. Ci sono molte, molte, molte ragioni per usare \ dontrun {}

— Jason

25

Nel manuale "Writing R Extensions" , nella sezione su \ examples {...} si dice questo

Puoi usare \ dontrun {} per il testo che dovrebbe essere mostrato, ma non eseguito, e \ dontshow {} per comandi extra per il test che non dovrebbero essere mostrati agli utenti, ma saranno eseguiti da example ()

Quando si crea un pacchetto, tutto il codice nella chiusura di \ dontrun {} è visibile in help come

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

modifica: questa risposta era precedente.

— Marek
fonte

15

Questo aggiunge \donttest{}ed è preso (parola per parola) dai pacchetti R di @ hadley .

Tuttavia, a scopo illustrativo, è spesso utile includere codice che causa un errore. \dontrun{}consente di includere nell'esempio codice che non viene mai utilizzato. Ci sono altri due comandi speciali. \dontshow{}viene eseguito, ma non mostrato nella pagina di aiuto: questo può essere utile per test informali. \donttest{}viene eseguito negli esempi, ma non viene eseguito automaticamente nel controllo R CMD. Questo è utile se hai esempi che richiedono molto tempo per essere eseguiti. Le opzioni sono riassunte di seguito.

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

— Tyler Rinker
fonte

2

Nota che nontest è ora testato

— Tyler Rinker

1

Per l'invio del pacchetto, devi avere commenti aggiuntivi nel .Rd che giustifichino l'omissione del blocco di codice? Ho avuto un controllo del pacchetto non riuscito a causa di un esempio \ donttest {} e mi chiedo se sia semplice come cambiarlo in \ dontrun {}. La funzione serve per scaricare dati da un ftp e il commento di CRAN è: "Questo non è commentato nei file .Rd. Notare che example () eseguirà queste sezioni".

— Jeffrey Evans

Sì, dovrebbe essere così semplice.

— Tyler Rinker

@TylerRinker intendi che la funzione è stata verificata come funzionante, o il codice con @donttest {} è ora eseguito da CRAN durante i controlli?

— tim

2

Sì, ecco una citazione dal libro di Hadley: "A scopo illustrativo, è spesso utile includere codice che causa un errore. \ Dontrun {} ti consente di includere codice nell'esempio che non viene eseguito. (Prima in grado di utilizzare \ donttest {} per uno scopo simile, ma non è più consigliato perché in realtà è testato.) "

— Tyler Rinker

5

C & p dal Capitolo 5.4 (File di documentazione R) del DEVE LEGGERE Creazione di pacchetti R: un tutorial di Friedrich Leisch:

La sezione degli esempi dovrebbe contenere il codice R eseguibile e l'esecuzione automatica del codice fa parte del controllo di un pacchetto. Ci sono due comandi speciali di markup per gli esempi:

dontrun : Tutto all'interno di \ dontrun {} non viene eseguito dai test o da example (). Questo è utile, ad esempio, per funzioni interattive, funzioni che accedono a Internet, ecc. Non usarlo in modo improprio per semplificarti la vita fornendo esempi che non possono essere eseguiti.

— Paolo
fonte

3

L'esempio canonico qui potrebbe essere nella pagina della guida per 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)

Se funzionasse, ovviamente avrebbe effetti indesiderati.

— Michael Lugo
fonte