¿Qué significa "no ejecutar" en las páginas de ayuda de R?

112

A veces, en una página de ayuda de R, aparece la frase "no ejecutar" en los comentarios. Consulte esto en la página de ayuda para "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**)

¿Qué significa "no ejecutar" en el código de ejemplo?

r

— Dan Goldstein
fuente

32

solo un consejo relacionado. Puede ejecutar el código de ejemplo emitiendo "example (glm)".

— Eduardo Leoni

4

Ese es un buen consejo. Y apuesto a que la gran mayoría de los usuarios de R no lo saben.

— Dan Goldstein

1

pero el ejemplo de nota (fn) sigue sin código de ejemplo envuelto endontRun

— tim

excepto si establece el run.dontrunparámetro enTRUE

— Moody_Mudskipper

77

"no ejecutar" incluye código que no debería ejecutarse en la examplefunción (por ejemplo, partes de código que consumen mucho tiempo, interacción del usuario, ...).

ver, por ejemplo ?example:

Como se detalla en el manual Writing R Extensions , el autor de la página de ayuda puede marcar partes de los ejemplos para dos reglas de excepción

'dontrun' incluye código que no debe ejecutarse.
'dontshow' encierra código que es invisible en las páginas de ayuda, pero que será ejecutado tanto por las herramientas de verificación de paquetes como por la función 'example ()'. Anteriormente, esto era 'testonly' y ese formulario todavía se acepta.

— rcs
fuente

3

... ¿cómo no supe de esta función?

— Matt Parker

5

No es solo un código que consume mucho tiempo lo que normalmente se coloca dentro de un \ dontrun {}. El código que requiere la entrada del usuario también debe estar dentro de dontrun o, de lo contrario, no pasaráR CMD check

— Dason

2

O: código que depende de un paquete que podría no estar instalado en la máquina del usuario. Hay muchísimas razones para usar \ dontrun {}

— Jason

25

En el manual "Escritura de extensiones R" , en la sección sobre \ ejemplos {...} se dice que

Puede usar \ dontrun {} para texto que solo debe mostrarse, pero no ejecutarse, y \ dontshow {} para comandos adicionales para pruebas que no deben mostrarse a los usuarios, pero que se ejecutarán con un ejemplo ()

Cuando construyes un paquete, todo el código en el cierre de \ dontrun {} es visible en la ayuda como

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

editar: Esta respuesta fue anterior.

— Marek
fuente

15

Esto agrega \donttest{}y está tomado (literalmente) de los paquetes R de @ hadley .

Sin embargo, con fines ilustrativos, suele ser útil incluir código que provoque un error. \dontrun{}le permite incluir código en el ejemplo que nunca se usa. Hay otros dos comandos especiales. \dontshow{}se ejecuta, pero no se muestra en la página de ayuda: esto puede ser útil para pruebas informales. \donttest{}se ejecuta en ejemplos, pero no se ejecuta automáticamente en R CMD check. Esto es útil si tiene ejemplos que tardan mucho en ejecutarse. Las opciones se resumen a continuación.

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

— Tyler Rinker
fuente

2

Tenga en cuenta que ahora se prueba donttest

— Tyler Rinker

1

Para el envío de paquetes, ¿debe tener algún comentario adicional en el .Rd que justifique la omisión del bloque de código? Tuve un paquete de verificación de fallas debido a un ejemplo de \ donttest {} y me pregunto si es tan simple como cambiarlo a \ dontrun {}. La función es para descargar datos de un ftp y el comentario CRAN es: "Eso no está comentado en los archivos .Rd. Tenga en cuenta que example () ejecutará estas secciones".

— Jeffrey Evans

Sí, debería ser así de simple.

— Tyler Rinker

@TylerRinker, ¿quiere decir que la función está verificada como funcionando, o que el código en @donttest {} ahora es ejecutado por CRAN al hacer comprobaciones?

— tim

2

Sí, aquí hay una cita del libro de Hadley: "Con el propósito de ilustrar, a menudo es útil incluir código que causa un error. \ Dontrun {} le permite incluir código en el ejemplo que no se ejecuta. (Solía ser puede usar \ donttest {} para un propósito similar, pero ya no se recomienda porque en realidad está probado.) "

— Tyler Rinker

5

C & p del Capítulo 5.4 (Archivos de documentación de R) de MUST-TO-LEAD Creación de paquetes R: Un tutorial de Friedrich Leisch:

La sección de ejemplos debe contener código R ejecutable, y la ejecución automática del código es parte de la verificación de un paquete. Hay dos comandos de marcado especiales para los ejemplos:

dontrun : Todo lo que hay dentro de \ dontrun {} no es ejecutado por las pruebas o example (). Esto es útil, por ejemplo, para funciones interactivas, funciones de acceso a Internet, etc. No lo use incorrectamente para hacerle la vida más fácil dando ejemplos que no se pueden ejecutar.

— Paolo
fuente

3

El ejemplo canónico aquí podría estar en la página de ayuda para 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)

Si esto funcionara, por supuesto, tendría efectos no deseados.

— Miguel Lugo
fuente