Ce înseamnă „not run” în paginile de ajutor R? (Programare, R)

Dan Goldstein a intrebat.

Uneori, pe o pagină de ajutor R apare în comentarii expresia „not run”. Priviți acest lucru din pagina de ajutor pentru „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**)

Ce înseamnă „not run” în codul de exemplu?

Comentarii

    33

  • doar un sfat înrudit. Puteți rula codul de exemplu lansând „example(glm)”. –  > Por Eduardo Leoni.
  • Acesta este un sfat bun. Și aș paria că marea majoritate a utilizatorilor R nu sunt conștienți de el. –  > Por Dan Goldstein.
  • dar rețineți că example(fn) tot nu va exemplifica codul învelit în dontRun –  > Por tim.
  • cu excepția cazului în care setați run.dontrun la TRUE –  > Por Moody_Mudskipper.
5 răspunsuri
rcs

„not run” înglobează codul care nu ar trebui să fie executat în example funcție (de exemplu, părți de cod care consumă timp, interacțiunea cu utilizatorul, …).

vezi de ex. ?example:

Așa cum este detaliat în manual Scrierea extensiilor R, , autorul paginii de ajutor poate marca părți din exemple pentru două reguli de excepție

  • ‘dontrun’ cuprinde codul care nu trebuie să fie executat.

  • „dontshow” conține cod care este invizibil pe paginile de ajutor, dar care va fi executat atât de instrumentele de verificare a pachetelor, cât și de funcția „example()”. Anterior a fost „testonly”, iar această formă este încă acceptată.

Comentarii

  • … cum de nu am știut de această funcție? –  > Por Matt Parker.
  • Nu este vorba doar de codul consumator de timp care, de obicei, este pus în interiorul unui dontrun{}. Codul care necesită introducerea datelor de către utilizator trebuie să fie și el în interiorul dontrun, altfel nu va trece R CMD check –  > Por Dason.
  • Sau: cod care depinde de un pachet care ar putea să nu fie instalat pe calculatorul utilizatorului. Există multe, multe, multe, multe motive pentru a folosi dontrun{} –  > Por Jason.
Marek

În „Scrierea extensiilor R” în secțiunea despre examples{…} se spune că

Puteți utiliza dontrun{} pentru text care trebuie doar afișat, dar nu și executat, și dontshow{} pentru comenzi suplimentare pentru testare care nu trebuie afișate utilizatorilor, dar care vor fi executate de example()

Atunci când construiți un pachet, tot codul din închiderea dontrun{} este vizibil în help ca

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

modificare: Acest răspuns a fost mai devreme.

Tyler Rinker

Acest lucru adaugă donttest{} și este preluată (textual) din răspunsul lui @hadley Pachete R.

Cu toate acestea, în scopul ilustrării, este adesea util să includem codul care provoacă o eroare. dontrun{} vă permite să includeți în exemplu cod care nu este niciodată utilizat. Există alte două comenzi speciale. dontshow{} este rulată, dar nu este afișată în pagina de ajutor: acest lucru poate fi util pentru teste informale. donttest{} se execută în exemple, dar nu se execută automat în R CMD check. Acest lucru este util dacă aveți exemple care necesită mult timp pentru a fi rulate. Opțiunile sunt rezumate mai jos.

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

Comentarii

  • Rețineți că donttest este acum testat –  > Por Tyler Rinker.
  • Pentru transmiterea pachetului, trebuie să aveți comentarii suplimentare în .Rd care să justifice omiterea blocului de cod? Am avut un pachet a cărui verificare a eșuat din cauza unui exemplu de donttest{} și mă întreb dacă este atât de simplu ca și cum l-aș schimba în dontrun{}. Funcția este pentru a descărca date de la un ftp, iar comentariul CRAN este: „Acest lucru nu este comentat în fișierele .Rd. Rețineți că example() va rula aceste secțiuni”. –  > Por Jeffrey Evans.
  • Da, ar trebui să fie atât de simplu. –  > Por Tyler Rinker.
  • @TylerRinker vrei să spui că funcția este verificată ca fiind funcțională sau codul cu în @donttest{ } este acum rulat de CRAN atunci când face verificări? –  > Por Tim.
  • Da, iată un citat din cartea lui Hadley: „În scopul ilustrării, este adesea util să includem cod care provoacă o eroare. dontrun{} vă permite să includeți în exemplu codul care nu este rulat. (Înainte puteai folosi donttest{} într-un scop similar, dar nu mai este recomandat, pentru că de fapt este testat)”. –  > Por Tyler Rinker.
Paolo

C & p din Capitolul 5.4 (Fișiere de documentație R) din MUST-TO-READ Crearea de pachete R: A Tutorial de Friedrich Leisch:

Secțiunea de exemple trebuie să conțină cod R executabil, iar rularea automată a codului face parte din verificarea unui pachet. Există două comenzi speciale de marcare pentru exemple:

dontrun: Tot ceea ce se află în interiorul dontrun{} nu este executat de teste sau de example(). Acest lucru este util, de exemplu, pentru funcțiile interactive, funcțiile care accesează internetul etc.. Nu o folosiți în mod abuziv pentru a vă face viața mai ușoară, oferind exemple care nu pot fi executate.

Michael Lugo

Exemplul canonic aici ar putea fi în pagina de ajutor pentru 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)

Dacă aceasta s-ar executa, ar avea desigur efecte nedorite.

Tags: