Que signifie «ne pas fonctionner» dans les pages d'aide R?

112

Parfois, sur une page d'aide R, la phrase «not run» apparaît dans les commentaires. Vérifiez ceci sur la page d'aide pour "avec ()":

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

Que signifie «ne pas exécuter» dans l'exemple de code?

r

— Dan Goldstein
source

32

juste une astuce connexe. Vous pouvez exécuter l'exemple de code en émettant "example (glm)".

— Eduardo Leoni le

4

C'est un bon conseil. Et je parie que la grande majorité des utilisateurs de R n'en sont pas conscients.

— Dan Goldstein

1

mais notez que l'exemple (fn) ne sera toujours pas un exemple de code encapsulé dansdontRun

— tim

sauf si vous définissez le run.dontrunparamètre surTRUE

— Moody_Mudskipper

77

"not run" renferme du code qui ne doit pas être exécuté dans la examplefonction (par exemple, des parties de code chronophages, une interaction avec l'utilisateur, ...).

voir par exemple ?example:

Comme détaillé dans le manuel Writing R Extensions , l'auteur de la page d'aide peut baliser des parties des exemples pour deux règles d'exception

'dontrun' renferme du code qui ne doit pas être exécuté.
'dontshow' renferme du code qui est invisible sur les pages d'aide, mais qui sera exécuté à la fois par les outils de vérification des packages et par la fonction 'example ()'. C'était auparavant «testonly», et ce formulaire est toujours accepté.

— rcs
source

3

... comment n'ai-je pas entendu parler de cette fonction?

— Matt Parker

5

Ce n'est pas seulement du code chronophage qui est généralement placé dans un \ dontrun {}. Le code qui nécessite une entrée de l'utilisateur doit également être à l'intérieur de dontrun, sinon il ne passera pasR CMD check

— Dason

2

Ou: code qui dépend d'un package qui peut ne pas être installé sur la machine de l'utilisateur. Il y a beaucoup de raisons d'utiliser \ dontrun {}

— Jason

25

Dans le manuel "Writing R Extensions" , dans la section about \ examples {...} il est dit que

Vous pouvez utiliser \ dontrun {} pour le texte qui ne doit être affiché, mais pas exécuté, et \ dontshow {} pour des commandes supplémentaires pour les tests qui ne doivent pas être montrées aux utilisateurs, mais qui seront exécutées par example ()

Lorsque vous créez un package, tout le code de la fermeture \ dontrun {} est visible dans l'aide comme

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

edit: Cette réponse était plus tôt.

— Marek
source

15

Ceci ajoute \donttest{}et est repris (textuellement) des packages R de @ hadley .

Cependant, à des fins d'illustration, il est souvent utile d'inclure du code qui provoque une erreur. \dontrun{}vous permet d'inclure du code dans l'exemple qui n'est jamais utilisé. Il existe deux autres commandes spéciales. \dontshow{}est exécuté, mais n'apparaît pas dans la page d'aide: cela peut être utile pour des tests informels. \donttest{}est exécuté dans les exemples, mais pas automatiquement dans le contrôle R CMD. Ceci est utile si vous avez des exemples qui prennent beaucoup de temps à s'exécuter. Les options sont résumées ci-dessous.

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

— Tyler Rinker
source

2

Notez que donttest est maintenant testé

— Tyler Rinker

1

Pour la soumission de package, devez-vous avoir des commentaires supplémentaires dans le .Rd justifiant l'omission du bloc de code? J'ai eu une vérification d'échec de paquet à cause d'un exemple de \ donttest {} et je me demande si c'est un simple comme le changer en \ dontrun {}. La fonction est de télécharger des données à partir d'un ftp et le commentaire CRAN est: "Cela n'est pas commenté dans les fichiers .Rd. Notez que example () exécutera ces sections".

— Jeffrey Evans

Oui, cela devrait être aussi simple que cela.

— Tyler Rinker

@TylerRinker vous voulez dire que la fonction est vérifiée comme fonctionnant, ou le code avec dans @donttest {} est maintenant exécuté par CRAN lors des vérifications?

— tim

2

Oui, voici une citation du livre de Hadley: "A des fins d'illustration, il est souvent utile d'inclure du code qui provoque une erreur. \ Dontrun {} vous permet d'inclure du code dans l'exemple qui n'est pas exécuté. (Vous étiez capable d'utiliser \ donttest {} dans un but similaire, mais ce n'est plus recommandé car il est en fait testé.) "

— Tyler Rinker

5

C & p du chapitre 5.4 (Fichiers de documentation R) du MUST-TO-READ Création de packages R: un tutoriel de Friedrich Leisch:

La section des exemples doit contenir du code R exécutable, et l'exécution automatique du code fait partie de la vérification d'un package. Il existe deux commandes de balisage spéciales pour les exemples:

dontrun : Tout ce qui se trouve à l'intérieur de \ dontrun {} n'est pas exécuté par les tests ou example (). Ceci est utile, par exemple, pour les fonctions interactives, les fonctions accédant à Internet, etc. Ne pas en abuser pour vous faciliter la vie en donnant des exemples qui ne peuvent pas être exécutés.

— Paolo
source

3

L'exemple canonique ici pourrait être dans la page d'aide pour 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 cela fonctionnait, cela aurait bien sûr des effets indésirables.

— Michael Lugo
source