7  AYUDAS

7.1 Ayudas sobre funciones

Para acceder a la ayuda sobre cualquier función, se escribe ?función. Así, para obtener ayuda, por ejemplo, sobre la función read.table, se escribe:

?read.table
¡El paquete tiene que estar cargado!

La función sobre la que se busque ayuda por esta vía debe formar parte de un paquete cargado (cf. sección 4.2).

Recuerde que hay 7 paquetes que se cargan automáticamente cada vez que se inicia una sesión en R: base, stats, graphics, grDevices, methods, utils y datasets.

Sería posible realizar una carga temporal (cf. tip 4.1) para pedir ayuda sobre alguna función particular:

help(car::leveneTest)

En cualquier caso, sea que se intente realizar una carga temporal o permanente del paquete, este tendrá que estar instalado (cf. sección 4.1).

Alternativamente, puede usarse help, con el nombre de la función como argumento, el cual podrá estar entrecomillado o sin comillas:

help(read.table)

O

help("read.table")

En caso, de que el paquete no estuviera cargado en memoria, se especificaría mediante el argumento package.

Así, para buscar ayuda sobre la función leveneTest, que forma parte del paquete car, se usa:

help(leveneTest, package = "car")
¡O usando la caja de búsqueda!

También puede buscarse ayuda escribiendo el nombre de la función en el botón de búsqueda de la pestaña Help, la cual se ubica por defecto en el panel inferior derecho de RStudio, y a la que puede accederse directamente pulsando .

Cuando se use la caja de búsqueda, no funciona la carga temporal (cf. tip 4.1), sino que el paquete tendrá que haber sido cargado de manera permanente en esa sesión.

Las ayudas para todas las funciones en R tienen un formato común, conformado por varias secciones, las cuales se ilustran a continuación, tomando como referencia la función binom.test.

  1. Nombre de la función y del paquete del cual forma parte. En R, todas las funciones se encuentran dentro de algún paquete. Para indicar cuál es el paquete que contiene la función, este se escribe al final, dentro de llaves.

    binom.test {stats}

  2. Nombre largo de la función. El nombre corto de la función, que es el que se usa para su invocación (v. gr., binom.test), en ocasiones no da mucha información sobre la función. El nombre largo, por su parte, sí lo hace.

    Exact Binomial Test

  3. Descripción de la tarea realizada. Se trata de un enunciado corto, mediante el que se indica la tarea ejecutada por la función.

  4. Uso. En esta parte se presenta la sintaxis de la función. Allí aparece el nombre y la posición de cada uno de sus argumentos (cf. sección 2.4). Puede verse, por ejemplo, que la función binom.test tiene cinco argumentos, el orden de los mismos y los valores por defecto o admitidos de algunos de estos.

    binom.test(x, n, p = 0.5,
           alternative = c("two.sided", "less", "greater"),
           conf.level = 0.95)

    Los argumentos que no traen ningún valor (v. gr. x y n) son obligatorios. Se requiere que el usuario suministre tales valores para que la función pueda ejecutarse. En ocasiones se muestra un listado de valores, como en el caso del argumento alternative, que indican las opciones válidas para dicho argumento. Cuando el argumento aparece con un único valor (v. gr. conf.level = 0.95), dicho valor es el que se usaría por defecto.

  5. Argumentos. En esta sección se detallan las características y funcionalidad de cada uno de los argumentos que aparecen en la sección anterior.

  6. Detalles. Cuando el autor considera necesario detallar algunas características de la función —particularmente sobre la forma en que se realizan algunos cálculos o se manejan ciertos escenarios— puede incluir esta sección.

  7. Valores. En esta parte se muestran todos los resultados generados por la función, tanto los explícitos, como algunos otros que permanecen ocultos para el usuario, pero que estarían disponibles si este los solicita.

  8. Fuente. Algunas funciones provienen de la adaptación de algoritmos escritos inicialmente en otros lenguajes. Cuando este es el caso, en esta sección se cita la fuente original.

  9. Autor. Aunque en muchas ocasiones no aparece esta sección, casi siempre es posible conocer el autor, y eventualmente contactarlo, revisando las ayudas del paquete.

  10. Referencias. Artículos o libros en los que se presenta el tema programado en la función. Usualmente se referencian los artículos clave.

  11. Funciones relacionadas (See also). Aparece el vínculo a la ayuda de otras funciones que realizan tareas similares.

  12. Ejemplos. Puede ser una de las secciones de mayor utilidad. Los ejemplos que se presentan en esta sección tienen la ventaja de que siempre ejecutan adecuadamente, sin depender de datos externos.

    Para ejecutar los ejemplos, basta con hacer clic en Run examples. No obstante, si se desea tener mayor control, ejecutando líneas específicas o realizando adaptaciones, puede copiarse el código, llevarlo al editor de scripts y explorarlo desde allí.

