O que significa “não executado” nas páginas de ajuda do R?

112

Às vezes, em uma página de ajuda do R, a frase "não executado" aparece nos comentários. Verifique isso na página de ajuda de "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**)

O que significa "não executar" no código de exemplo?

r

— Dan Goldstein
fonte

32

apenas uma dica relacionada. Você pode executar o código de exemplo emitindo "example (glm)".

— Eduardo Leoni

4

Essa é uma boa dica. E aposto que a grande maioria dos usuários do R não tem conhecimento disso.

— Dan Goldstein

1

mas observe o exemplo (fn) ainda não será o código de exemplo envolvido emdontRun

— tim

exceto se você definir o run.dontrunparâmetro paraTRUE

— Moody_Mudskipper

77

"não executado" inclui o código que não deve ser executado na examplefunção (por exemplo, partes de código demoradas, interação do usuário, ...).

veja por exemplo ?example:

Conforme detalhado no manual Writing R Extensions , o autor da página de ajuda pode marcar partes dos exemplos para duas regras de exceção

'dontrun' inclui o código que não deve ser executado.
'dontshow' inclui o código que é invisível nas páginas de ajuda, mas será executado pelas ferramentas de verificação de pacote e pela função 'example ()'. Isso era anteriormente 'testonly' e esse formulário ainda é aceito.

— rcs
fonte

3

... como eu não sabia sobre esta função?

— Matt Parker

5

Não é apenas um código demorado que normalmente é colocado dentro de um \ dontrun {}. O código que requer a entrada do usuário precisa estar dentro do dontrun também, ou então não será aprovadoR CMD check

— Dason

2

Ou: código que depende de um pacote que pode não estar instalado na máquina do usuário. Existem muitos e muitos motivos para usar \ dontrun {}

— Jason

25

No manual "Writing R Extensions" , na seção sobre \ examples {...} é dito que

Você pode usar \ dontrun {} para texto que deve ser apenas mostrado, mas não executado, e \ dontshow {} para comandos extras para teste que não devem ser mostrados aos usuários, mas serão executados por exemplo ()

Quando você constrói um pacote, todo o código no fechamento \ dontrun {} fica visível na ajuda

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

editar: Esta resposta foi anterior.

— Marek
fonte

15

Isso adiciona \donttest{}e é obtido (literalmente) dos Pacotes R de @ hadley .

No entanto, para fins de ilustração, geralmente é útil incluir código que causa um erro. \dontrun{}permite incluir código no exemplo que nunca é usado. Existem dois outros comandos especiais. \dontshow{}é executado, mas não é mostrado na página de ajuda: isso pode ser útil para testes informais. \donttest{}é executado em exemplos, mas não é executado automaticamente na verificação R CMD. Isso é útil se você tiver exemplos que demoram muito para serem executados. As opções estão resumidas abaixo.

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

— Tyler Rinker
fonte

2

Observe que donttest agora foi testado

— Tyler Rinker

1

Para envio de pacote, você deve ter algum comentário adicional no .Rd justificando a omissão do bloco de código? Eu tive uma falha na verificação do pacote por causa de um exemplo de \ donttest {} e estou me perguntando se é tão simples quanto alterá-lo para \ dontrun {}. A função é para baixar dados de um ftp e o comentário CRAN é: "Isso não é comentado nos arquivos .Rd. Observe que example () executará essas seções".

— Jeffrey Evans

Sim, deve ser simples assim.

— Tyler Rinker

@TylerRinker, você quer dizer que a função foi verificada como funcionando ou o código com @donttest {} agora é executado pelo CRAN ao fazer as verificações?

— tim

2

Sim, aqui está uma citação do livro de Hadley: "Para fins de ilustração, geralmente é útil incluir um código que causa um erro. \ Dontrun {} permite que você inclua código no exemplo que não é executado. (Você costumava ser capaz de usar \ donttest {} para uma finalidade semelhante, mas não é mais recomendado porque realmente foi testado.) "

— Tyler Rinker

5

C & p do Capítulo 5.4 (Arquivos de Documentação R) do item OBRIGATÓRIO Criando Pacotes R: Um Tutorial de Friedrich Leisch:

A seção de exemplos deve conter código R executável e a execução automática do código faz parte da verificação de um pacote. Existem dois comandos de marcação especiais para os exemplos:

dontrun : Tudo dentro de \ dontrun {} não é executado pelos testes ou example (). Isso é útil, por exemplo, para funções interativas, funções de acesso à Internet, etc. Não faça mau uso para facilitar sua vida, dando exemplos que não podem ser executados.

— Paolo
fonte

3

O exemplo canônico aqui pode estar na página de ajuda 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)

Se funcionasse, teria efeitos indesejáveis.

— Michael Lugo
fonte