Local pròxima reunió
Tal i com haviem anunciat, el dijous dia 20 de Juny de 19 a 21h farem la pròxima reunió on parlaran en Miguel Alba sobre “Prediccions amb R fent servir arbres de decisió” i l’Andreu Vall del data.table. El local serà “Can Pinyons”, al carrer Joan Blanques entre el carrer Encarnació i el carrer Congost.
Us hi esperem!
Aleix, RugBcn.
Ampliar el package amb dades, NEWS i documents
Seguint la presentació de Crear packages de forma fàcil amb RStudio i Documentar el package amb Roxygen2 acabo els vídeos de crear packages de forma fàcil amb RStudio amb Ampliar el package amb dades, NEWS i documents.
En aquest vídeo tutorial explico com afegir dades al nostre package, com informar dels canvis amb NEWS i incloure qualsevol document que considerem rellevant pel package. Com a bonus i degut al retard, afegeixo com incloure una demo.
Per tenir més detalls i totes les opcions d’ampliar els vostres packages, cal anar a la documentació de referència Writing R extensions.
Espero que amb aquests 3 vídeos quedi tot clar com per crear, documentar i ampliar els vostres packages. Si teniu algun dubte envieu-me un correu o escriviu un comentari i intentaré solucionar-ho de la millor forma possible.
Tot i que amb aquest vídeo tutorial acabo la sèrie, si més endavant utilitzo opcions que considero rellevants compartir sobre la creació de packages, potser afegeixo algun altre vídeo.
Videotutorial
Proxima reunió
La proxima reunió la farem el dijous 20 de juny de 19 a 21h. Tindrem dues presentacions:
- Miguel Alba ens parlarà de “Prediccions amb R fent servir arbres de decisió”.
- Per part d’Andreu Vall tindrem “Introducció al paquet data.table”: data.table és un paquet de M Dowle, T Short, S Lianoglou, que tal i com podem llegir a la documentació és una “Extension of data.frame for fast indexing, fast ordered joins,fast assignment, fast grouping and list columns.” En aquesta xerrada coneixerem el paquet, i estic segur que no podreu deixar de fer-lo servir!
El lloc encara està per confirmar.
Sessió d’introducció a R a la UPC
Demà dimarts 21 de maig, farem una sessió d’introducció a R al màster de la Universitat Politècnica de Barcelona de Cloud Computing impartit pel Jordi Torres . Serà una sessió informativa sobre les característiques distintives d’R i les eines que aporta a l’estadística i l’anàlisi de dades. La sessió serà gratuïta, però cal fer reserva prèvia per a garantir l’espai en l’aula (envieu un correu a aleixrvr@gmail.com si hi esteu interessats). Serà al Campus Nord de la Upc de 15 a 17h.
Qualsevol que hi vulgui venir hi serà benvingut!
Aleix Ruiz de Villa, RugBcn.
Documentar packages amb Roxygen2
Seguint la presentació de Crear packeges de forma fàcil amb RStudio, considero interessant utilitzar el package Roxygen2 per generar la documentació del package. Per entendre millor el video tutorial al final de l’entrada, afegeixo les explicacions teòriques en què consisteix i com utilitzar el package Roxygen2.
Perquè és interessant roxygen2?
La documentació és un dels aspectes més importants del desenvolupament del package. Sense ella, els usuaris no saben com utilitzar-lo, i és poc probable que el facin servir. La documentació també és útil per saber què s’estava pensant quan es va programar la funció, tant per qui la va fer, com pels altres desenvolupadors del package.
La forma estàndard d’escriure la documentació de R és crear arxius .Rd al directory man/. Aquests fitxers descriuen cada objecte (funció, conjunt de dades, la classe o mètode genèric) en el seu package, documentant com funciona i donant exemples de com fer-lo servir. Els arxius .Rd són un format de fitxer especial vagament basats en làtex. Podeu llegir més sobre el format dels arxius a Writing R extensions.
En lloc d’escriure a mà els arxius .Rd, utilitzarem el package roxygen2. Amb roxygen, s’escriu la documentació en els comentaris al costat de cada funció, i després s’executa una funció del package per crear els arxius principals.
Aquest flux de treball té una sèrie d’avantatges respecte escriure la documentació dels arxius .Rd a mà:
- El codi i la documentació estan junts de manera que quan es modifica el codi, és més fàcil d’enrecordar-se d’actualitzar la documentació.
- Evita deixar tota la documentació per fer al final. Evitant així acumular molt treball de documentació de moltes funcions i data sets, resultant habitualment en una documentació deficient per anar depresa o no poder-hi dedicar tant de temps seguit.
- Roxygen2 inspecciona dinàmicament tots els objectes que es documenten, per la qual cosa permet incloure informació interrelacionada entre els diferents objectes. Funcions d’una mateixa família, objectes que enllacen altres que poden ser d’interès.
- Roxygen2 s’encarrega d’actualitzar automàticament arxius que són incòmodes de mantenir a mà, com el NAMESPACE, el camp Collate al DESCRIPTION, i l’índex de les demos.
Documentar amb Roxygen2
Els comentaris roxygen tenen un format especial. Comencen amb #' i inclouen variables de la forma @tag que trenquen la documentació en trossos. El contingut d’una etiqueta s’estén des del nom d’etiqueta fins l’etiqueta següent, i poden abastar diverses línies.
Cada bloc de documentació comença amb una descripció de text. La primera línia es converteix en el títol de la documentació. Això és el que veus quan mires a help(package = mypackage) i es mostra a la part superior de la documentació de cada package. Ha de ser concís. El segon apartat és la descripció: això és el primer que apareix en la documentació i ha de descriure breument el que fa la funció. Els paràgrafs tercer i posteriors son els detalls: es tracta d’una secció que ve després de la descripció dels paràmetres. Per anul·lar el comportament predeterminat es pot utilitzar @title, @description i @details.
Els tags més comuns que fem servir són els següents:
- @name nom de la funció
- @title títol de la funció
- @param nom i explicació de les variables
- @author autor de la funció
- @note aclariments o informació complementaria de la funció
- @export indica si una funció es visible afegint-la al NAMESPACE
- @import indica quines funcions o packages s’han d’incloure al NAMESPACE
- @examples exemples del funcionament de la funció
- @return explicació del resultat de la funció
Funcionament Roxygen2
Una cop documentats tots els objectes del package, per convertir els comentaris roxygen a arxius .Rd, es pot executar la funció roxygenize del package però nosaltres farem servir l’RStudio clickant la pestanya pertinent o definint que cada cop que fem el package ens documenti les funcions. Al videotutorial es veu com es fa.
Això genera o actualitza els arxius .Rd i els guarda al directori man/.
Documentar automàticament el NAMESPACE
Al documentar una funció, la primera decisió que s’ha de prendre és si es vol exportar o no. Les exportacions es descriuen al NAMESPACE i indica que es pot utilitzar al carregar el package. Totes les funcions que vulguem exportar han de ser documentades amb el tag @export. No cal documentar les funcions internes, però pot ser una bona pràctica si és particularment complicada.
Si el nostre package utilitza altres packages o funcions s’ha d’afegir a la documentació amb el tag @import.
Referències
La informació del package Roxygen2 està bastant dispersa però els següents enllaços poden ajudar a entendre una mica millor el seu funcionament. També afegeixo enllaços de com documentar packages.
- Web roxygen
- The New R Help System
- Writing R extensions
- Writing Package Documentation
- wiki devtools: Documenting functions
- Roxygen2
Videotutorial
Crear packages de forma fàcil amb RStudio
A la darrera reunió del Grup d’usuaris d’R de Barcelona vaig explicar com crear packages de forma fàcil amb RStudio. Com que diferents usuaris no podien venir vaig intentar gravar amb poc èxit la presentació. Finalment he decidit refer-la però la he dividit en 3 parts.
- Crear packages de forma fàcil amb RStudio.
- Documentar packages amb Roxygen2.
- Ampliant el package amb dades, NEWS i documents.
La primera ja està feta i pujada a YouTube perquè la pugueu mirar. Les següents ja les tinc mig preparades i en breu també les compartiré.
Espero que quedi prou clar com per animar-vos a fer els vostres packages. Si teniu algun dubte envieu-me un correu i intentaré aclarir-ho de la millor forma possible.
Enllaços d’interès:
Crear packages de forma fàcil amb RStudio
Aquest dijous 4 d’abril ens reunim de nou i explicaré com crear packages de forma fàcil utilitzant RStudio. Un package d’R és la unitat bàsica per compartir i re-utilitzar codi, estenent les funcionalitats base de l’R.
Per a la reunió no cal portar ordinador, però pels que vulguin crear en directe el package cal que tinguin instal·lat el següent:
- La versió 0.97 de l’Rstudio que permet generar
packagesde forma fàcil. - El
packageRoxygen2 que permet simplificar el procés de documentació de les funcions, els datasets. Tot i que no és imprescindible per crearpackagesconsidero que és molt recomanable. - En el cas d’utilitzar el sistema operatiu Windows, a més, cal Rtools que és un programa que conté les eines necessàries per crear
packagesd’R amb Windows. - Tot seguit afegeixo els scripts del
packageque crearem dijous, que consistirà d’una funció que calcula el quadrat i un dataset amb els mil primers quadrats.
Ens veiem dijous!!!