¡A propósito…!

Si no se recuerda el nombre exacto de una función o se desea buscar funciones con nombres similares, puede usarse la función apropos, la cual da como resultado un listado de las funciones cuyo nombre incluye la cadena de caracteres en cuestión.

Debe tenerse en cuenta, sin embargo, que la búsqueda solo se realiza dentro de los paquetes cargados en memoria (cf. sección 4.2).

apropos("read")
 [1] "read.csv"         "read.csv2"        "read.dcf"         "read.delim"      
 [5] "read.delim2"      "read.DIF"         "read.fortran"     "read.ftable"     
 [9] "read.fwf"         "read.socket"      "read.table"       "readBin"         
[13] "readChar"         "readCitationFile" "readClipboard"    "readline"        
[17] "readLines"        "readRDS"          "readRegistry"     "readRenviron"    
[21] "Sys.readlink"

7.2 Ayudas sobre paquetes

Para obtener ayudas sobre paquetes se usa ??, seguido del nombre del paquete, que puede estar entrecomillado o sin entrecomillar:

??agricolae

Equivalentemente, puede usarse el nombre del paquete entrecomillado como argumento de la función help.search:

help.search("agricolae")
¡Mejor que no sea tan sensible!

Aunque help.search puede permitir un mayor control en las búsquedas, mediante la inclusión de argumentos adicionales, exige escribir el nombre del paquete de manera exacta, diferenciando mayúsculas y minúsculas (case-sensitive).

Por su parte, ?? constituye un atajo a la invocación básica de help.search, pero no diferencia entre mayúsculas y minúsculas (case-insensitive), lo que puede resultar muy ventajoso cuando se busca ayuda sobre algún paquete cuyo nombre no se tiene muy claro.

Así, por ejemplo, la siguiente instrucción

??envstats

arroja las ayudas sobre el paquete EnvStats.

7.3 Viñetas

Algunos paquetes incluyen viñetas, es decir, documentos con explicaciones o ejemplos detallados, escritos en pdf o html.

Estos documentos van mucho más allá de la sintaxis básica de las funciones, actuando como guías o tutoriales, pudiendo incluso ser libros completos.

Tales viñetas, cuando existe, aparecen bajo el ítem Vignettes, al invocar la ayuda del paquete.

Para buscar las viñetas de un paquete, se usa la función vignette

vignette(package = "agricolae")

7.4 Otras ayudas

La función help.search también puede utilizarse para buscar información sobre algún tema específico, dentro de los paquetes instalados, sin necesidad de que los paquetes estén cargados en memoria.

Así, para buscar ayuda sobre el tema correspondence, se usa:

help.search('correspondence')

Si se busca ayuda sobre símbolos especiales, tales como los operadores, o sobre comandos reservados, estos deben escribirse entrecomillados.

?"+"

o

help("if")

7.5 Recursos

Todas las ayudas mencionadas en las secciones precedentes se obtienen directamente desde R (a través de RStudio), mediante su sistema integrado de ayuda.

Existen sin embargo, muchos otros recursos en Internet. Para acceder a los mismos, basta con realizar la correspondiente búsqueda, bien sea a través de un buscador genérico como Google o —mucho mejo— a través del buscador específico R Seek.

In english is better!

Aunque eventualmente podrían encontrarse algunas ayudas interesantes en español, la mayoría están en inglés, por lo cual se recomienda usar este idioma en todas las búsquedas.

Un sitio que merece una mención especial es Stack Overflow, el cual, tal y como reza su descripción en Wikipedia aloja preguntas y respuestas para programadores entusiastas y profesionales. Es bastante común que las consultas realizadas mediante cualquier buscador genérico conduzcan a este sitio.

A quienes migran desde SAS, SPSS y Stata, el sitio Quick-R puede facilitarles dicha transición. De igual manera, los textos de Muenchen (2009) y de Kleinman y Horton (2010) también presentan paralelos que les facilitan la migración a usuarios de otros programas.

¡Pregúntele a la IA!

No podemos cerrar este capítulo sin recomendarle la consulta a través de la inteligencia artificial de su preferencia.

Por este medio pueden realizarse consultas no solo sobre aspectos específicos de una función o paquete, sino también aspectos más generales sobre programación y uso de R.

Al momento de escribir este texto, ChatGPT y DeepSeek resultaban bastante útiles para tales efectos.

Referencias Bibliográficas

Kleinman, K, y N. J. Horton. 2010. SAS and R: Data management, statistical analysis, and graphics. Boca Raton, Fl, USA: Taylor & Francis. https://r4ds.had.co.nz/.
Muenchen, R. A. 2009. R for SAS and SPSS users. Knoxville, TN, USA: Springer. https://r4ds.had.co.nz/.