warning() comunica situaciones inusuales que pueden ser manejadas por tu código.
warning("El número de elementos esperados es mayor a uno, se tomará el primer valor del vector")
## Warning: El número de elementos esperados es mayor a uno, se tomará el primer
-## valor del vector
+## Warning: El número de elementos esperados es mayor a uno, se tomará
+## el primer valor del vector
- stop() indica una condición errónea.
diff --git a/docs/search_index.json b/docs/search_index.json
index 4f9b0c3..9ae55ef 100644
--- a/docs/search_index.json
+++ b/docs/search_index.json
@@ -1 +1 @@
-[["index.html", "Desarrollo de paqueterías de R/Bioconductor. Bienvenida 0.1 Instructores 0.2 Ayudantes 0.3 Temario 0.4 Patrocinadores 0.5 Licencia", " Desarrollo de paqueterías de R/Bioconductor. Dra. Joselyn Cristina Chávez-Fuentes, Dra. Mirna Vázquez Rosas-Landa, M.C. Erick Cuevas-Fernández, Dra. Alejandra Medina-Rivera, Bienvenida Les damos la bienvenida al Workshop Desarrollo de paqueterías de R/Bioconductor! En este taller aprenderás cuáles son los pasos cruciales para desarrollar un paquete de R y algunas buenas prácticas para la generación de código. Con la integración de estas herramientas, tendrás la oportunidad de crear tu primer paquete y contribuir a la comunidad de desarrolladores. Adicionalmente, aprenderás a crear un sitio web para mostrar el funcionamiento de un paquete de R. 0.1 Instructores Dra. Joselyn Cristina Chávez Fuentes: Estancia Postdoctoral en Icahn School of Medicine at Mount Sinai. Dra. Alejandra Medina Rivera: Investigadora Asociada en el Laboratorio Internacional de Investigación de Medicina Genómica, UNAM. Dra. Yalbi I. Balderas-Martínez: Investigadora en el Instituto Nacional de Enfermedades Respiratorias Ismael Cosío Villegas. Dra. Mirna Vázquez Rosas Landa: Investigadora en el Instituto de Ciencias de Mar y Limnología de la UNAM. M.C. Erick Cuevas Fernández: Estudiante de Doctorado en la Universidad Nacional Autónoma de México. M.C. José Antonio Ovando Ricárdez: Estudiante de Doctorado en el Instituto Nacional de Enfermedades Respiratorias Ismael Cosío Villegas. 0.2 Ayudantes Dra. Evelia Coss: Posdoctoral en el Laboratorio Internacional de Investigación de Medicina Genómica, UNAM. M.C. José Antonio Ovando Ricárdez: Estudiante de Doctorado en el Instituto Nacional de Enfermedades Respiratorias Ismael Cosío Villegas. 0.3 Temario Consulta el calendario de este curso en: https://bit.ly/calendarcdsb2024 Día 1: Flujo de trabajo orientado a proyectos: Introducción al trabajo con proyectos de RStudio. Paths seguros. Control de versiones con GitHub y RStudio. Solución de problemas con las versiones de paquetes de Rstudio. Día 2: Creación de paquetes de R/Bioconductor Parte I Infraestructura de un paquete de R/Bioconductor. Documentación de funciones. Sesión social: Conociendo a la comunidad. Proyectos colaborativos Parte I. Día 3: Creación de paquetes de R/Bioconductor Parte II Diseño de pruebas. Creación de viñetas. Compilación e instalación de paquetes. Proyectos colaborativos Parte II. Día 4: Creación de sitios web para la documentación de paquetes de R Creación de sitios web con pkgdown Proyectos colaborativos Parte III. Presentación de proyectos. Clausura. 0.4 Patrocinadores Agradecemos a nuestros patrocinadores: 0.5 Licencia Este material posee una licencia tipo Creative Commons Attribution-ShareAlike 4.0 International License. Para conocer más sobre esta licencia, visite http://creativecommons.org/licenses/by-sa/4.0/ "],["trabajando-con-proyectos-de-rstudio.html", "1 Trabajando con proyectos de RStudio 1.1 Diapositivas 1.2 ¿Qué es un proyecto de RStudio? 1.3 ¿Cómo generamos un proyecto de RStudio? 1.4 ¿Por qué usar proyectos de RStudio? 1.5 Algunos hacks! 1.6 Generando rutas seguras", " 1 Trabajando con proyectos de RStudio Joselyn Cristina Chávez Fuentes 28 de octubre de 2024 1.1 Diapositivas div.grey { background-color: #bfbfbf; } div.center { text-align:center; } 1.2 ¿Qué es un proyecto de RStudio? Es un archivo especial de R, compatible con RStudio, que al ejecutarlo hará 3 cosas: Abrirá una nueva sesión de RStudio. Establecerá la ubicación del proyecto como tu directorio de trabajo. Establecerá la ubicación del proyecto como la raíz de los archivos. 1.3 ¿Cómo generamos un proyecto de RStudio? 1.3.1 Opción 1: Creando un proyecto en un directorio nuevo. En las opciones de RStudio Ve a File > New project > New Directory > New Project. Asigna un nombre a tu proyecto, sin espacios y sin caracteres especiales. Selecciona la ubicación donde crearás el nuevo directorio. Selecciona la opción Open in New Session. Oprime Create Project. 1.3.2 Opción 2: Creando un proyecto en un directorio existente. Crea un directorio en alguna ubicación conocida de tu computadora. Asigna un nombre a tu directorio, sin espacios y sin caracteres especiales (Este será el nombre de tu proyecto). En las opciones de RStudio ve a File > New project > Existing Directory. Selecciona la ubicación donde previamente creaste el directorio. Selecciona la opción Open in New Session. Oprime Create Project. 1.4 ¿Por qué usar proyectos de RStudio? Te permiten ser más organizado y pasar de tener una ensalada de archivos a tener carpetas para cada sección del análisis. Compartamentalizas tu trabajo al generar un proyecto específico para cada análisis. Te permiten trabajar con varios proyectos a la vez en sesiones independientes de RStudio, cada uno con sus propias variables, directorio de trabajo y archivos. Establece automáticamente tu directorio de trabajo. En lugar de usar setwd() solamente requieres ejecutar el archivo .Rproj para abrir la sesión y trabajar en la ubicación del proyecto. Puedes usar rutas relativas (y estables) a tus archivos, que seguirán funcionando sin importar en dónde se ubique tu proyecto. Facilita el compartir y reproducir tu trabajo. No más rutas al estilo ~/MiComputadora/MiFolder/MiArchivo. Comparte la carpeta completa de tu proyecto con todos los archivos necesarios y usa rutas relativas dentro del Rscript, por ejemplo ./datos. Nos ayuda a establecer colaboraciones y trabajar con plataformas de control de versiones. Actividad Comprueba algunas ventajas de usar proyectos de RStudio. Genera un nuevo proyecto de RStudio llamado ‘miproyecto’, recuerda que existen varias formas para hacerlo. Cierra la sesión y vuelve a abrirla ejecutando desde la terminal open miproyecto.Rproj o dando doble click sobre el archivo miproyecto.Rproj. Evalúa tu directorio de trabajo ejecutando en la consola de RStudio el comando getwd(). Cierra la sesión y mueve toda la carpeta de tu proyecto a otra ubicación. Si lo creaste en Documentos mueve la carpeta al Escritorio o viceversa. Abre nuevamente el proyecto y verifica el directorio de trabajo, ¿Cambió el directorio de trabajo? Sin cerrar este proyecto, abre alguno de los proyectos que generaste previamente (por ejemplo directorioprevio.Rproj), recuerda que puedes seleccionar Open Project in New session 1.5 Algunos hacks! RStudio recuerda los proyectos con los que has trabajado recientemente. Ve a la esquina superior derecha y da click en la flecha junto al nombre de tu proyecto actual. Verás todos los proyectos recientes. Si das click en el nombre de alguno de ellos te abrirá el proyecto en la misma sesión, si das click en el recuadro con flecha blanca te abrirá una nueva sesión con tu proyecto. Crea todos tus proyectos dentro de una carpeta principal y usa el buscador de archivos para acceder a ellos rápidamente. 1.6 Generando rutas seguras Se construyen a partir de una base estable El directorio de trabajo cambia de usuario a usuario y dependiendo de la ubicación de los archivos. getwd() Deben funcionar en cualquier sistema operativo Una ruta en sistemas Linux se ve así: "/Users/joselynchavez/Documents/materiales_cdsb2024" Mientras que una ruta en Windows se ve así: "C:\\Documents/materiales_cdsb2024" 1.6.1 El paquete here Usemos el paquete here para detectar la ubicación del proyecto: here::here() Ahora generemos una ruta segura a partir de la raíz del proyecto here::here("mi_tabla.csv") here::here("subfolder", "mi_tabla.csv") 1.6.2 Usando el paquete fs Por defecto, usa el directorio de trabajo actual como base y detecta el sistema operativo automáticamente. fs::path("mi_tabla.csv") fs::path("subfolder", "mi_tabla.csv") Tiene como ventaja que puede construir las rutas a partir del home del usuario. fs::path_home() fs::path_home("mi_tabla.csv") 1.6.3 Usando funciones base Si no deseas incluir el paquete ‘here’ en las dependencias de tu paquete, puedes usar la función file.path Esta función usa como base el directorio de trabajo actual y detecta el sistema operativo para construir la ruta. file.path("mi_tabla.csv") file.path("subfolder", "mi_tabla.csv") "],["control-de-versiones-con-github-y-rstudio.html", "2 Control de versiones con GitHub y RStudio 2.1 Diapositivas 2.2 ¿Por qué hacer control de versiones de nuestros proyectos? 2.3 Git 2.4 Recomendaciones para sus proyectos 2.5 Proyectos colaborativos 2.6 GitHub 2.7 Manual de sobreviviencia con Git Y GitHub en RStudio (en caso de ser necesario) 2.8 Cómo clonar un repositorio y tener conección/permisos para modificarlo? 2.9 Credenciales HTTPS en Cache 2.10 Conectando RStudio con Git y Github. 2.11 GitHub primero, RStudio después… 2.12 Rmarkdown en GitHub 2.13 RStudio primero y GitHub también 2.14 Proyecto existente, GitHub al final 2.15 Git basics: commands 2.16 Merge conflics 2.17 Merge conflics 2.18 En resumen", " 2 Control de versiones con GitHub y RStudio Dra. Alejandra Medina Rivera 28 de octubre de 2024 div.color { border-radius: 5px; padding: 20px; margin: 30px 0px 30px;} div.red { background-color:#f67155; } div.orange{ background-color:#f0BB51;} div.pair { display: flex; flex-direction: row; justify-content: center; text-align:center; padding:0px} div.inside { width: 49%; padding: 0px} div.scroll { max-height: 400px; overflow-y: auto; background: #111111; border-radius:5px; padding: 10px; margin: 30px 0px 30px; color: #999999;} div.alert{color:#bd475d; background-color:transparent} Este documento se basa en “Happy Git with R” de Jenny Bryan, los STAT 545 TAs, Jim Hester https://happygitwithr.com 2.1 Diapositivas 2.2 ¿Por qué hacer control de versiones de nuestros proyectos? ✅ Los proyectos suelen cambiar y crecer. 💾 Es díficil saber cuáles fueron todos los cambios a lo largo del tiempo (en especial tiempos largos, hazlo por tu yo del futuro!). 🤔 Las colaboraciones se pueden complicar sin un buen control de versiones. 🔐 Seguridad. 2.3 Git Git es un sistema de control de versiones Git funciona con GitHub, Bitbucket o GitLab ¿Por qué usar Git en vez de solo renombrar los archivos? ✅✅Por qué es mejor tener una filogenia del archivo. Git es un sistema de control de versiones distribuido, gratuito y de código abierto, diseñado para manejar todo tipo de proyectos, desde los más pequeños hasta los más grandes, con rapidez y eficiencia. Git es fácil de aprender y ocupa poco espacio con un rendimiento rapidísimo. Supera a las herramientas SCM como Subversion, CVS, Perforce y ClearCase con características como la ramificación local barata, las cómodas áreas de preparación y los múltiples flujos de trabajo. 2.3.1 Git vs controles de versión a mano Con Git cada contribuidor tiene una copia del repositorio central, con todos los archivos y la historia de los cambios por los que han pasado. Excuse me, do you have a moment to talk about version control?, Jennifer Bryan, 2017 ⚠️ NO OLVIDES TENER INSTALADO Git, en caso de que aún no lo hayas instalado, lo puedes descargar en el siguiente enlace https://git-scm.com/downloads. Para conocer la localización y la versión de Git que tienes en tu computadora, corre el siguiente comando en la terminal: which git y git --version 2.4 Recomendaciones para sus proyectos Dedicar un directorio Es mejor organizarlo en un RStudio Project Hacer un repositorio de Git Trabajen como siempre, solo además de guardar, recuerden hacer commit De vez en vez hagan push de sus cambios cuando los hayan verificado. 2.5 Proyectos colaborativos GitHub se parece más a un GoogleDoc que a un Word Document. Es fácil que los colaboradores hagan cambios y también es fácil saber quién hizo que. El owner del proyecto puede dar permisos a los diferentes colaboradores. También existen organizaciones, esto puede ser útil para manejar los permisos de grupos grandes de colaboración. 2.6 GitHub GitHub es una plataforma para guardar proyectos, hace uso de Git. Su principal utilidad es para generar código fuente de programas. ⚠️ NO OLVIDES TENER UNA CUENTA EN GITHUB, en caso de que aún no lo hayas hecho, puedes ir la página de GitHub y seleccionar join. Es indispensable tu usuario para los ejercicios que siguen. También existen otras plataformas como Bitbucked y GitLab, las cuales funcionan de manera similar a GitHub. 2.7 Manual de sobreviviencia con Git Y GitHub en RStudio (en caso de ser necesario) Por cualquier problema con la conexión entre RStudio y Git, siempre ten en cuenta la ubicación de dónde se instaló Git. Puedes usar en la terminal which git (Mac y Linux) O bien usar en la terminal where git (Windows) Recuerda que la terminal (o línea de comandos ó consola ó shell ó bash) es un programa en tu computadora que funciona para correr otros programas. Desde RStudio puedes abrir la terminal, lo cual es muy conveniente si estás trabajando en un proyecto. Puedes abrir una terminal con: Tools > Terminal (abre la terminal dentro del IDE de RStudio) Tools > Shell (abre una terminal externa a RStudio) 2.8 Cómo clonar un repositorio y tener conección/permisos para modificarlo? Git puede comunicarse con un servidor remoto usando uno de dos protocolos, HTTPS o SSH, y cada protocolo usa credenciales diferentes. La recomendación actual de GitHub es usar HTTPS porque es la manera más fácil de configurar y tiene operabilidad en multiples redes y plataformas. Es menos probable que HTTPS sea bloqueado por un firewall. Una conexión HTTPS permite que credential.helper almacene en caché su contraseña. (por tanto puedes configurar tu usuario y contraseña en tu equipo de uso) Es más sencillo acceder a un repositorio desde cualquier lugar, ya que solo necesitas los detalles de tu cuenta (no se requieren claves SSH) para escribir en el repositorio. Usualmente cuando inicies un proyecto colaborativo con GitHub inicializa el ropositorio con un README. Copia el HTTPS URL para clonar el repositorio en la terminal git clone https://github.com/TU-USUARIO/TU-REPOSITORIO.git. 2.9 Credenciales HTTPS en Cache Para usar HTTPS debes crear un token de acceso personal, PAT (PERSONAL ACCESS TOKEN), esa será tu credencial para HTTPS. Es una alternativa al uso de contraseñas para la autenticación en GitHub. Como precaución de seguridad, GitHub elimina automáticamente los tokens de acceso personales que no se han usado durante un año. ¿Cómo crear un token? Ve a tu perfil de GitHub, dale click a la imagen de perfil (usualmente en la esquina superior derecha), y busca la opción de settings ó configuración según sea la configuración de idioma que tengas. Da click a continuación en Developer settings ó Parámetros del desarrollador. En la barra lateral izquierda da click en Tokens de acceso personal. Haz click en Generar un nuevo token. Asígna un nombre descriptivo a tu token. Selecciona los alcances o permisos que deseas otorgarle a este token. Para usar tu token para acceder a repositorios desde la línea de comando, selecciona repo. (Recomendados: repo, user, workflow ) Finalmente haz click en generar token. Listo, copia y pega tu token en el lugar dónde siempre lo puedas volver a copiar, ya que por razones de seguridad, una vez salgas de la página no podrás volver a ver el token. Nota: Preserva tus tokens de la misma manera que tus contraseñas y no se las reveles a nadie. Una vez que tengas un token, puedes ingresarlo en lugar de tu contraseña cuando realices operaciones de Git a través de HTTPS. El punto final es que una vez configurada una PAT, varios paquetes de R, incluidos usethis y gh, podrán trabajar con la API de GitHub en su nombre, de forma automática. Por lo tanto, una PAT configurada correctamente significa que todo esto funcionará a la perfección: - Operaciones HTTPS remotas a través de la línea de comando Git y, por lo tanto, a través de RStudio - Operaciones HTTPS remotas a través del paquete gert R y, por lo tanto, usethis - Operaciones de la API de GitHub a través del paquete gh R y, por lo tanto, usethis Probar el repositorio Clonado Después de hacer clone Usa estos comandos para verificar tu repositorio y revisar desde dónde se está sincorinzando. cd myrepo ls -la head README.md git remote show origin Probemos haciendo un cambio en el README echo "Something I want to add to the README in my local computer" >> README.md git status Qué pasó? Ahora tenemos que decirle a git que queremos seguir los cambios de ese archivo Vamos a commit los cambios y luego a subir (push) los mismos a GitHub git add README.md git commit -m "A commit from my local computer" git push Recuerda tu TOKEN!! ¿Cómo crear un token desde R? Puedes ir directamente a la página de GitHub a la parte para generar tu token de acceso personal mediante la siguiente función: usethis::create_github_token() Y con las opciones que se mencionaban anteriormente puedes configurar y crear tu PAT. Si lo que quieres es especificar tu PAT en RStudio, las siguientes funciones te serán útiles: library(gitcreds) gitcreds_set() library(credentials) set_github_pat() Para eliminar credenciales utiliza la función credentials::git_credential_forget() 2.9.1 Actividad Ejecuta los códigos y genera tu PAT, recuerda no perderlo! 2.10 Conectando RStudio con Git y Github. Para lo que sigue a continuación, deberías tener esto: Tener una cuenta en GitHub R y RStudio actualizados Git instalado Saber que desde la terminal puedes hacer push y pull 2.11 GitHub primero, RStudio después… Crea un repositorio en GitHub: mi_repositorio > Public > YES initialize this repository with a README > clicken el gran botón verde “Create repository” En RStudio crea un nuevo proyecto: File > New Project > Version Control > Git. Ahi pega el URL del repositorio https://github.com/mi_usuario/mi_repositorio.git. Da click en Create Project. Esto nos generará los siguientes elementos: Un directorio nuevo Un repositorio Git enlazado a al repositorio de GitHub Un proyecto en RStudio Con este procedimiento ya no es necesario preocuparse por configurar controles remotos Git y rastrear ramas en la línea de comandos. 2.11.1 Actividad Genera un repositorio con el nombre que desees. Y conéctalo a RStudio. Cerciorate de que el archivo README se encuentre en tu nueva carpeta. Usa la función usethis::use_r(\"titulo_de_un_script\") y observa lo que sucede. PAUSA ¿Cómo comento y doy push/pull desde RStudio? 2.11.2 Comentar, pull y push Con la flecha azul podemos hacer pull (RECUERDA HACERLO ANTES DE HACER UN PUSH), y con la flecha verde un push. Para poder comentar y hacer push debemos marcar con una flechita mediante un click en las pequeñas cajas blancas de la columna Staged, damoc click en commit lo cual no abre la siguiente ventana. Volvemos a dar click en commit, y finalizamos con push (flecha verde). 2.12 Rmarkdown en GitHub Creemos un Rmakrdown y subámoslo a GitHub Ahora hay que agregarlo al repositorio (add), stage and commit. Subieron el hmlt? Qué tal se ve? No se ve como queremos, verdad? Para eso necesitamos recuperar el .md. El .md es un resultado intermedio de crear el html desde Rmd. Tenemos que cambiar el header para esto --- title: "RmarkwondTest" output: html_document: keep_md: true --- 2.12.1 Actividad Usa el código dir.create(\"mis_imagenes\") en la consola de tu sesión de RStudio (la que está vinculada a tu repositorio). Ejecuta el siguiente código quitando los #: install.packages("MASS") library (MASS) data(MASS::cats) # pdf("mis_imagenes/cats_plot.pdf") ggplot(cats, aes(x = Sex)) + geom_bar(fill = "orange", color = "black") + theme_classic() + xlab("Sexo") + ylab("Número de Gatos") + ggtitle("Gatos") # dev.off() Comenta y da push a los cambios que realizaste en el repositorio. 2.13 RStudio primero y GitHub también Usa uno de los proyectos que hayas generado en las sesiones anteriores, PERO, que no esté enlazado a GitHub. Ahora veremos como conectar un proyecto de R existente con GitHub. Realiza los pasos que hicimos en GitHub primero, RStudio después pero asegurate de crear un repositorio con un nuevo nombre. Y LISTO!! usa un simple ctrl + c, ó mv ó click derecho + copiar ó el método que prefieras para mover o copiar archivos. Copia los archivos de tu antigüo proyecto al proyecto nuevo. Solo haz commit y push y listo, lo que tenía en tu antigüo proyecto ya está enlazado a GitHub. 2.14 Proyecto existente, GitHub al final Supongamos que tenemos un proyecto de R existente en algún lugar de nuestra computadora. NOTA: Para generar proyecto de RStudio desde la consola puedes utilizar el siguiente código: usethis::create_project() O en RStudio con File > New Project > Existing Directory Si su proyecto ya es un proyecto de RStudio, ejecútelo. ¿Ya es un repositorio de Git? La presencia del panel de Git debería alertarlo. Si es así, ha terminado. Sino este es el primer camino a seguir: Con el páquete usethis usa la función usethis::use_git En RStudio ve a Tools > Project Options > Git/SVN. Dentro de Version control system, selecciona Git. Y da click a “Yes” cuando aparezca “Confirm New Git Repository?”. Si usaste RStudio o usethis, el proyecto debería reiniciarse en RStudio. Hazlo tu mismo si hizo git init. RStudio ahora debería tener un panel Git. 2.14.1 Breviario cultural con los PATs Si usas el paquete usethis Y has configurado un token de acceso personal (PAT) de GitHub has esto en R: usethis::use_github() Esto creará un nuevo repositorio en GitHub, lo agregará como un control remoto, configurará una rama de seguimiento y lo abrirá en su navegador. Lea la ayuda de use_github() para conocer sus argumentos y consejos sobre cómo configurar una PAT. Esto es extremadamente útil para una variedad de flujos de trabajo que llaman a la API de GitHub. Considere configurar esto si usa usethis, devtools o gh con regularidad. Volviendo al tema de Proyecto existente, GitHub al final. Otra opción que se puede hacer para conectar un proyecto existen a GitHub es ir a hacer un repositorio a GitHub PERO ten en cuenta los siguientes cambios: Elije un nombre de repositorio; probablemente debería coincidir con el nombre de su proyecto y directorio local. NO inicialice este repositorio con un archivo README. Todo lo demás es igual a los pasos que hacíamos en GitHub primero, RStudio después… Ahora ve a tu proyecto de RStudio, has clic en los “dos cuadros de color púrpura y un cuadrado blanco” en el panel de Git. Has clic en “Agregar control remoto”. Pegue la URL aquí y elija un nombre remoto, casi con certeza el origin. Ahora “ADD”. Pasado esto deberiamos volver en el cuadro de diálogo “New Branch”. Ingresa “master” como el nombre de la rama y asegúrate de que la opción “Sync branch with remote” esté marcada. Haz clic en “Create”. En el siguiente cuadro de diálogo elije “overwrite”. Ahora solo haz commit/pull/push y cérciorate que FUNCIONE!! 2.15 Git basics: commands Fetch Commits git fetch Create and Switch to a branch git branch [branch-name] git checkout [branch-name] 2.16 Merge conflics A veces, no tan a veces también, las cosas no salen bien a la primera Merging (Fusionar) es una de esas cosas Cuando bajamos un cambio o fusionamos branches esto puede pasar. Primera regla: NO ENTRAR EN PANICO!!! Revisen el status del repositorio. Qué archivo tiene conflicto? 2.17 Merge conflics Abran ese archivo y busquen los problemas de merge. Es fácil, se ven así: <<<<<<< HEAD:index.html <div id="footer">contact : email.support@github.com</div> ======= <div id="footer"> please contact us at support@github.com </div> >>>>>>> issue-5:index.html Editen esa sección, dejen una versión final. Hagan commit y push Si entran en pánico? Aborten la misión! git merge --abort t 2.18 En resumen ¡QUE LA FUERZA TE ACOMPAÑE! "],["solución-de-problemas-con-las-versiones-de-paquetes-de-rstudio.html", "3 Solución de problemas con las versiones de paquetes de Rstudio 3.1 Diapositivas", " 3 Solución de problemas con las versiones de paquetes de Rstudio Yalbi Balderas 28 de octubre de 2024 3.1 Diapositivas "],["creando-la-infraestructura-de-un-paquete.html", "4 Creando la infraestructura de un paquete 4.1 Diapositivas 4.2 Los primeros pasos 4.3 Checks 4.4 Modificando el archivo DESCRIPTION 4.5 Modificando el archivo NEWS", " 4 Creando la infraestructura de un paquete Joselyn Cristina Chávez Fuentes 29 de octubre de 2024 4.1 Diapositivas 4.2 Los primeros pasos Revisar si podemos usar el nombre del paquete available::available("mipaquete") Crear la estructura inicial del paquete usethis::create_package("mipaquete") Podemos agregar la estructura de biocthis biocthis::use_bioc_pkg_templates() Pedir que Git ignore el archivo .Rproj usethis::use_git_ignore("*.Rproj") Crear el respositorio de GitHub usethis::use_github() Crear el archivo Description estilo Bioconductor biocthis::use_bioc_description() Crear el archivo README estilo Bioconductor biocthis::use_bioc_readme_rmd() devtools::build_readme() Recuerda guardar los cambios, hacer commit y push. Crear el archivo NEWS estilo Bioconductor biocthis::use_bioc_news_md() Crear los archivos de ayuda para usuarios y contribuidores biocthis::use_bioc_coc() usethis::use_tidy_contributing() biocthis::use_bioc_support() biocthis::use_bioc_issue_template() biocthis::use_bioc_citation() 4.3 Checks 4.3.1 BiocCheck BiocManager::install("BiocCheck") BiocCheck::BiocCheck() Algunas reglas de BiocCheck: Utilizar el símbolo <- en lugar de = para definir funciones y variables. Utilizar TRUE y FALSE en lugar de T y F. Indentar el código usando 4 espacios. Las líneas de código y documentación no deben ser mayores a 80 caracteres. Las funciones deben tener 50 líneas de código o menos. El paquete debe contener al menos una viñeta. Al menos 80% de las funciones deben tener ejemplos reproducibles. Las dependencias deben ser declaradas en el archivo DESCRIPTION. El paquete debe tener al menos un biocView. El tamaño del paquete no debe ser mayor 5Mb. El maintainer debe estar suscrito a la lista de correo de Bioconductor. El maintainer debe agregar su paquete en los tags de Bioconductor. 4.3.2 rcmdcheck install.packages("rcmdcheck") rcmdcheck::rcmdcheck() Algunas reglas de rcmdcheck: El paquete debe ser instalable. Los ejemplos de las funciones deben ser reproducibles. Las viñetas deben ser reproducibles. Todas las unidades de prueba deben pasar sin errores. El archivo DESCRIPTON debe tener el formato adecuado. 4.4 Modificando el archivo DESCRIPTION Paquete Este es el nombre del paquete. El nombre del repositorio y el nombre del paquete en la descripción deben coincidir (incluyendo mayúsculas y minúsculas). Título Este es un título breve pero descriptivo para el paquete. Versión Todos los paquetes de Bioconductor utilizan un esquema de versión x.y.z. Cuando se envía por primera vez a Bioconductor, un paquete debe tener la versión 0.99.0. Se aplican las siguientes reglas: x es normalmente 0 para paquetes que aún no han sido liberados. y es par para paquetes liberados, e impar para paquetes en desarrollo. Generalmente, no se debe aumentar este número en el pre-release. z se incrementa siempre que se realizan cambios en el paquete. Descripción La descripción debe ser una visión general relativamente breve pero detallada de lo que implica la funcionalidad del paquete. Debe ser de al menos tres oraciones completas. Autores Se requiere una designación de maintainer (cre) con una dirección de correo electrónico que se mantenga activamente. Esta dirección de correo se utilizará para el contacto con respecto a cualquier problema que surja con el paquete en el futuro. Idealmente, se debe incluir el ORCiD por lo menos del maintainer. person("Lori", "Shepherd", email = Lori.Shepherd@roswellpark.org, role = c("cre", "aut"), comment = c(ORCID = "0000-0002-5910-4010")) Sólo debe figurar una persona como responsable para garantizar un único punto de contacto. Esta persona tendrá acceso al repositorio git en git.bioconductor.org. El acceso a Commit puede ser dado a otros desarrolladores por solicitud en la lista de correo bioc-devel. Otra opción es añadir colaboradores al repositorio de GitHub. Este enfoque permite el desarrollo por muchos pero restringe el acceso a git.bioconductor.org. Licencia El campo de licencia debe referirse preferentemente a una licencia estándar no restrictiva. Las licencias que restringen el uso, por ejemplo, a investigadores académicos o sin fines de lucro, no son adecuadas para Bioconductor. Los paquetes de bioconductor básico suelen estar licenciados bajo Artistic-2.0. El paquete debe contener sólo código que pueda ser redistribuido de acuerdo con la licencia del paquete. LazyData Para paquetes que incluyen datos, se recomienda NO incluir LazyData: TRUE. Incluirlo en ese caso, ralentiza la carga de paquetes con datos grandes. Dependencias Todos los paquetes deben estar disponibles a través de biocViews o CRAN de Bioconductor; el uso del campo Remotes: no es soportado, por lo tanto las dependencias sólo disponibles en otros repositorios (e.g. GitHub) no están permitidas. Un paquete puede ser listado sólo una vez entre Depends, Imports, Suggests, o Enhances: Imports: es para paquetes que proporcionan funciones, métodos o clases que se usan dentro del código del paquete. La mayoría de los paquetes están listados aquí. Depends: es para paquetes que proporcionan funcionalidad esencial para los usuarios del paquete, por ejemplo, el paquete GenomicRanges se enumera en el campo Depends: de GenomicAlignments. Es poco común que más de tres paquetes aparezcan como Depends:. Suggests: es para paquetes usados en viñetas, ejemplos y código condicional. Comúnmente, los paquetes de anotaciones y experimentos (por ejemplo, TxDb*) usados en viñetas y código de ejemplo se incluyen en este campo, evitando así una descarga costosa. Enhances: es para paquetes como parallel que mejoran el rendimiento del paquete, pero no son estrictamente necesarios para su funcionalidad. En el caso de que se requiera una función única externa para el código del paquete, la disponibilidad y el uso del paquete pueden hacerse a través de: if (!requireNamespace('suggPKG', quietly = TRUE)) stop("Install 'suggPKG' to use this function.") suggPKG::function() biocViews Este campo es obligatorio! Especifica al menos dos biocViews. Los términos deben provenir del mismo tipo de paquete (Software, AnnotationData, ExperimentData o Workflow). Puedes encontrar más información en: https://www.bioconductor.org/packages/release/BiocViews.html BugReports Se recomienda apuntar hacia el repositorio de GitHub, por ejemplo: https://github.com/usuario/paquete/issues. URL Se incluyen los links importantes, como el repositorio con el código fuente y el sitio web de pkgdown si se cuenta con él. Por ejemplo: https://github.com/usuario/paquete https://usuario.github.io/paquete 4.5 Modificando el archivo NEWS Secciones: New: Nuevas funciones. Bug fixes: Reparación de errores en las funciones previas o en la documentación. Changes: Cambios en el código de las funciones, incluyendo modificaciones en los argumentos. Breaking changes: Cambios importantes que romperían el código en caso de no ser atendidos, por ejemplo el uso de funciones o argumentos antiguos. Enhancements: Mejoras a las funciones existentes. Formato El archivo NEWS se ve similar a este ejemplo: "],["creando-mis-primeras-funciones.html", "5 Creando mis primeras funciones 5.1 Diapositivas 5.2 Nombre de la función 5.3 Estructura de la función 5.4 ¡Tu turno! 5.5 Argumentos 5.6 ¡Tu turno! 5.7 Indentación 5.8 Uso de espacios 5.9 Comentarios 5.10 Mensajes para el usuario", " 5 Creando mis primeras funciones Instructora: Joselyn Chávez 29 de octubre de 2024 5.1 Diapositivas 5.2 Nombre de la función Cortos pero descriptivos Recomendable: Separar las palabras con _ Establecer una palabra en común al inicio para familias de funciones use_bioc_citation() # es mejor que citation() bioc_cit() usebioccitation() useBiocCitation() use.bioc.citation() 5.3 Estructura de la función Indentar las líneas de código. Agregar comentarios para separar/describir las secciones importantes. Usar la sintaxis paquete::funcion() cuando hacemos llamado a funciones de otros paquetes. usethis::use_r("subset_heatmap") Generemos el código de manera regular. Simulemos una matriz con diversas mediciones y grafiquemos los datos en un heatmap. mi_matriz <- matrix(rnorm(100), nrow = 10) rownames(mi_matriz) <- paste0("medicion_",letters[1:10]) colnames(mi_matriz) <- paste0("grupo_",letters[1:10]) library(ComplexHeatmap) Heatmap(mi_matriz, cluster_columns = FALSE, heatmap_legend_param = list(title = "valores")) Escribamos una función que permita seleccionar algunos grupos de interés y genere el heatmap. No la mejor opción: library(ComplexHeatmap) subset_heatmap <- function(x,mediciones=NULL,grupos=NULL) { x_subset <- x[mediciones,grupos] Heatmap(mi_matriz, cluster_columns=FALSE, heatmap_legend_param=list(title="valores")) } Un poco mejor: library(ComplexHeatmap) subset_heatmap <- function(x, mediciones = NULL, grupos = NULL) { x_subset <- x[mediciones,grupos] Heatmap(mi_matriz, cluster_columns = FALSE, heatmap_legend_param = list(title = "valores")) } Mucho mejor: subset_heatmap <- function(x, mediciones = NULL, grupos = NULL) { # subset matrix x_subset <- x[mediciones, grupos] # plot heatmap ComplexHeatmap::Heatmap( x_subset, cluster_columns = FALSE, heatmap_legend_param = list(title = "valores")) } Ejecutemos la función: subset_heatmap( mi_matriz, mediciones = c("medicion_a", "medicion_b", "medicion_c"), grupos = c("grupo_d","grupo_e","grupo_f")) 5.4 ¡Tu turno! Escribe una función que: Filtre la matriz y mantenga sólo los valores por encima de cierto valor. Genere el heatmap filtrado. Recuerda seguir las recomendaciones para escribir funciones. 5.5 Argumentos Los argumentos deben tener un nombre descriptivo y bien documentado. No la mejor opción: subset_heatmap <- function(x, m, g) { # subset matrix x_subset <- x[mediciones, grupos] } Una mejor opción: subset_heatmap <- function(x, mediciones, grupos) { # subset matrix x_subset <- x[mediciones, grupos] # plot heatmap ComplexHeatmap::Heatmap( x_subset, cluster_columns = FALSE, heatmap_legend_param = list(title = "valores")) } Los argumentos generalmente deben tener valores default. subset_heatmap <- function(x, mediciones = NULL, grupos = NULL, return_plot = TRUE) { # subset matrix x_subset <- x[mediciones, grupos] # plot heatmap ComplexHeatmap::Heatmap( x_subset, cluster_columns = FALSE, heatmap_legend_param = list(title = "valores")) } Evalúa la validez de los argumentos subset_heatmap <- function(x, mediciones = NULL, grupos = NULL, return_plot = TRUE) { stopifnot(is.matrix(x)) # subset matrix x_subset <- x[mediciones, grupos] # plot heatmap heatmap <- ComplexHeatmap::Heatmap( x_subset, cluster_columns = FALSE, heatmap_legend_param = list(title = "valores")) if(return_plot == TRUE) {return(heatmap)} } Este código no debe funcionar: subset_heatmap( as.data.frame(mi_matriz), mediciones = c("medicion_a", "medicion_b", "medicion_c"), grupos = c("grupo_d","grupo_e","grupo_f")) Nota: Usa las funciones is() para evaluar la clase de los objects, no uses class() == ni class() !=. Proporciona pistas para entender los errores. subset_heatmap <- function(x, mediciones = NULL, grupos = NULL, return_plot = TRUE) { if(!is.matrix(x)) {stop("x debe ser una matriz")} # subset matrix x_subset <- x[mediciones, grupos] # plot heatmap heatmap <- ComplexHeatmap::Heatmap( x_subset, cluster_columns = FALSE, heatmap_legend_param = list(title = "valores")) if(return_plot == TRUE) {return(heatmap)} } Este código debe dar un error, más un mensaje de ayuda. subset_heatmap( as.data.frame(mi_matriz), mediciones = c("medicion_a", "medicion_b", "medicion_c"), grupos = c("grupo_d","grupo_e","grupo_f")) 5.6 ¡Tu turno! Agrega pasos de evaluación para los otros argumentos de la función. Incluye mensajes de ayuda cuando el formato de los argumentos no es el esperado. 5.7 Indentación Usa 4 espacios para indentar, evita los tabs. No uses líneas de más de 80 caracteres. 5.8 Uso de espacios Usa un espacio después de la coma: a, b, c. Usa espacio después de operadores binarios: a == b. 5.9 Comentarios Usa “##” para comenzar las líneas de comentarios. Los comentarios deben usarse como notas y documentación solamente. No dejes código comentado que no se va a usar. Evita los TODO’s comentados cuando vayas a publicar el paquete. 5.10 Mensajes para el usuario Si deseas imprimir mensajes para el usuario, como el progreso del análisis en la función o advertir sobre los valores de los argumentos, evita el uso de cat(), mejor usa: message() comunica mensajes diagnóstico, como el progreso de la función. message("Paso 1: completo") ## Paso 1: completo warning() comunica situaciones inusuales que pueden ser manejadas por tu código. warning("El número de elementos esperados es mayor a uno, se tomará el primer valor del vector") ## Warning: El número de elementos esperados es mayor a uno, se tomará el primer ## valor del vector stop() indica una condición errónea. stop("x debe ser numérico") "],["documentación-de-funciones.html", "6 Documentación de funciones 6.1 Diapositivas 6.2 Links importantes: 6.3 ¿Qué es la documentación de una función y por qué es importante? 6.4 Generacion de la documentacion con ayuda del paquete roxygen 6.5 Antes de empezar…✏️ 6.6 Generacion de un bloque de documentacion con ayuda del paquete roxygen. 6.7 Otros campos de la documentacion.", " 6 Documentación de funciones Instructor/a: 29 de octubre de 2024 6.1 Diapositivas 6.2 Links importantes: Esta lección está basada en algunos manuales sobre documentación: Una viñeta del cranproject El manual de paqutes de r En esta viñeta de cranproject 6.3 ¿Qué es la documentación de una función y por qué es importante? 🙇️ Es la información complementaria que el desarrollador escribe sobre una función y que se accede con ? seguido el nombre de una función actual de un paquete p.ej. ?unafuncion. 📁 La documentación se almacena como un archivo .Rd (“R documentation) en la carpeta man/. 🔎 La documentación usa una síntesis especial, que es distinta a la de r y que está ligeramente basada en LaTeX. 📄 Se puede renderizar como html, pdf o texto sin formato según se necesite. 6.4 Generacion de la documentacion con ayuda del paquete roxygen En un paquete de r y en cualquier ecosistema de devtools no editamos un documento .Rd manualmente. La documentación usa una síntesis parecida a LaTex que puede ser fácil de estropear. Por ventaja existen paquetes como roxigen2. Usar roxigen nos permite usar comentarios especiales sobre el inicio de la función, esto nos da un par de ventajas: ✅ La documentación y la función estarán en un mismo lugar, por lo que si editas la función será mas fácil recordar actualizar la documentcion también. 🎉 Puedes usar markdown en lugar de la síntesis especial para los archivos .Rd 6.5 Antes de empezar…✏️ Vamos a crear un función para nuestro paquete. Supongamos que para nuestro paquete necesitamos una función que calcule la moda. Esta es una forma sencilla de calcular la moda: getmode <- function(serievector) { uniqv <- unique(serievector) uniqv[which.max(tabulate(match(serievector, uniqv)))] } unique(serievector): Crea un vector que contiene únicamente los valores únicos de la serie de números serievector. match(serievector, uniqv): Encuentra la posición de cada valor de serievector en el vector único uniqv. tabulate(match(serievector, uniqv)): Cuenta cuántas veces aparece cada valor en la serie serievector. which.max(tabulate(match(serievector, uniqv))): Encuentra el índice del valor máximo en el vector de frecuencias. uniqv[which.max(tabulate(match(serievector, uniqv)))]: Devuelve el valor correspondiente al índice calculado, que es la moda. Creamos un ejemplo para ver que funcione: serie_numeros <- c(1, 2, 2, 2, 2, 3, 3, 4, 4, 4) resultado <- getmode(serie_numeros) print(resultado) ## [1] 2 Bien ahora si podemos podemos empezar a usar el paquete de roxygen para documentar nuestra función.. comencemos. 6.6 Generacion de un bloque de documentacion con ayuda del paquete roxygen. Podemos insertar un esqueleto de comentarios de roxygen para ver su síntesis. Colocamos el cursor en algún lugar de la definición de nuestra función y buscamos en la pestaña Código > Insertar Roxygen Skeleton. #' Title #' #' @param serievector #' #' @return #' @export #' #' @examples getmode <- function(serievector) { uniqv <- unique(serievector) uniqv[which.max(tabulate(match(serievector, uniqv)))] } Ahora ya tenemos un esqueleto de la documentación que nos da una ventaja para su creación. Las líneas de comentarios de Roxygen siempre comienzan con #', el habitual para un comentario # mas un ' Veamos los comentarios de uno por uno: Empezamos con el titulo. Se sugiere poner en el titulo las acciones principales que realiza la función en este caso por ejemplo podremos usar: #' @title Encontrar la Moda de una Serie de Números #' #' @param serievector #' #' @return #' @export #' #' @examples getmode <- function(serievector) { uniqv <- unique(serievector) uniqv[which.max(tabulate(match(serievector, uniqv)))] } Muy bien!. El siguiente comentario que podemos ver es @param. Pero antes, vamos a añadir una pequeña descripción de la función y como usarla. Primero añadimos la pequeña descripción con @description: #' @title Encontrar la Moda de una Serie de Números #' #' @description Esta función lee una serie de números en forma de vector y #' encuentra el elemento que mas se repite, es decir la moda. #' @param serievector #' #' @return #' @export #' #' @examples getmode <- function(serievector) { uniqv <- unique(serievector) uniqv[which.max(tabulate(match(serievector, uniqv)))] } Ahora vamos a añadir el comentario @usage que nos indica como puedes mandar a llamar la función. #' @title Encontrar la Moda de una Serie de Números #' #' @description Esta función lee una serie de números en forma de vector y #' encuentra el elemento que mas se repite, es decir la moda. #' @usage getmode(serievector) #' @param serievector #' #' @return #' @export #' #' @examples getmode <- function(serievector) { uniqv <- unique(serievector) uniqv[which.max(tabulate(match(serievector, uniqv)))] } Ahora si vamos a añadir una pequeña descripción de nuestros argumentos. Si tuviéramos mas de un parámetro en nuestra función podríamos llamar las veces que sea necesario el comentario de parámetro con @param, veamoslo. Ahora añadimos una pequeña descripción a nuestro único parámetro que es serievector: #' @title Encontrar la Moda de una Serie de Números #' #' @description Esta función lee una serie de números en forma de vector y #' encuentra el elemento que mas se repite, es decir la moda. #' #' @param serievector Es una serie de números en forma de un vector simple de r. #' #' @return #' @export #' #' @examples getmode <- function(serievector) { uniqv <- unique(serievector) uniqv[which.max(tabulate(match(serievector, uniqv)))] } Después, podemos añadir un comentario de detalles de la función con @details. Por ejemplo, si en nuestro ejemplo tuviéramos ciertos valores no numéricos en nuestro vector de entrada, por ejemplo letras, ¿nuestra función podría leerlas?, o si le diéramos un vector sin caracteres ¿que pasaría?, veamos: serie_numeros <- c(0,2,2,"d", "d","d") resultado <- getmode(serie_numeros) print(resultado) ## [1] "d" serie_numeros <- c() resultado <- getmode(serie_numeros) print(resultado) ## NULL Entonces, esto es un ejemplo de lo que podríamos poner en el comentario @details. Hagamoslo describiendo esto. En details podemos agregar detalles un poco mas específicos que en la descripción de la función #' @title Encontrar la Moda de una Serie de Números #' #' @description Esta función lee una serie de números en forma de vector y #' encuentra el elemento que mas se repite, es decir la moda. #' #' @param serievector Es una serie de números en forma de un vector simple de r. #' #' @details si tu vector de entrada puede ser interpretado alternando números y #' letras escritas entre comillas "". Si un vector esta vacío, dará como #' resultado un NULL. #' @return #' @export #' #' @examples getmode <- function(serievector) { uniqv <- unique(serievector) uniqv[which.max(tabulate(match(serievector, uniqv)))] } Ya casi terminamos de llenar nuestra documentación, pero antes vamos a ver algunos otros arrobas que pudieran ser importantes. El @import e @importfrom importan funciones de otros paquetes en caso de que las necesitemos, el primero importa todas las funciones del paquete que que solicites, y el segundo importa solo algunas funciones especificas. En nuestra función no necesitamos llamar funciones de otros paquetes puesto que todas las que usamos están en r base. Pero imaginemos que tu función, por ejemplo necesita leer un archivo .tsv con la función read_tsv del paquete readr y después reconvertir la tabla resultante en un archivo con write.table pero solo necesitas esa función del paquete utils, entonces haríamos: #' @title Encontrar la Moda de una Serie de Números #' #' @description Esta función lee una serie de números en forma de vector y #' encuentra el elemento que mas se repite, es decir la moda. #' #' @param serievector Es una serie de números en forma de un vector simple de r. #' #' @details si tu vector de entrada puede ser interpretado alternando números y #' letras escritas entre comillas "". Si un vector esta vacío, dará como #' resultado un NULL. #' @import readr #' @importFrom utils write.table #' @return #' @export #' #' @examples getmode <- function(serievector) { uniqv <- unique(serievector) uniqv[which.max(tabulate(match(serievector, uniqv)))] } Así podemos importar las funciones que necesitemos de otros paquetes y se incluirán en la documentación y se cargaran automáticamente al cargar tu paquete. :eyes::exclamation: Para un correcto funcionamiento de tu paquete y al estar los paquetes necesarios incluidos en la documentación, no será necesario llamarlos de la forma ``library(“apackage”)```. Entonces llegamos a la sección @return. Esta descripción le servirá al usuario del paquete para conocer cual sera el resultado de la función, que puede ser un archivo, una tabla, un numero,etc. Entonces retomando la función que usamos al inicio, vamos a escribir una descripción corta del resultado de la función getmode(). #' @title Encontrar la Moda de una Serie de Números #' #' @description Esta función lee una serie de números en forma de vector y #' encuentra el elemento que mas se repite, es decir la moda. #' #' @param serievector Es una serie de números en forma de un vector simple de r. #' #' @details si tu vector de entrada puede ser interpretado alternando números y #' letras escritas entre comillas "". Si un vector esta vacío, dará como #' resultado un NULL. #' @return El carácter con mas frecuencia de el vector de entrada. #' @export #' #' @examples getmode <- function(serievector) { uniqv <- unique(serievector) uniqv[which.max(tabulate(match(serievector, uniqv)))] } Por ultimo tenemos @export que es el encargado de renderizar la documentación para que pueda aparecer en la ventana de Ayuda (abajo a la derecha). esta opción la dejamos para funciones principales que el usuario va a utilizar, aunque puede que existan alguna funciones internas que no queremos que el usuario vea. En ese caso vamos a usar @noRd en lugar de este. Antes de terminar podemos incluir ejemplos de como funciona nuestra función para un mejor entendimiento, pongamos los que ya realizamos: #' @title Encontrar la Moda de una Serie de Números #' #' @description Esta función lee una serie de números en forma de vector y #' encuentra el elemento que mas se repite, es decir la moda. #' #' @param serievector Es una serie de números en forma de un vector simple de r. #' #' @details si tu vector de entrada puede ser interpretado alternando números y #' letras escritas entre comillas "". Si un vector esta vacío, dará como #' resultado un NULL. #' @return El carácter con mas frecuencia de el vector de entrada. #' @export #' #' @examples #' serie_números <- c(1, 2, 2, 2, 2, 3, 3, 4, 4, 4) #' resultado <- getmode(serie_números) #' print(resultado) getmode <- function(serievector) { uniqv <- unique(serievector) uniqv[which.max(tabulate(match(serievector, uniqv)))] } Ahora si, una vez teniendo listo el bloque de comentarios para la documentación, vamos a ejecutar devtools::load_all() para cargar nuestras funciones y hecho esto, ejecutamos devtools::document() o presionamos Ctrl/Cmd + Shift + D para convertir los comentarios en archivo .Rd y poder renderizarlo. 💯 Listo, tenemos nuestra documentación para una función. Así se verá cuando el paquete esté terminado. 6.7 Otros campos de la documentacion. @seealso para indicar funciones relacionadas y facilitar la búsqueda de funciones. @references añade algunas referencias. @author para especificar el autor de la función. "],["diseño-de-pruebas.html", "7 Diseño de pruebas 7.1 Diapositivas", " 7 Diseño de pruebas Mirna Vázquez Rosas-Landa 30 de octubre de 2024 7.1 Diapositivas "],["creación-de-viñetas.html", "8 Creación de viñetas 8.1 ¿Qué es una viñeta/vignette? 📝✨ 8.2 Características de una vignette 🌟 8.3 ¿Cómo consultar la viñeta de un paquete? ❓🔍 8.4 ¿Cómo crear una viñeta? ❓🔍 8.5 ¿Cómo guardar y actualizar la viñeta? 🔄💻 8.6 Veamos un ejemplo 🔍👨💻 8.7 Actividad", " 8 Creación de viñetas José Antonio Ovando Ricárdez 30 de octubre de 2024 8.1 ¿Qué es una viñeta/vignette? 📝✨ Es una guía extendida sobre cómo funciona el paquete. Es recomendable que muestre cómo utilizar las funciones del paquete, aplicado en un flujo de trabajo; por ejemplo: el análisis estadístico de una encuesta 📊 o el análisis de expresión diferencial de genes. Podemos estructurarlo como haríamos con la escritura de un capítulo de libro o de un artículo científico: debe mostrar el problema a resolver y la metodología paso a paso sobre cómo el paquete lo resuelve. Si el paquete contiene funciones que se complementan entre sí para alcanzar un fin específico, entonces debes mostrar su uso de forma compartamentalizada. 8.2 Características de una vignette 🌟 Debe mostrar un flujo de análisis explotando el potencial de tu paquete 📊🚀. Implementa tantas funciones de tu paquete como sea posible, pero no es necesario que incluya todas 🛠️✨. Los datos a usar deben ser pequeños o fáciles de acceder 📂🔍. Puedes crear múltiples viñetas para mostrar diferentes casos de análisis y cubrir una mayor cantidad de funciones 📝📚. 8.3 ¿Cómo consultar la viñeta de un paquete? ❓🔍 browseVignettes(package = "ggplot2") 8.4 ¿Cómo crear una viñeta? ❓🔍 biocthis::use_bioc_vignette("mi_vignette") Esta función tendrá tres efectos ✨: Generar el directorio vignettes en caso que no exista 📂🔧. Agregar dependencias en el archivo DESCRIPTION (por ejemplo, knitr necesario para construir viñetas dentro del paquete) 📄📦. Abrir un template en formato .Rmd para comenzar a escribir la viñeta, que se va a guardar en vignettes/mi_vignette.Rmd 📝💾. 8.5 ¿Cómo guardar y actualizar la viñeta? 🔄💻 Una vez que se ha generado el archivo vignettes/mi_vignette.Rmd, se hacen las modificaciones necesarias. Puedes usar el comando: edit_file("vignettes/mi_vignette.Rmd") Para guardar los cambios, debes hacer clic en el botón Knit o utiliza la combinación de teclas Ctrl/Cmd-Shift-K 💾✨. 8.6 Veamos un ejemplo 🔍👨💻 Busca la viñeta del paquete regutools en la página de Bioconductor 🌐: Viñeta de regutools en Bioconductor 📦📄 8.7 Actividad 8.7.1 Ejercicio 1: Identificación de viñetas en paquetes de interés en Bioconductor 📚🔍 En equipos selecciona dos paquetes almacenados en Bioconductor que sean de tu interés y responde las siguientes preguntas: ¿Ambos paquetes incluyen viñetas? 📝❓ ¿Qué aspectos de la viñeta del paquete A versus el paquete B te llaman más la atención? 🔍🤔 ¿Consideras que alguna viñeta está mejor desarrollada que la otra? Explica por qué 💭📊. 8.7.2 Ejercicio 2: Creación de viñetas en R 🛠️📄 Pasos: 1. Cargar los paquetes necesarios library(usethis) library(biocthis) Crear un nuevo paquete de R (si no tienes uno ya creado) # usethis::create_package("CDSB2024") Configurar el paquete para Bioconductor Ejecuta el siguiente comando para configurar el paquete con las mejores prácticas de Bioconductor: # biocthis::use_bioc_pkg_templates() Esto agregará varios archivos de configuración y plantillas útiles para trabajar con Bioconductor. Crear una viñeta con biocthis Ejecuta el siguiente comando para agregar una viñeta en formato R Markdown. Cambia “mi_vignette” por el título de la viñeta que prefieran. # usethis::use_vignette("mi_vignette_usethis") # biocthis::use_bioc_vignette("mi_vignette_biocthis") Esto creará un archivo R Markdown en la carpeta vignettes/ dentro del paquete. Editar la viñeta Abre el archivo creado en vignettes .Rmd. Incluye contenido que describa una función del paquete. Abrir la viñeta en el navegador y renderiza el archivo .Rmd # browseVignettes("CDSB2024") 8.7.3 Preguntas de Reflexión 🤔💭 ¿Cuál es la ventaja de documentar ejemplos de uso en una viñeta? 📚✨ ¿Qué estructura consideras útil para presentar ejemplos en una viñeta? 🏗️🔍 ¿Cómo aplicarías esta clase en tu proyecto colaborativo? 🤝📈 "],["compilación-e-instalación-de-paquetes.html", "9 Compilación e instalación de paquetes 9.1 Diapositivas 9.2 Metadatos de una paquetería 9.3 Licencias 9.4 Paqueterías de código fuente 9.5 ¿En dónde podemos encontrar el código fuente de un paquete? 9.6 Instalando la última versión en desarrollo 9.7 Instalando paquetes desde GitHub 9.8 Instalando un paquete local 9.9 Contribuyendo código", " 9 Compilación e instalación de paquetes Joselyn Cristina Chávez Fuentes 30 de octubre de 2024 9.1 Diapositivas 9.2 Metadatos de una paquetería Los metadatos de la paquetería se encuentran en el archivo DESCRIPTION. 9.2.1 Description El campo Description describe lo que hace tu paquetería. Suele ser extenso, si requieres escribir múltiples líneas, deben estar indentadas. Por ejemplo: # Description: Este paquete contiene todas las funciones generadas en el curso # de escritura de paqueterías en R. También contiene las funciones que cada # participante propuso para solucionar un problema relacionado con su trabajo. 9.2.2 Dependencias Las dependencias son las paqueterías que tu paquete necesita para funcionar. La lista de paquetes se escribe separada por comas y es recomendado que se escriban en orden alfabético. Existen tres tipos: Imports: Son paquetes que deben instalarse para que tu paquete funcione y por tanto se van a instalar en el momento que instales el paquete. Internamente existe una función que evalúa si los paquetes se encuentran instalados o no y solamente instala los faltantes. Esta dependencia hace solamente la instalación pero no ejecuta library(), por lo que los paquetes requeridos deberán ser cargados dentro de la escritura del paquete. Depends: Son paquetes que obligatoriamente deben estar para que tu paquetería funcione pero no se instalarán de manera automática. Aquí también se indica la versión de R requerida para el funcionamiento del paquete. Los paquetes que se listen aquí se van a cargar al mismo tiempo que se ejecute el library(mipaquete). Suggests: Se refiere a los paquetes que tu paquete puede utilizar y aprovechar para ser más poderoso en el análsis pero no los necesita para funcionar. Por ejemplo, paquetes que contienen sets de datos para hacer pruebas o análisis de práctica. Nota Importante Se recomienda listar los paquetes necesarios para el funcionamiento de nuestro paquete en Imports porque cuando se ponen en Depends se cargan los paquetes completos y probablemente solamente requerimos una o dos funciones. Cargar demasiados paquetes completos, sin ser necesario, sólo hace que nuestro paquete se vuelva pesado y lento. Es mejor llamar particularmente a las funciones usando la sintaxis explícita: Biostrings::translate() 9.2.3 ¿Cómo añadir dependencias? Usando usethis: usethis::use_package("ggplot2", type = "Imports") Editando manualmente el archivo DESCRIPTION. 9.3 Licencias Establece quién puede usar tu paquete. Existen diversas licencias pero hablaremos sobre las 3 más comunes: MIT (Massachusetts Institute of Technology): es simple y permisiva. Permite a cualquier persona usar y distribuir tu paquetería con una sola restricción: la distribución debe incluir la declaración de licencia del autor. Existe un texto base al cual se le pueden añadir cláusulas o excepciones. Este es un ejemplo: GPL-2 (General Public License): Permite usar y distribuir tu código con la condición que si se genera una versión modificada de tu código, su distribución debe ser también bajo esta licencia. Aunque está enfocada a la distribución de código abierto, permite dejar en claro quién es el autor del material y evitar la apropiación del código por terceros. Un ejemplo de la aplicación de esta licencia es el desarrollo de Linux. CCO: Esta licencia implica que cedes todos los derechos y el código puede ser utilizado con cualquier fin, excepto fines comerciales. Es el más utilizado en los paquetes. Concede el derecho a utilizar y distribuir el material sin requerir el permiso del autor. 9.4 Paqueterías de código fuente En algunas ocasiones necesitaremos instalar paquetes que no se encuentran compilados, por ejemplo: Paquetes en desarrollo de CRAN o Bioconductor. Versiones anteriores de paquetes de CRAN o Bioconductor. Paquetes que no se encuentran depositados en CRAN o Bioconductor, sino en repositorios personales como GitHub. Paquetes que estás desarrollando de forma local. El paquete remotes será de gran utilidad. Regularmente, los paquetes que instalamos desde algún repositorio como CRAN o Bioconductor son paquetes binarios que ya se encuentran compilados previamente. Existen algunas funciones que nos permiten instalar paquetes desde código fuente. Anteriormente, se solían utilizar las funciones install_* del paquete devtools; sin embargo, recientemente se creó el paquete remotes que contiene las mismas funciones pero está específicamente diseñado para ayudarnos a trabajar con paquetes desde código fuente. 9.5 ¿En dónde podemos encontrar el código fuente de un paquete? Si el paquete se encuentra disponible en CRAN, puedes encontrar el link al código fuente en la sección URL. Si el paquete se encuentra disponible en Bioconductor, puedes encontrar el link al código fuente en la sección Package Archives Si el paquete se encuentra en GitHub o GitLab, necesitarás conocer el nombre de usuario y el nombre del paquete. 9.6 Instalando la última versión en desarrollo Si el paquete se encuentra depositado en CRAN podemos usar la función remotes::install_dev("pkgname") Por ejemplo, para instalar la versión en desarrollo de dplyr usaremos el comando remotes::install_dev("dplyr") Si el paquete se encuentra en Bioconductor usaremos la siguiente función: remotes::install_bioc("pkgname") Por ejemplo, para instalar la versión en desarrollo de regutools, el paquete desarrollado por miembros de la CDSB, usaremos el comando remotes::install_bioc("regutools") 9.7 Instalando paquetes desde GitHub Para poder instalar un paquete desde GitHub necesitaremos conocer el usuario del creador y el nombre del repositorio. remotes::install_github("usuario/repositorio") Por ejemplo, para instalar el paquete starwarssay desarrollado por Erick Cuevas (Erickcufe) utilizaremos el siguiente comando: remotes::install_github("Erickcufe/starwarssay") Independientemente de si el paquete se encuentra en CRAN, Bioconductor, o ninguno de ellos, podemos instalar un paquete depositado en una cuenta de GitHub. Para poder instalar un paquete desde GitHub necesitaremos conocer el usuario del creador y el nombre del repositorio donde se encuentra depositado el paquete. Con esta información usaremos la siguiente función: 9.8 Instalando un paquete local Paso 1: Abre el proyecto del paquete que estás desarrollando. Paso opcional: Ejecuta la documentación si realizaste algún cambio. devtools::document() Paso 2: Construye el paquete: devtools::build() Paso 3: Instala el paquete desde tu proyecto actual: devtools::install() 9.9 Contribuyendo código Una ventaja de descargar el paquete de forma local es que puedes realizar cambios, probar que funciona de manera local y después contribuir (haciendo un pull-request). Usemos el paquete saludo Clona el repositorio en tu computadora. git clone https://github.com/ComunidadBioInfo/saludo.git Ahora puedes abrir el proyecto del paquete y agregar tu código. "],["creación-de-sitios-web-con-pkgdown.html", "10 Creación de sitios web con pkgdown 10.1 Diapositivas 10.2 Instalación 10.3 Configura el paquete para crear el sitio con pkgdown 10.4 Genera la estructura de pkgdown 10.5 Pre-visualiza el sitio de manera local 10.6 Personalizando el _pkgdown.yml 10.7 Las variables bslib 10.8 Layout 10.9 Accessibilidad 10.10 La página de inicio 10.11 La página de referencias 10.12 Articles 10.13 News 10.14 Publicando el sitio web", " 10 Creación de sitios web con pkgdown Joselyn Cristina Chávez Fuentes 31 de octubre de 2024 10.1 Diapositivas div.grey { background-color: #bfbfbf; } div.center { text-align:center; } 10.2 Instalación install.packages("pkgdown") 10.3 Configura el paquete para crear el sitio con pkgdown Este paso se ejecuta solamente una vez, dentro del proyecto del paquete. usethis::use_pkgdown_github_pages() Este paso genera las acciones automáticas de GitHub para renderizar el sitio. El archivo README.md será tu página de inicio, la documentación en man/ va a crear una sección de referencias, y las viñetas serán renderizadas como articles. 10.4 Genera la estructura de pkgdown Este paso se ejecuta solamente una vez. usethis::use_pkgdown() 10.5 Pre-visualiza el sitio de manera local Este paso lo puedes ejecutar para visualizar el sitio cada vez que hagas una modificación, antes de enviar los cambios a GitHub. pkgdown::build_site() 10.6 Personalizando el _pkgdown.yml 10.6.1 Metadatos URL Este es el link donde se va a renderizar el sitio, revisa que sea correcto y, de ser necesario, actualízalo. url: https://pkgdown.r-lib.org template Esta sección permite personalizar la apariencia general del sitio. template: bootstrap: 5 bootswatch: cerulean 10.6.2 Temas Light switch Puedes proporcionar un “light switch” para permitir a tus usuarios cambiar entre temas oscuros y claros configurando la opción de light-switch a true: template: light-switch: true Bootswatch themes La forma más fácil de cambiar toda la apariencia de tu sitio web es usar un tema de Bootswatch: template: bootstrap: 5 bootswatch: materia Puedes ver los temas disponibles en https://bootswatch.com/ Estos temas suelen no ser compatibles con el light switch, pero puedes intentar. Al cambiar el bootswatch theme necesitas renderizar el sitio para ver por completo los efectos del tema. build_site() Mientras estás experimentando, puedes acelerar las cosas simplemente reconstruyendo la página de inicio y el CSS ejecutando: build_home_index() init_site() y luego actualizando el navegador. Los bootswatch theme con barras de navegación altas (lux, pulse) también requieren que se modifique la variable pkgdown-nav-height. Debido a que los temas de bootswatch son proporcionados por el paquete bslib, se puede anidar el campo bootswatch debajo del campo bslib. template: bootstrap: 5 bslib: bootswatch: lux pkgdown-nav-height: 100px 10.7 Las variables bslib Hay tres variables clave que afectan al color: bg (fondo) determina el fondo de la página. fg (primer plano) determina el color del texto. primary establece el color del enlace y el color translúcido en la barra de navegación y la barra lateral. template: bootstrap: 5 bslib: bg: "#202123" fg: "#B8BCC2" primary: "#306cc9" También se pueden personalizar las fuentes predeterminadas utilizadas para la mayoría del texto (base_font), para los encabezados (heading_font) y para el código (code_font). La forma más fácil es proporcionar el nombre de una fuente de Google con la siguiente sintaxis: template: bootstrap: 5 bslib: base_font: {google: "Roboto"} heading_font: {google: "Roboto Slab"} code_font: {google: "JetBrains Mono"} 10.7.1 Syntax highlighting Los colores utilizados para el resaltado de sintaxis en bloques de código están controlados por la configuración theme: template: bootstrap: 5 theme: breeze-light Puedes elegir entre: a11y-dark, a11y-light, arrow-dark, arrow-light, atom-one-dark, atom-one-light, ayu-dark, ayu-light, ayu-mirage, breeze-dark, breeze-light, breezedark, dracula, espresso, github-dark, github-light, gruvbox-dark, gruvbox-light, haddock, kate, monochrome-dark, monochrome-light, monochrome, monokai, nord, oblivion, printing, pygments, radical, solarized-dark, solarized-light, solarized, tango, vim-dark, zenburn. 10.7.2 Navbar style Los campos bg y type de la barra de navegación controlan los colores del fondo y el primer plano respectivamente. Normalmente bg será light, dark, o primary: navbar: bg: primary 10.8 Layout Puedes personalizar el contenido de la barra de navegación, pie de página, utilizando los campos navbar y footer. Todos ellos utilizan una estructura similar que define por separado la estructura global y los componentes individuales. 10.8.1 Navbar Esta es la estructura default: navbar: structure: left: [intro, reference, articles, tutorials, news] right: [search, github, lightswitch] intro: “Get Started”, enlaza a una viñeta o artículo con el mismo nombre que el paquete. reference: si hay archivos . Rd. articles: si hay viñetas o artículos. tutorials: si hay algún tutorial. news: si existe NEWS.md. search: la barra de búsqueda. github: un enlace al repositorio de origen (con un icono), es determinado automáticamente a partir del archivo DESCRIPTION. lightswitch; un “interruptor de luz” para seleccionar el modo claro, modo oscuro o modo automático. Puedes utilizar el campo structure para reorganizar la barra de navegación: navbar: structure: left: [search] right: [reference, articles] Puedes usar la misma sintaxis para organizar el menú de artículos: navbar: components: articles: text: Articles menu: - text: Category A - text: Title A1 href: articles/a1.html - text: Title A2 href: articles/a2.html - text: ------- - text: "Category B" - text: Article B1 href: articles/b1.html 10.8.2 Footer Esta es la estructura por defecto:: footer: structure: left: developed_by right: built_with Que utiliza dos de los tres componentes incorporados: developed_by: una frase que describe a los principales autores del paquete. built_with: una frase que hace publicidad de la misma. package: el nombre del paquete. Puedes personalizar la organización del pie de página: footer: structure: left: pkgdown right: [developed_by, legal] components: legal: Provided without **any warranty**. 10.9 Accessibilidad Las configuraciones default de pkgdown tratan de hacer el sitio lo más accesible posible para todos, pero hay algunos puntos a tomar en cuenta: 10.9.1 Colores Si ajustas cualquier color del tema default, verifica que el contraste entre el fondo y el primer plano no haga difícil leer ningún texto. Puedes utilizar la herramienta de evaluación de accessibilidad en https://wave.webaim.org. El color default genera un contraste demasiado bajo contra el fondo gris pálido de la barra de navegación. Este color viene de la paleta “danger” de bootstrap, así que puedes arreglarlo sobreescribiendo esa variable en tu _pkgdown.yml: template: bootstrap: 5 bslib: danger: "#A6081A" Si utilizas entradas de barra de navegación personalizadas que sólo muestran un icono, asegúrate de utilizar también el campo aria-label para proporcionar una etiqueta accesible que describa el icono. cran: icon: fab fa-r-project href: https://cloud.r-project.org/package=pkgdown aria-label: View on CRAN 10.9.2 Imágenes Para hacer tu sitio completamente accessible, agrega una descripción del contenido de las imágenes en las viñetas usando el campo “fig.alt” de las opciones del chunk de R. 10.10 La página de inicio Los contenidos del home page son automáticamente generados desde el archivo index.md o el README.md. pkgdown les asigna diferentes prioridades, por lo que es possible tener contenidos diferentes en el repositorio de GitHub y la página de pkgdown si provees ambos archivos. La página de inicio también incluye una barra de contenidos con links importantes, como la guía de contribución, el código de conducta, etc. 10.11 La página de referencias pkgdown crea una página de referencia en reference/ para cada una de las funciones del paquete, basado en la documentación. pkgdown ejecuta todos los ejemplos de las funciones, insertando los resultados renderizados en los archivos HTML generados. Por defecto, pkgdown genera un índice de referencia que es sólo una lista de funciones ordenadas alfabéticamente. El índice es mucho más útil con la curación manual porque las funciones pueden agruparse y describirse en categorías. Cada entrada de referencia puede adoptar una de las tres formas siguientes: Un título, definido por los campos title y desc (descripción) opcionales. Un subtítulo, definido por los campos de subtítulo y desc (descripción) opcionales. Lista de temas definidos por un campo de contenido. Mientras editas el índice de referencias, puedes ejecuar la siguiente función para renderizar solamente el índice, lo que permite ver de forma rápida el efecto de los cambios sin tener que renderizar todo el sitio. pkgdown::build_reference_index() reference: - title: "Connecting to Spark" desc: > Functions for installing Spark components and managing connections to Spark contents: - spark_config - spark_connect - spark_disconnect - spark_install - spark_log 10.12 Articles pkgdown creará automáticamente todas las viñetas que se encuentran en la carpeta vignettes/, traduciéndolas a archivos HTML en articles/. Se puede nombrar el artículo de introducción con el nombre del paquete para generar una página “Get Started” automáticamente. 10.13 News Si el archivo NEWS.md está presente, se procesará en un changelog de una sola página basado en los títulos de las secciones del archivo. pkgdown asume que el archivo NEWS.md está formateado con encabezados de nivel uno (#) para especificar el nombre del paquete y el número de versión, y con encabezados de nivel dos (##) para proporcionar una organización temática para cada versión. # pkgdown 1.1.0 ## Bug Fixes * Lots of them 10.14 Publicando el sitio web Haz commit de los cambios y luego push. Ve al repositorio del paquete en GitHub y espera a que la acción de GitHub termine de renderizar el sitio. Ve al sitio web, el formato debe ser similar a https://usuario.github.io/paquete "],["proyectos-colaborativos-1.html", "11 Proyectos colaborativos 11.1 Propuesta 1 11.2 Propuesta 2 11.3 Propuesta 3 11.4 Propuesta 4 11.5 Propuesta 5", " 11 Proyectos colaborativos 11.1 Propuesta 1 11.2 Propuesta 2 11.3 Propuesta 3 11.4 Propuesta 4 11.5 Propuesta 5 "],["404.html", "Page not found", " Page not found The page you requested cannot be found (perhaps it was moved or renamed). You may want to try searching to find the page's new location, or use the table of contents to find the page you are looking for. "]]
+[["index.html", "Desarrollo de paqueterías de R/Bioconductor. Bienvenida 0.1 Instructores 0.2 Ayudantes 0.3 Temario 0.4 Patrocinadores 0.5 Licencia", " Desarrollo de paqueterías de R/Bioconductor. Dra. Joselyn Cristina Chávez-Fuentes, Dra. Mirna Vázquez Rosas-Landa, M.C. Erick Cuevas-Fernández, Dra. Alejandra Medina-Rivera, Bienvenida Les damos la bienvenida al Workshop Desarrollo de paqueterías de R/Bioconductor! En este taller aprenderás cuáles son los pasos cruciales para desarrollar un paquete de R y algunas buenas prácticas para la generación de código. Con la integración de estas herramientas, tendrás la oportunidad de crear tu primer paquete y contribuir a la comunidad de desarrolladores. Adicionalmente, aprenderás a crear un sitio web para mostrar el funcionamiento de un paquete de R. 0.1 Instructores Dra. Joselyn Cristina Chávez Fuentes: Estancia Postdoctoral en Icahn School of Medicine at Mount Sinai. Dra. Alejandra Medina Rivera: Investigadora Asociada en el Laboratorio Internacional de Investigación de Medicina Genómica, UNAM. Dra. Yalbi I. Balderas-Martínez: Investigadora en el Instituto Nacional de Enfermedades Respiratorias Ismael Cosío Villegas. Dra. Mirna Vázquez Rosas Landa: Investigadora en el Instituto de Ciencias de Mar y Limnología de la UNAM. M.C. Erick Cuevas Fernández: Estudiante de Doctorado en la Universidad Nacional Autónoma de México. M.C. José Antonio Ovando Ricárdez: Estudiante de Doctorado en el Instituto Nacional de Enfermedades Respiratorias Ismael Cosío Villegas. 0.2 Ayudantes Dra. Evelia Coss: Posdoctoral en el Laboratorio Internacional de Investigación de Medicina Genómica, UNAM. M.C. José Antonio Ovando Ricárdez: Estudiante de Doctorado en el Instituto Nacional de Enfermedades Respiratorias Ismael Cosío Villegas. 0.3 Temario Consulta el calendario de este curso en: https://bit.ly/calendarcdsb2024 Día 1: Flujo de trabajo orientado a proyectos: Introducción al trabajo con proyectos de RStudio. Paths seguros. Control de versiones con GitHub y RStudio. Solución de problemas con las versiones de paquetes de Rstudio. Día 2: Creación de paquetes de R/Bioconductor Parte I Infraestructura de un paquete de R/Bioconductor. Documentación de funciones. Sesión social: Conociendo a la comunidad. Proyectos colaborativos Parte I. Día 3: Creación de paquetes de R/Bioconductor Parte II Diseño de pruebas. Creación de viñetas. Compilación e instalación de paquetes. Proyectos colaborativos Parte II. Día 4: Creación de sitios web para la documentación de paquetes de R Creación de sitios web con pkgdown Proyectos colaborativos Parte III. Presentación de proyectos. Clausura. 0.4 Patrocinadores Agradecemos a nuestros patrocinadores: 0.5 Licencia Este material posee una licencia tipo Creative Commons Attribution-ShareAlike 4.0 International License. Para conocer más sobre esta licencia, visite http://creativecommons.org/licenses/by-sa/4.0/ "],["trabajando-con-proyectos-de-rstudio.html", "1 Trabajando con proyectos de RStudio 1.1 Diapositivas 1.2 ¿Qué es un proyecto de RStudio? 1.3 ¿Cómo generamos un proyecto de RStudio? 1.4 ¿Por qué usar proyectos de RStudio? 1.5 Algunos hacks! 1.6 Generando rutas seguras", " 1 Trabajando con proyectos de RStudio Joselyn Cristina Chávez Fuentes 28 de octubre de 2024 1.1 Diapositivas div.grey { background-color: #bfbfbf; } div.center { text-align:center; } 1.2 ¿Qué es un proyecto de RStudio? Es un archivo especial de R, compatible con RStudio, que al ejecutarlo hará 3 cosas: Abrirá una nueva sesión de RStudio. Establecerá la ubicación del proyecto como tu directorio de trabajo. Establecerá la ubicación del proyecto como la raíz de los archivos. 1.3 ¿Cómo generamos un proyecto de RStudio? 1.3.1 Opción 1: Creando un proyecto en un directorio nuevo. En las opciones de RStudio Ve a File > New project > New Directory > New Project. Asigna un nombre a tu proyecto, sin espacios y sin caracteres especiales. Selecciona la ubicación donde crearás el nuevo directorio. Selecciona la opción Open in New Session. Oprime Create Project. 1.3.2 Opción 2: Creando un proyecto en un directorio existente. Crea un directorio en alguna ubicación conocida de tu computadora. Asigna un nombre a tu directorio, sin espacios y sin caracteres especiales (Este será el nombre de tu proyecto). En las opciones de RStudio ve a File > New project > Existing Directory. Selecciona la ubicación donde previamente creaste el directorio. Selecciona la opción Open in New Session. Oprime Create Project. 1.4 ¿Por qué usar proyectos de RStudio? Te permiten ser más organizado y pasar de tener una ensalada de archivos a tener carpetas para cada sección del análisis. Compartamentalizas tu trabajo al generar un proyecto específico para cada análisis. Te permiten trabajar con varios proyectos a la vez en sesiones independientes de RStudio, cada uno con sus propias variables, directorio de trabajo y archivos. Establece automáticamente tu directorio de trabajo. En lugar de usar setwd() solamente requieres ejecutar el archivo .Rproj para abrir la sesión y trabajar en la ubicación del proyecto. Puedes usar rutas relativas (y estables) a tus archivos, que seguirán funcionando sin importar en dónde se ubique tu proyecto. Facilita el compartir y reproducir tu trabajo. No más rutas al estilo ~/MiComputadora/MiFolder/MiArchivo. Comparte la carpeta completa de tu proyecto con todos los archivos necesarios y usa rutas relativas dentro del Rscript, por ejemplo ./datos. Nos ayuda a establecer colaboraciones y trabajar con plataformas de control de versiones. Actividad Comprueba algunas ventajas de usar proyectos de RStudio. Genera un nuevo proyecto de RStudio llamado ‘miproyecto’, recuerda que existen varias formas para hacerlo. Cierra la sesión y vuelve a abrirla ejecutando desde la terminal open miproyecto.Rproj o dando doble click sobre el archivo miproyecto.Rproj. Evalúa tu directorio de trabajo ejecutando en la consola de RStudio el comando getwd(). Cierra la sesión y mueve toda la carpeta de tu proyecto a otra ubicación. Si lo creaste en Documentos mueve la carpeta al Escritorio o viceversa. Abre nuevamente el proyecto y verifica el directorio de trabajo, ¿Cambió el directorio de trabajo? Sin cerrar este proyecto, abre alguno de los proyectos que generaste previamente (por ejemplo directorioprevio.Rproj), recuerda que puedes seleccionar Open Project in New session 1.5 Algunos hacks! RStudio recuerda los proyectos con los que has trabajado recientemente. Ve a la esquina superior derecha y da click en la flecha junto al nombre de tu proyecto actual. Verás todos los proyectos recientes. Si das click en el nombre de alguno de ellos te abrirá el proyecto en la misma sesión, si das click en el recuadro con flecha blanca te abrirá una nueva sesión con tu proyecto. Crea todos tus proyectos dentro de una carpeta principal y usa el buscador de archivos para acceder a ellos rápidamente. 1.6 Generando rutas seguras Se construyen a partir de una base estable El directorio de trabajo cambia de usuario a usuario y dependiendo de la ubicación de los archivos. getwd() Deben funcionar en cualquier sistema operativo Una ruta en sistemas Linux se ve así: "/Users/joselynchavez/Documents/materiales_cdsb2024" Mientras que una ruta en Windows se ve así: "C:\\Documents/materiales_cdsb2024" 1.6.1 El paquete here Usemos el paquete here para detectar la ubicación del proyecto: here::here() Ahora generemos una ruta segura a partir de la raíz del proyecto here::here("mi_tabla.csv") here::here("subfolder", "mi_tabla.csv") 1.6.2 Usando el paquete fs Por defecto, usa el directorio de trabajo actual como base y detecta el sistema operativo automáticamente. fs::path("mi_tabla.csv") fs::path("subfolder", "mi_tabla.csv") Tiene como ventaja que puede construir las rutas a partir del home del usuario. fs::path_home() fs::path_home("mi_tabla.csv") 1.6.3 Usando funciones base Si no deseas incluir el paquete ‘here’ en las dependencias de tu paquete, puedes usar la función file.path Esta función usa como base el directorio de trabajo actual y detecta el sistema operativo para construir la ruta. file.path("mi_tabla.csv") file.path("subfolder", "mi_tabla.csv") "],["control-de-versiones-con-github-y-rstudio.html", "2 Control de versiones con GitHub y RStudio 2.1 Diapositivas 2.2 ¿Por qué hacer control de versiones de nuestros proyectos? 2.3 Git 2.4 Recomendaciones para sus proyectos 2.5 Proyectos colaborativos 2.6 GitHub 2.7 Manual de sobreviviencia con Git Y GitHub en RStudio (en caso de ser necesario) 2.8 Cómo clonar un repositorio y tener conección/permisos para modificarlo? 2.9 Credenciales HTTPS en Cache 2.10 Conectando RStudio con Git y Github. 2.11 GitHub primero, RStudio después… 2.12 Rmarkdown en GitHub 2.13 RStudio primero y GitHub también 2.14 Proyecto existente, GitHub al final 2.15 Git basics: commands 2.16 Merge conflics 2.17 Merge conflics 2.18 En resumen", " 2 Control de versiones con GitHub y RStudio Dra. Alejandra Medina Rivera 28 de octubre de 2024 div.color { border-radius: 5px; padding: 20px; margin: 30px 0px 30px;} div.red { background-color:#f67155; } div.orange{ background-color:#f0BB51;} div.pair { display: flex; flex-direction: row; justify-content: center; text-align:center; padding:0px} div.inside { width: 49%; padding: 0px} div.scroll { max-height: 400px; overflow-y: auto; background: #111111; border-radius:5px; padding: 10px; margin: 30px 0px 30px; color: #999999;} div.alert{color:#bd475d; background-color:transparent} Este documento se basa en “Happy Git with R” de Jenny Bryan, los STAT 545 TAs, Jim Hester https://happygitwithr.com 2.1 Diapositivas 2.2 ¿Por qué hacer control de versiones de nuestros proyectos? ✅ Los proyectos suelen cambiar y crecer. 💾 Es díficil saber cuáles fueron todos los cambios a lo largo del tiempo (en especial tiempos largos, hazlo por tu yo del futuro!). 🤔 Las colaboraciones se pueden complicar sin un buen control de versiones. 🔐 Seguridad. 2.3 Git Git es un sistema de control de versiones Git funciona con GitHub, Bitbucket o GitLab ¿Por qué usar Git en vez de solo renombrar los archivos? ✅✅Por qué es mejor tener una filogenia del archivo. Git es un sistema de control de versiones distribuido, gratuito y de código abierto, diseñado para manejar todo tipo de proyectos, desde los más pequeños hasta los más grandes, con rapidez y eficiencia. Git es fácil de aprender y ocupa poco espacio con un rendimiento rapidísimo. Supera a las herramientas SCM como Subversion, CVS, Perforce y ClearCase con características como la ramificación local barata, las cómodas áreas de preparación y los múltiples flujos de trabajo. 2.3.1 Git vs controles de versión a mano Con Git cada contribuidor tiene una copia del repositorio central, con todos los archivos y la historia de los cambios por los que han pasado. Excuse me, do you have a moment to talk about version control?, Jennifer Bryan, 2017 ⚠️ NO OLVIDES TENER INSTALADO Git, en caso de que aún no lo hayas instalado, lo puedes descargar en el siguiente enlace https://git-scm.com/downloads. Para conocer la localización y la versión de Git que tienes en tu computadora, corre el siguiente comando en la terminal: which git y git --version 2.4 Recomendaciones para sus proyectos Dedicar un directorio Es mejor organizarlo en un RStudio Project Hacer un repositorio de Git Trabajen como siempre, solo además de guardar, recuerden hacer commit De vez en vez hagan push de sus cambios cuando los hayan verificado. 2.5 Proyectos colaborativos GitHub se parece más a un GoogleDoc que a un Word Document. Es fácil que los colaboradores hagan cambios y también es fácil saber quién hizo que. El owner del proyecto puede dar permisos a los diferentes colaboradores. También existen organizaciones, esto puede ser útil para manejar los permisos de grupos grandes de colaboración. 2.6 GitHub GitHub es una plataforma para guardar proyectos, hace uso de Git. Su principal utilidad es para generar código fuente de programas. ⚠️ NO OLVIDES TENER UNA CUENTA EN GITHUB, en caso de que aún no lo hayas hecho, puedes ir la página de GitHub y seleccionar join. Es indispensable tu usuario para los ejercicios que siguen. También existen otras plataformas como Bitbucked y GitLab, las cuales funcionan de manera similar a GitHub. 2.7 Manual de sobreviviencia con Git Y GitHub en RStudio (en caso de ser necesario) Por cualquier problema con la conexión entre RStudio y Git, siempre ten en cuenta la ubicación de dónde se instaló Git. Puedes usar en la terminal which git (Mac y Linux) O bien usar en la terminal where git (Windows) Recuerda que la terminal (o línea de comandos ó consola ó shell ó bash) es un programa en tu computadora que funciona para correr otros programas. Desde RStudio puedes abrir la terminal, lo cual es muy conveniente si estás trabajando en un proyecto. Puedes abrir una terminal con: Tools > Terminal (abre la terminal dentro del IDE de RStudio) Tools > Shell (abre una terminal externa a RStudio) 2.8 Cómo clonar un repositorio y tener conección/permisos para modificarlo? Git puede comunicarse con un servidor remoto usando uno de dos protocolos, HTTPS o SSH, y cada protocolo usa credenciales diferentes. La recomendación actual de GitHub es usar HTTPS porque es la manera más fácil de configurar y tiene operabilidad en multiples redes y plataformas. Es menos probable que HTTPS sea bloqueado por un firewall. Una conexión HTTPS permite que credential.helper almacene en caché su contraseña. (por tanto puedes configurar tu usuario y contraseña en tu equipo de uso) Es más sencillo acceder a un repositorio desde cualquier lugar, ya que solo necesitas los detalles de tu cuenta (no se requieren claves SSH) para escribir en el repositorio. Usualmente cuando inicies un proyecto colaborativo con GitHub inicializa el ropositorio con un README. Copia el HTTPS URL para clonar el repositorio en la terminal git clone https://github.com/TU-USUARIO/TU-REPOSITORIO.git. 2.9 Credenciales HTTPS en Cache Para usar HTTPS debes crear un token de acceso personal, PAT (PERSONAL ACCESS TOKEN), esa será tu credencial para HTTPS. Es una alternativa al uso de contraseñas para la autenticación en GitHub. Como precaución de seguridad, GitHub elimina automáticamente los tokens de acceso personales que no se han usado durante un año. ¿Cómo crear un token? Ve a tu perfil de GitHub, dale click a la imagen de perfil (usualmente en la esquina superior derecha), y busca la opción de settings ó configuración según sea la configuración de idioma que tengas. Da click a continuación en Developer settings ó Parámetros del desarrollador. En la barra lateral izquierda da click en Tokens de acceso personal. Haz click en Generar un nuevo token. Asígna un nombre descriptivo a tu token. Selecciona los alcances o permisos que deseas otorgarle a este token. Para usar tu token para acceder a repositorios desde la línea de comando, selecciona repo. (Recomendados: repo, user, workflow ) Finalmente haz click en generar token. Listo, copia y pega tu token en el lugar dónde siempre lo puedas volver a copiar, ya que por razones de seguridad, una vez salgas de la página no podrás volver a ver el token. Nota: Preserva tus tokens de la misma manera que tus contraseñas y no se las reveles a nadie. Una vez que tengas un token, puedes ingresarlo en lugar de tu contraseña cuando realices operaciones de Git a través de HTTPS. El punto final es que una vez configurada una PAT, varios paquetes de R, incluidos usethis y gh, podrán trabajar con la API de GitHub en su nombre, de forma automática. Por lo tanto, una PAT configurada correctamente significa que todo esto funcionará a la perfección: - Operaciones HTTPS remotas a través de la línea de comando Git y, por lo tanto, a través de RStudio - Operaciones HTTPS remotas a través del paquete gert R y, por lo tanto, usethis - Operaciones de la API de GitHub a través del paquete gh R y, por lo tanto, usethis Probar el repositorio Clonado Después de hacer clone Usa estos comandos para verificar tu repositorio y revisar desde dónde se está sincorinzando. cd myrepo ls -la head README.md git remote show origin Probemos haciendo un cambio en el README echo "Something I want to add to the README in my local computer" >> README.md git status Qué pasó? Ahora tenemos que decirle a git que queremos seguir los cambios de ese archivo Vamos a commit los cambios y luego a subir (push) los mismos a GitHub git add README.md git commit -m "A commit from my local computer" git push Recuerda tu TOKEN!! ¿Cómo crear un token desde R? Puedes ir directamente a la página de GitHub a la parte para generar tu token de acceso personal mediante la siguiente función: usethis::create_github_token() Y con las opciones que se mencionaban anteriormente puedes configurar y crear tu PAT. Si lo que quieres es especificar tu PAT en RStudio, las siguientes funciones te serán útiles: library(gitcreds) gitcreds_set() library(credentials) set_github_pat() Para eliminar credenciales utiliza la función credentials::git_credential_forget() 2.9.1 Actividad Ejecuta los códigos y genera tu PAT, recuerda no perderlo! 2.10 Conectando RStudio con Git y Github. Para lo que sigue a continuación, deberías tener esto: Tener una cuenta en GitHub R y RStudio actualizados Git instalado Saber que desde la terminal puedes hacer push y pull 2.11 GitHub primero, RStudio después… Crea un repositorio en GitHub: mi_repositorio > Public > YES initialize this repository with a README > clicken el gran botón verde “Create repository” En RStudio crea un nuevo proyecto: File > New Project > Version Control > Git. Ahi pega el URL del repositorio https://github.com/mi_usuario/mi_repositorio.git. Da click en Create Project. Esto nos generará los siguientes elementos: Un directorio nuevo Un repositorio Git enlazado a al repositorio de GitHub Un proyecto en RStudio Con este procedimiento ya no es necesario preocuparse por configurar controles remotos Git y rastrear ramas en la línea de comandos. 2.11.1 Actividad Genera un repositorio con el nombre que desees. Y conéctalo a RStudio. Cerciorate de que el archivo README se encuentre en tu nueva carpeta. Usa la función usethis::use_r(\"titulo_de_un_script\") y observa lo que sucede. PAUSA ¿Cómo comento y doy push/pull desde RStudio? 2.11.2 Comentar, pull y push Con la flecha azul podemos hacer pull (RECUERDA HACERLO ANTES DE HACER UN PUSH), y con la flecha verde un push. Para poder comentar y hacer push debemos marcar con una flechita mediante un click en las pequeñas cajas blancas de la columna Staged, damoc click en commit lo cual no abre la siguiente ventana. Volvemos a dar click en commit, y finalizamos con push (flecha verde). 2.12 Rmarkdown en GitHub Creemos un Rmakrdown y subámoslo a GitHub Ahora hay que agregarlo al repositorio (add), stage and commit. Subieron el hmlt? Qué tal se ve? No se ve como queremos, verdad? Para eso necesitamos recuperar el .md. El .md es un resultado intermedio de crear el html desde Rmd. Tenemos que cambiar el header para esto --- title: "RmarkwondTest" output: html_document: keep_md: true --- 2.12.1 Actividad Usa el código dir.create(\"mis_imagenes\") en la consola de tu sesión de RStudio (la que está vinculada a tu repositorio). Ejecuta el siguiente código quitando los #: install.packages("MASS") library (MASS) data(MASS::cats) # pdf("mis_imagenes/cats_plot.pdf") ggplot(cats, aes(x = Sex)) + geom_bar(fill = "orange", color = "black") + theme_classic() + xlab("Sexo") + ylab("Número de Gatos") + ggtitle("Gatos") # dev.off() Comenta y da push a los cambios que realizaste en el repositorio. 2.13 RStudio primero y GitHub también Usa uno de los proyectos que hayas generado en las sesiones anteriores, PERO, que no esté enlazado a GitHub. Ahora veremos como conectar un proyecto de R existente con GitHub. Realiza los pasos que hicimos en GitHub primero, RStudio después pero asegurate de crear un repositorio con un nuevo nombre. Y LISTO!! usa un simple ctrl + c, ó mv ó click derecho + copiar ó el método que prefieras para mover o copiar archivos. Copia los archivos de tu antigüo proyecto al proyecto nuevo. Solo haz commit y push y listo, lo que tenía en tu antigüo proyecto ya está enlazado a GitHub. 2.14 Proyecto existente, GitHub al final Supongamos que tenemos un proyecto de R existente en algún lugar de nuestra computadora. NOTA: Para generar proyecto de RStudio desde la consola puedes utilizar el siguiente código: usethis::create_project() O en RStudio con File > New Project > Existing Directory Si su proyecto ya es un proyecto de RStudio, ejecútelo. ¿Ya es un repositorio de Git? La presencia del panel de Git debería alertarlo. Si es así, ha terminado. Sino este es el primer camino a seguir: Con el páquete usethis usa la función usethis::use_git En RStudio ve a Tools > Project Options > Git/SVN. Dentro de Version control system, selecciona Git. Y da click a “Yes” cuando aparezca “Confirm New Git Repository?”. Si usaste RStudio o usethis, el proyecto debería reiniciarse en RStudio. Hazlo tu mismo si hizo git init. RStudio ahora debería tener un panel Git. 2.14.1 Breviario cultural con los PATs Si usas el paquete usethis Y has configurado un token de acceso personal (PAT) de GitHub has esto en R: usethis::use_github() Esto creará un nuevo repositorio en GitHub, lo agregará como un control remoto, configurará una rama de seguimiento y lo abrirá en su navegador. Lea la ayuda de use_github() para conocer sus argumentos y consejos sobre cómo configurar una PAT. Esto es extremadamente útil para una variedad de flujos de trabajo que llaman a la API de GitHub. Considere configurar esto si usa usethis, devtools o gh con regularidad. Volviendo al tema de Proyecto existente, GitHub al final. Otra opción que se puede hacer para conectar un proyecto existen a GitHub es ir a hacer un repositorio a GitHub PERO ten en cuenta los siguientes cambios: Elije un nombre de repositorio; probablemente debería coincidir con el nombre de su proyecto y directorio local. NO inicialice este repositorio con un archivo README. Todo lo demás es igual a los pasos que hacíamos en GitHub primero, RStudio después… Ahora ve a tu proyecto de RStudio, has clic en los “dos cuadros de color púrpura y un cuadrado blanco” en el panel de Git. Has clic en “Agregar control remoto”. Pegue la URL aquí y elija un nombre remoto, casi con certeza el origin. Ahora “ADD”. Pasado esto deberiamos volver en el cuadro de diálogo “New Branch”. Ingresa “master” como el nombre de la rama y asegúrate de que la opción “Sync branch with remote” esté marcada. Haz clic en “Create”. En el siguiente cuadro de diálogo elije “overwrite”. Ahora solo haz commit/pull/push y cérciorate que FUNCIONE!! 2.15 Git basics: commands Fetch Commits git fetch Create and Switch to a branch git branch [branch-name] git checkout [branch-name] 2.16 Merge conflics A veces, no tan a veces también, las cosas no salen bien a la primera Merging (Fusionar) es una de esas cosas Cuando bajamos un cambio o fusionamos branches esto puede pasar. Primera regla: NO ENTRAR EN PANICO!!! Revisen el status del repositorio. Qué archivo tiene conflicto? 2.17 Merge conflics Abran ese archivo y busquen los problemas de merge. Es fácil, se ven así: <<<<<<< HEAD:index.html <div id="footer">contact : email.support@github.com</div> ======= <div id="footer"> please contact us at support@github.com </div> >>>>>>> issue-5:index.html Editen esa sección, dejen una versión final. Hagan commit y push Si entran en pánico? Aborten la misión! git merge --abort t 2.18 En resumen ¡QUE LA FUERZA TE ACOMPAÑE! "],["solución-de-problemas-con-las-versiones-de-paquetes-de-rstudio.html", "3 Solución de problemas con las versiones de paquetes de Rstudio 3.1 Diapositivas", " 3 Solución de problemas con las versiones de paquetes de Rstudio Yalbi Balderas 28 de octubre de 2024 3.1 Diapositivas "],["creando-la-infraestructura-de-un-paquete.html", "4 Creando la infraestructura de un paquete 4.1 Diapositivas 4.2 Los primeros pasos 4.3 Checks 4.4 Modificando el archivo DESCRIPTION 4.5 Modificando el archivo NEWS", " 4 Creando la infraestructura de un paquete Joselyn Cristina Chávez Fuentes 29 de octubre de 2024 4.1 Diapositivas 4.2 Los primeros pasos Revisar si podemos usar el nombre del paquete available::available("mipaquete") Crear la estructura inicial del paquete usethis::create_package("mipaquete") Podemos agregar la estructura de biocthis biocthis::use_bioc_pkg_templates() Pedir que Git ignore el archivo .Rproj usethis::use_git_ignore("*.Rproj") Crear el respositorio de GitHub usethis::use_github() Crear el archivo Description estilo Bioconductor biocthis::use_bioc_description() Crear el archivo README estilo Bioconductor biocthis::use_bioc_readme_rmd() devtools::build_readme() Recuerda guardar los cambios, hacer commit y push. Crear el archivo NEWS estilo Bioconductor biocthis::use_bioc_news_md() Crear los archivos de ayuda para usuarios y contribuidores biocthis::use_bioc_coc() usethis::use_tidy_contributing() biocthis::use_bioc_support() biocthis::use_bioc_issue_template() biocthis::use_bioc_citation() 4.3 Checks 4.3.1 BiocCheck BiocManager::install("BiocCheck") BiocCheck::BiocCheck() Algunas reglas de BiocCheck: Utilizar el símbolo <- en lugar de = para definir funciones y variables. Utilizar TRUE y FALSE en lugar de T y F. Indentar el código usando 4 espacios. Las líneas de código y documentación no deben ser mayores a 80 caracteres. Las funciones deben tener 50 líneas de código o menos. El paquete debe contener al menos una viñeta. Al menos 80% de las funciones deben tener ejemplos reproducibles. Las dependencias deben ser declaradas en el archivo DESCRIPTION. El paquete debe tener al menos un biocView. El tamaño del paquete no debe ser mayor 5Mb. El maintainer debe estar suscrito a la lista de correo de Bioconductor. El maintainer debe agregar su paquete en los tags de Bioconductor. 4.3.2 rcmdcheck install.packages("rcmdcheck") rcmdcheck::rcmdcheck() Algunas reglas de rcmdcheck: El paquete debe ser instalable. Los ejemplos de las funciones deben ser reproducibles. Las viñetas deben ser reproducibles. Todas las unidades de prueba deben pasar sin errores. El archivo DESCRIPTON debe tener el formato adecuado. 4.4 Modificando el archivo DESCRIPTION Paquete Este es el nombre del paquete. El nombre del repositorio y el nombre del paquete en la descripción deben coincidir (incluyendo mayúsculas y minúsculas). Título Este es un título breve pero descriptivo para el paquete. Versión Todos los paquetes de Bioconductor utilizan un esquema de versión x.y.z. Cuando se envía por primera vez a Bioconductor, un paquete debe tener la versión 0.99.0. Se aplican las siguientes reglas: x es normalmente 0 para paquetes que aún no han sido liberados. y es par para paquetes liberados, e impar para paquetes en desarrollo. Generalmente, no se debe aumentar este número en el pre-release. z se incrementa siempre que se realizan cambios en el paquete. Descripción La descripción debe ser una visión general relativamente breve pero detallada de lo que implica la funcionalidad del paquete. Debe ser de al menos tres oraciones completas. Autores Se requiere una designación de maintainer (cre) con una dirección de correo electrónico que se mantenga activamente. Esta dirección de correo se utilizará para el contacto con respecto a cualquier problema que surja con el paquete en el futuro. Idealmente, se debe incluir el ORCiD por lo menos del maintainer. person("Lori", "Shepherd", email = Lori.Shepherd@roswellpark.org, role = c("cre", "aut"), comment = c(ORCID = "0000-0002-5910-4010")) Sólo debe figurar una persona como responsable para garantizar un único punto de contacto. Esta persona tendrá acceso al repositorio git en git.bioconductor.org. El acceso a Commit puede ser dado a otros desarrolladores por solicitud en la lista de correo bioc-devel. Otra opción es añadir colaboradores al repositorio de GitHub. Este enfoque permite el desarrollo por muchos pero restringe el acceso a git.bioconductor.org. Licencia El campo de licencia debe referirse preferentemente a una licencia estándar no restrictiva. Las licencias que restringen el uso, por ejemplo, a investigadores académicos o sin fines de lucro, no son adecuadas para Bioconductor. Los paquetes de bioconductor básico suelen estar licenciados bajo Artistic-2.0. El paquete debe contener sólo código que pueda ser redistribuido de acuerdo con la licencia del paquete. LazyData Para paquetes que incluyen datos, se recomienda NO incluir LazyData: TRUE. Incluirlo en ese caso, ralentiza la carga de paquetes con datos grandes. Dependencias Todos los paquetes deben estar disponibles a través de biocViews o CRAN de Bioconductor; el uso del campo Remotes: no es soportado, por lo tanto las dependencias sólo disponibles en otros repositorios (e.g. GitHub) no están permitidas. Un paquete puede ser listado sólo una vez entre Depends, Imports, Suggests, o Enhances: Imports: es para paquetes que proporcionan funciones, métodos o clases que se usan dentro del código del paquete. La mayoría de los paquetes están listados aquí. Depends: es para paquetes que proporcionan funcionalidad esencial para los usuarios del paquete, por ejemplo, el paquete GenomicRanges se enumera en el campo Depends: de GenomicAlignments. Es poco común que más de tres paquetes aparezcan como Depends:. Suggests: es para paquetes usados en viñetas, ejemplos y código condicional. Comúnmente, los paquetes de anotaciones y experimentos (por ejemplo, TxDb*) usados en viñetas y código de ejemplo se incluyen en este campo, evitando así una descarga costosa. Enhances: es para paquetes como parallel que mejoran el rendimiento del paquete, pero no son estrictamente necesarios para su funcionalidad. En el caso de que se requiera una función única externa para el código del paquete, la disponibilidad y el uso del paquete pueden hacerse a través de: if (!requireNamespace('suggPKG', quietly = TRUE)) stop("Install 'suggPKG' to use this function.") suggPKG::function() biocViews Este campo es obligatorio! Especifica al menos dos biocViews. Los términos deben provenir del mismo tipo de paquete (Software, AnnotationData, ExperimentData o Workflow). Puedes encontrar más información en: https://www.bioconductor.org/packages/release/BiocViews.html BugReports Se recomienda apuntar hacia el repositorio de GitHub, por ejemplo: https://github.com/usuario/paquete/issues. URL Se incluyen los links importantes, como el repositorio con el código fuente y el sitio web de pkgdown si se cuenta con él. Por ejemplo: https://github.com/usuario/paquete https://usuario.github.io/paquete 4.5 Modificando el archivo NEWS Secciones: New: Nuevas funciones. Bug fixes: Reparación de errores en las funciones previas o en la documentación. Changes: Cambios en el código de las funciones, incluyendo modificaciones en los argumentos. Breaking changes: Cambios importantes que romperían el código en caso de no ser atendidos, por ejemplo el uso de funciones o argumentos antiguos. Enhancements: Mejoras a las funciones existentes. Formato El archivo NEWS se ve similar a este ejemplo: "],["creando-mis-primeras-funciones.html", "5 Creando mis primeras funciones 5.1 Diapositivas 5.2 Nombre de la función 5.3 Estructura de la función 5.4 ¡Tu turno! 5.5 Argumentos 5.6 ¡Tu turno! 5.7 Indentación 5.8 Uso de espacios 5.9 Comentarios 5.10 Mensajes para el usuario", " 5 Creando mis primeras funciones Instructora: Joselyn Chávez 29 de octubre de 2024 5.1 Diapositivas 5.2 Nombre de la función Cortos pero descriptivos Recomendable: Separar las palabras con _ Establecer una palabra en común al inicio para familias de funciones use_bioc_citation() # es mejor que citation() bioc_cit() usebioccitation() useBiocCitation() use.bioc.citation() 5.3 Estructura de la función Indentar las líneas de código. Agregar comentarios para separar/describir las secciones importantes. Usar la sintaxis paquete::funcion() cuando hacemos llamado a funciones de otros paquetes. usethis::use_r("subset_heatmap") Generemos el código de manera regular. Simulemos una matriz con diversas mediciones y grafiquemos los datos en un heatmap. mi_matriz <- matrix(rnorm(100), nrow = 10) rownames(mi_matriz) <- paste0("medicion_",letters[1:10]) colnames(mi_matriz) <- paste0("grupo_",letters[1:10]) library(ComplexHeatmap) Heatmap(mi_matriz, cluster_columns = FALSE, heatmap_legend_param = list(title = "valores")) Escribamos una función que permita seleccionar algunos grupos de interés y genere el heatmap. No la mejor opción: library(ComplexHeatmap) subset_heatmap <- function(x,mediciones=NULL,grupos=NULL) { x_subset <- x[mediciones,grupos] Heatmap(mi_matriz, cluster_columns=FALSE, heatmap_legend_param=list(title="valores")) } Un poco mejor: library(ComplexHeatmap) subset_heatmap <- function(x, mediciones = NULL, grupos = NULL) { x_subset <- x[mediciones,grupos] Heatmap(mi_matriz, cluster_columns = FALSE, heatmap_legend_param = list(title = "valores")) } Mucho mejor: subset_heatmap <- function(x, mediciones = NULL, grupos = NULL) { # subset matrix x_subset <- x[mediciones, grupos] # plot heatmap ComplexHeatmap::Heatmap( x_subset, cluster_columns = FALSE, heatmap_legend_param = list(title = "valores")) } Ejecutemos la función: subset_heatmap( mi_matriz, mediciones = c("medicion_a", "medicion_b", "medicion_c"), grupos = c("grupo_d","grupo_e","grupo_f")) 5.4 ¡Tu turno! Escribe una función que: Filtre la matriz y mantenga sólo los valores por encima de cierto valor. Genere el heatmap filtrado. Recuerda seguir las recomendaciones para escribir funciones. 5.5 Argumentos Los argumentos deben tener un nombre descriptivo y bien documentado. No la mejor opción: subset_heatmap <- function(x, m, g) { # subset matrix x_subset <- x[mediciones, grupos] } Una mejor opción: subset_heatmap <- function(x, mediciones, grupos) { # subset matrix x_subset <- x[mediciones, grupos] # plot heatmap ComplexHeatmap::Heatmap( x_subset, cluster_columns = FALSE, heatmap_legend_param = list(title = "valores")) } Los argumentos generalmente deben tener valores default. subset_heatmap <- function(x, mediciones = NULL, grupos = NULL, return_plot = TRUE) { # subset matrix x_subset <- x[mediciones, grupos] # plot heatmap ComplexHeatmap::Heatmap( x_subset, cluster_columns = FALSE, heatmap_legend_param = list(title = "valores")) } Evalúa la validez de los argumentos subset_heatmap <- function(x, mediciones = NULL, grupos = NULL, return_plot = TRUE) { stopifnot(is.matrix(x)) # subset matrix x_subset <- x[mediciones, grupos] # plot heatmap heatmap <- ComplexHeatmap::Heatmap( x_subset, cluster_columns = FALSE, heatmap_legend_param = list(title = "valores")) if(return_plot == TRUE) {return(heatmap)} } Este código no debe funcionar: subset_heatmap( as.data.frame(mi_matriz), mediciones = c("medicion_a", "medicion_b", "medicion_c"), grupos = c("grupo_d","grupo_e","grupo_f")) Nota: Usa las funciones is() para evaluar la clase de los objects, no uses class() == ni class() !=. Proporciona pistas para entender los errores. subset_heatmap <- function(x, mediciones = NULL, grupos = NULL, return_plot = TRUE) { if(!is.matrix(x)) {stop("x debe ser una matriz")} # subset matrix x_subset <- x[mediciones, grupos] # plot heatmap heatmap <- ComplexHeatmap::Heatmap( x_subset, cluster_columns = FALSE, heatmap_legend_param = list(title = "valores")) if(return_plot == TRUE) {return(heatmap)} } Este código debe dar un error, más un mensaje de ayuda. subset_heatmap( as.data.frame(mi_matriz), mediciones = c("medicion_a", "medicion_b", "medicion_c"), grupos = c("grupo_d","grupo_e","grupo_f")) 5.6 ¡Tu turno! Agrega pasos de evaluación para los otros argumentos de la función. Incluye mensajes de ayuda cuando el formato de los argumentos no es el esperado. 5.7 Indentación Usa 4 espacios para indentar, evita los tabs. No uses líneas de más de 80 caracteres. 5.8 Uso de espacios Usa un espacio después de la coma: a, b, c. Usa espacio después de operadores binarios: a == b. 5.9 Comentarios Usa “##” para comenzar las líneas de comentarios. Los comentarios deben usarse como notas y documentación solamente. No dejes código comentado que no se va a usar. Evita los TODO’s comentados cuando vayas a publicar el paquete. 5.10 Mensajes para el usuario Si deseas imprimir mensajes para el usuario, como el progreso del análisis en la función o advertir sobre los valores de los argumentos, evita el uso de cat(), mejor usa: message() comunica mensajes diagnóstico, como el progreso de la función. message("Paso 1: completo") ## Paso 1: completo warning() comunica situaciones inusuales que pueden ser manejadas por tu código. warning("El número de elementos esperados es mayor a uno, se tomará el primer valor del vector") ## Warning: El número de elementos esperados es mayor a uno, se tomará ## el primer valor del vector stop() indica una condición errónea. stop("x debe ser numérico") "],["documentación-de-funciones.html", "6 Documentación de funciones 6.1 Diapositivas 6.2 Links importantes: 6.3 ¿Qué es la documentación de una función y por qué es importante? 6.4 Generacion de la documentacion con ayuda del paquete roxygen 6.5 Antes de empezar…✏️ 6.6 Generacion de un bloque de documentacion con ayuda del paquete roxygen. 6.7 Otros campos de la documentacion.", " 6 Documentación de funciones Instructor/a: 29 de octubre de 2024 6.1 Diapositivas 6.2 Links importantes: Esta lección está basada en algunos manuales sobre documentación: Una viñeta del cranproject El manual de paqutes de r En esta viñeta de cranproject 6.3 ¿Qué es la documentación de una función y por qué es importante? 🙇️ Es la información complementaria que el desarrollador escribe sobre una función y que se accede con ? seguido el nombre de una función actual de un paquete p.ej. ?unafuncion. 📁 La documentación se almacena como un archivo .Rd (“R documentation) en la carpeta man/. 🔎 La documentación usa una síntesis especial, que es distinta a la de r y que está ligeramente basada en LaTeX. 📄 Se puede renderizar como html, pdf o texto sin formato según se necesite. 6.4 Generacion de la documentacion con ayuda del paquete roxygen En un paquete de r y en cualquier ecosistema de devtools no editamos un documento .Rd manualmente. La documentación usa una síntesis parecida a LaTex que puede ser fácil de estropear. Por ventaja existen paquetes como roxigen2. Usar roxigen nos permite usar comentarios especiales sobre el inicio de la función, esto nos da un par de ventajas: ✅ La documentación y la función estarán en un mismo lugar, por lo que si editas la función será mas fácil recordar actualizar la documentcion también. 🎉 Puedes usar markdown en lugar de la síntesis especial para los archivos .Rd 6.5 Antes de empezar…✏️ Vamos a crear un función para nuestro paquete. Supongamos que para nuestro paquete necesitamos una función que calcule la moda. Esta es una forma sencilla de calcular la moda: getmode <- function(serievector) { uniqv <- unique(serievector) uniqv[which.max(tabulate(match(serievector, uniqv)))] } unique(serievector): Crea un vector que contiene únicamente los valores únicos de la serie de números serievector. match(serievector, uniqv): Encuentra la posición de cada valor de serievector en el vector único uniqv. tabulate(match(serievector, uniqv)): Cuenta cuántas veces aparece cada valor en la serie serievector. which.max(tabulate(match(serievector, uniqv))): Encuentra el índice del valor máximo en el vector de frecuencias. uniqv[which.max(tabulate(match(serievector, uniqv)))]: Devuelve el valor correspondiente al índice calculado, que es la moda. Creamos un ejemplo para ver que funcione: serie_numeros <- c(1, 2, 2, 2, 2, 3, 3, 4, 4, 4) resultado <- getmode(serie_numeros) print(resultado) ## [1] 2 Bien ahora si podemos podemos empezar a usar el paquete de roxygen para documentar nuestra función.. comencemos. 6.6 Generacion de un bloque de documentacion con ayuda del paquete roxygen. Podemos insertar un esqueleto de comentarios de roxygen para ver su síntesis. Colocamos el cursor en algún lugar de la definición de nuestra función y buscamos en la pestaña Código > Insertar Roxygen Skeleton. #' Title #' #' @param serievector #' #' @return #' @export #' #' @examples getmode <- function(serievector) { uniqv <- unique(serievector) uniqv[which.max(tabulate(match(serievector, uniqv)))] } Ahora ya tenemos un esqueleto de la documentación que nos da una ventaja para su creación. Las líneas de comentarios de Roxygen siempre comienzan con #', el habitual para un comentario # mas un ' Veamos los comentarios de uno por uno: Empezamos con el titulo. Se sugiere poner en el titulo las acciones principales que realiza la función en este caso por ejemplo podremos usar: #' @title Encontrar la Moda de una Serie de Números #' #' @param serievector #' #' @return #' @export #' #' @examples getmode <- function(serievector) { uniqv <- unique(serievector) uniqv[which.max(tabulate(match(serievector, uniqv)))] } Muy bien!. El siguiente comentario que podemos ver es @param. Pero antes, vamos a añadir una pequeña descripción de la función y como usarla. Primero añadimos la pequeña descripción con @description: #' @title Encontrar la Moda de una Serie de Números #' #' @description Esta función lee una serie de números en forma de vector y #' encuentra el elemento que mas se repite, es decir la moda. #' @param serievector #' #' @return #' @export #' #' @examples getmode <- function(serievector) { uniqv <- unique(serievector) uniqv[which.max(tabulate(match(serievector, uniqv)))] } Ahora vamos a añadir el comentario @usage que nos indica como puedes mandar a llamar la función. #' @title Encontrar la Moda de una Serie de Números #' #' @description Esta función lee una serie de números en forma de vector y #' encuentra el elemento que mas se repite, es decir la moda. #' @usage getmode(serievector) #' @param serievector #' #' @return #' @export #' #' @examples getmode <- function(serievector) { uniqv <- unique(serievector) uniqv[which.max(tabulate(match(serievector, uniqv)))] } Ahora si vamos a añadir una pequeña descripción de nuestros argumentos. Si tuviéramos mas de un parámetro en nuestra función podríamos llamar las veces que sea necesario el comentario de parámetro con @param, veamoslo. Ahora añadimos una pequeña descripción a nuestro único parámetro que es serievector: #' @title Encontrar la Moda de una Serie de Números #' #' @description Esta función lee una serie de números en forma de vector y #' encuentra el elemento que mas se repite, es decir la moda. #' #' @param serievector Es una serie de números en forma de un vector simple de r. #' #' @return #' @export #' #' @examples getmode <- function(serievector) { uniqv <- unique(serievector) uniqv[which.max(tabulate(match(serievector, uniqv)))] } Después, podemos añadir un comentario de detalles de la función con @details. Por ejemplo, si en nuestro ejemplo tuviéramos ciertos valores no numéricos en nuestro vector de entrada, por ejemplo letras, ¿nuestra función podría leerlas?, o si le diéramos un vector sin caracteres ¿que pasaría?, veamos: serie_numeros <- c(0,2,2,"d", "d","d") resultado <- getmode(serie_numeros) print(resultado) ## [1] "d" serie_numeros <- c() resultado <- getmode(serie_numeros) print(resultado) ## NULL Entonces, esto es un ejemplo de lo que podríamos poner en el comentario @details. Hagamoslo describiendo esto. En details podemos agregar detalles un poco mas específicos que en la descripción de la función #' @title Encontrar la Moda de una Serie de Números #' #' @description Esta función lee una serie de números en forma de vector y #' encuentra el elemento que mas se repite, es decir la moda. #' #' @param serievector Es una serie de números en forma de un vector simple de r. #' #' @details si tu vector de entrada puede ser interpretado alternando números y #' letras escritas entre comillas "". Si un vector esta vacío, dará como #' resultado un NULL. #' @return #' @export #' #' @examples getmode <- function(serievector) { uniqv <- unique(serievector) uniqv[which.max(tabulate(match(serievector, uniqv)))] } Ya casi terminamos de llenar nuestra documentación, pero antes vamos a ver algunos otros arrobas que pudieran ser importantes. El @import e @importfrom importan funciones de otros paquetes en caso de que las necesitemos, el primero importa todas las funciones del paquete que que solicites, y el segundo importa solo algunas funciones especificas. En nuestra función no necesitamos llamar funciones de otros paquetes puesto que todas las que usamos están en r base. Pero imaginemos que tu función, por ejemplo necesita leer un archivo .tsv con la función read_tsv del paquete readr y después reconvertir la tabla resultante en un archivo con write.table pero solo necesitas esa función del paquete utils, entonces haríamos: #' @title Encontrar la Moda de una Serie de Números #' #' @description Esta función lee una serie de números en forma de vector y #' encuentra el elemento que mas se repite, es decir la moda. #' #' @param serievector Es una serie de números en forma de un vector simple de r. #' #' @details si tu vector de entrada puede ser interpretado alternando números y #' letras escritas entre comillas "". Si un vector esta vacío, dará como #' resultado un NULL. #' @import readr #' @importFrom utils write.table #' @return #' @export #' #' @examples getmode <- function(serievector) { uniqv <- unique(serievector) uniqv[which.max(tabulate(match(serievector, uniqv)))] } Así podemos importar las funciones que necesitemos de otros paquetes y se incluirán en la documentación y se cargaran automáticamente al cargar tu paquete. :eyes::exclamation: Para un correcto funcionamiento de tu paquete y al estar los paquetes necesarios incluidos en la documentación, no será necesario llamarlos de la forma ``library(“apackage”)```. Entonces llegamos a la sección @return. Esta descripción le servirá al usuario del paquete para conocer cual sera el resultado de la función, que puede ser un archivo, una tabla, un numero,etc. Entonces retomando la función que usamos al inicio, vamos a escribir una descripción corta del resultado de la función getmode(). #' @title Encontrar la Moda de una Serie de Números #' #' @description Esta función lee una serie de números en forma de vector y #' encuentra el elemento que mas se repite, es decir la moda. #' #' @param serievector Es una serie de números en forma de un vector simple de r. #' #' @details si tu vector de entrada puede ser interpretado alternando números y #' letras escritas entre comillas "". Si un vector esta vacío, dará como #' resultado un NULL. #' @return El carácter con mas frecuencia de el vector de entrada. #' @export #' #' @examples getmode <- function(serievector) { uniqv <- unique(serievector) uniqv[which.max(tabulate(match(serievector, uniqv)))] } Por ultimo tenemos @export que es el encargado de renderizar la documentación para que pueda aparecer en la ventana de Ayuda (abajo a la derecha). esta opción la dejamos para funciones principales que el usuario va a utilizar, aunque puede que existan alguna funciones internas que no queremos que el usuario vea. En ese caso vamos a usar @noRd en lugar de este. Antes de terminar podemos incluir ejemplos de como funciona nuestra función para un mejor entendimiento, pongamos los que ya realizamos: #' @title Encontrar la Moda de una Serie de Números #' #' @description Esta función lee una serie de números en forma de vector y #' encuentra el elemento que mas se repite, es decir la moda. #' #' @param serievector Es una serie de números en forma de un vector simple de r. #' #' @details si tu vector de entrada puede ser interpretado alternando números y #' letras escritas entre comillas "". Si un vector esta vacío, dará como #' resultado un NULL. #' @return El carácter con mas frecuencia de el vector de entrada. #' @export #' #' @examples #' serie_números <- c(1, 2, 2, 2, 2, 3, 3, 4, 4, 4) #' resultado <- getmode(serie_números) #' print(resultado) getmode <- function(serievector) { uniqv <- unique(serievector) uniqv[which.max(tabulate(match(serievector, uniqv)))] } Ahora si, una vez teniendo listo el bloque de comentarios para la documentación, vamos a ejecutar devtools::load_all() para cargar nuestras funciones y hecho esto, ejecutamos devtools::document() o presionamos Ctrl/Cmd + Shift + D para convertir los comentarios en archivo .Rd y poder renderizarlo. 💯 Listo, tenemos nuestra documentación para una función. Así se verá cuando el paquete esté terminado. 6.7 Otros campos de la documentacion. @seealso para indicar funciones relacionadas y facilitar la búsqueda de funciones. @references añade algunas referencias. @author para especificar el autor de la función. "],["diseño-de-pruebas.html", "7 Diseño de pruebas 7.1 Diapositivas", " 7 Diseño de pruebas Mirna Vázquez Rosas-Landa 30 de octubre de 2024 7.1 Diapositivas "],["creación-de-viñetas.html", "8 Creación de viñetas 8.1 ¿Qué es una viñeta/vignette? 📝✨ 8.2 Características de una vignette 🌟 8.3 ¿Cómo consultar la viñeta de un paquete? ❓🔍 8.4 ¿Cómo crear una viñeta? ❓🔍 8.5 ¿Cómo guardar y actualizar la viñeta? 🔄💻 8.6 Veamos un ejemplo 🔍👨💻 8.7 Actividad", " 8 Creación de viñetas José Antonio Ovando Ricárdez 30 de octubre de 2024 8.1 ¿Qué es una viñeta/vignette? 📝✨ Es una guía extendida sobre cómo funciona el paquete. Es recomendable que muestre cómo utilizar las funciones del paquete, aplicado en un flujo de trabajo; por ejemplo: el análisis estadístico de una encuesta 📊 o el análisis de expresión diferencial de genes. Podemos estructurarlo como haríamos con la escritura de un capítulo de libro o de un artículo científico: debe mostrar el problema a resolver y la metodología paso a paso sobre cómo el paquete lo resuelve. Si el paquete contiene funciones que se complementan entre sí para alcanzar un fin específico, entonces debes mostrar su uso de forma compartamentalizada. 8.2 Características de una vignette 🌟 Debe mostrar un flujo de análisis explotando el potencial de tu paquete 📊🚀. Implementa tantas funciones de tu paquete como sea posible, pero no es necesario que incluya todas 🛠️✨. Los datos a usar deben ser pequeños o fáciles de acceder 📂🔍. Puedes crear múltiples viñetas para mostrar diferentes casos de análisis y cubrir una mayor cantidad de funciones 📝📚. 8.3 ¿Cómo consultar la viñeta de un paquete? ❓🔍 browseVignettes(package = "ggplot2") 8.4 ¿Cómo crear una viñeta? ❓🔍 biocthis::use_bioc_vignette("mi_vignette") Esta función tendrá tres efectos ✨: Generar el directorio vignettes en caso que no exista 📂🔧. Agregar dependencias en el archivo DESCRIPTION (por ejemplo, knitr necesario para construir viñetas dentro del paquete) 📄📦. Abrir un template en formato .Rmd para comenzar a escribir la viñeta, que se va a guardar en vignettes/mi_vignette.Rmd 📝💾. 8.5 ¿Cómo guardar y actualizar la viñeta? 🔄💻 Una vez que se ha generado el archivo vignettes/mi_vignette.Rmd, se hacen las modificaciones necesarias. Puedes usar el comando: edit_file("vignettes/mi_vignette.Rmd") Para guardar los cambios, debes hacer clic en el botón Knit o utiliza la combinación de teclas Ctrl/Cmd-Shift-K 💾✨. 8.6 Veamos un ejemplo 🔍👨💻 Busca la viñeta del paquete regutools en la página de Bioconductor 🌐: Viñeta de regutools en Bioconductor 📦📄 8.7 Actividad 8.7.1 Ejercicio 1: Identificación de viñetas en paquetes de interés en Bioconductor 📚🔍 En equipos selecciona dos paquetes almacenados en Bioconductor que sean de tu interés y responde las siguientes preguntas: ¿Ambos paquetes incluyen viñetas? 📝❓ ¿Qué aspectos de la viñeta del paquete A versus el paquete B te llaman más la atención? 🔍🤔 ¿Consideras que alguna viñeta está mejor desarrollada que la otra? Explica por qué 💭📊. 8.7.2 Ejercicio 2: Creación de viñetas en R 🛠️📄 Pasos: 1. Cargar los paquetes necesarios library(usethis) library(biocthis) Crear un nuevo paquete de R (si no tienes uno ya creado) # usethis::create_package("CDSB2024") Configurar el paquete para Bioconductor Ejecuta el siguiente comando para configurar el paquete con las mejores prácticas de Bioconductor: # biocthis::use_bioc_pkg_templates() Esto agregará varios archivos de configuración y plantillas útiles para trabajar con Bioconductor. Crear una viñeta con biocthis Ejecuta el siguiente comando para agregar una viñeta en formato R Markdown. Cambia “mi_vignette” por el título de la viñeta que prefieran. # usethis::use_vignette("mi_vignette_usethis") # biocthis::use_bioc_vignette("mi_vignette_biocthis") Esto creará un archivo R Markdown en la carpeta vignettes/ dentro del paquete. Editar la viñeta Abre el archivo creado en vignettes .Rmd. Incluye contenido que describa una función del paquete. Abrir la viñeta en el navegador y renderiza el archivo .Rmd # browseVignettes("CDSB2024") 8.7.3 Preguntas de Reflexión 🤔💭 ¿Cuál es la ventaja de documentar ejemplos de uso en una viñeta? 📚✨ ¿Qué estructura consideras útil para presentar ejemplos en una viñeta? 🏗️🔍 ¿Cómo aplicarías esta clase en tu proyecto colaborativo? 🤝📈 "],["compilación-e-instalación-de-paquetes.html", "9 Compilación e instalación de paquetes 9.1 Diapositivas 9.2 Metadatos de una paquetería 9.3 Licencias 9.4 Paqueterías de código fuente 9.5 ¿En dónde podemos encontrar el código fuente de un paquete? 9.6 Instalando la última versión en desarrollo 9.7 Instalando paquetes desde GitHub 9.8 Instalando un paquete local 9.9 Contribuyendo código", " 9 Compilación e instalación de paquetes Joselyn Cristina Chávez Fuentes 30 de octubre de 2024 9.1 Diapositivas 9.2 Metadatos de una paquetería Los metadatos de la paquetería se encuentran en el archivo DESCRIPTION. 9.2.1 Description El campo Description describe lo que hace tu paquetería. Suele ser extenso, si requieres escribir múltiples líneas, deben estar indentadas. Por ejemplo: # Description: Este paquete contiene todas las funciones generadas en el curso # de escritura de paqueterías en R. También contiene las funciones que cada # participante propuso para solucionar un problema relacionado con su trabajo. 9.2.2 Dependencias Las dependencias son las paqueterías que tu paquete necesita para funcionar. La lista de paquetes se escribe separada por comas y es recomendado que se escriban en orden alfabético. Existen tres tipos: Imports: Son paquetes que deben instalarse para que tu paquete funcione y por tanto se van a instalar en el momento que instales el paquete. Internamente existe una función que evalúa si los paquetes se encuentran instalados o no y solamente instala los faltantes. Esta dependencia hace solamente la instalación pero no ejecuta library(), por lo que los paquetes requeridos deberán ser cargados dentro de la escritura del paquete. Depends: Son paquetes que obligatoriamente deben estar para que tu paquetería funcione pero no se instalarán de manera automática. Aquí también se indica la versión de R requerida para el funcionamiento del paquete. Los paquetes que se listen aquí se van a cargar al mismo tiempo que se ejecute el library(mipaquete). Suggests: Se refiere a los paquetes que tu paquete puede utilizar y aprovechar para ser más poderoso en el análsis pero no los necesita para funcionar. Por ejemplo, paquetes que contienen sets de datos para hacer pruebas o análisis de práctica. Nota Importante Se recomienda listar los paquetes necesarios para el funcionamiento de nuestro paquete en Imports porque cuando se ponen en Depends se cargan los paquetes completos y probablemente solamente requerimos una o dos funciones. Cargar demasiados paquetes completos, sin ser necesario, sólo hace que nuestro paquete se vuelva pesado y lento. Es mejor llamar particularmente a las funciones usando la sintaxis explícita: Biostrings::translate() 9.2.3 ¿Cómo añadir dependencias? Usando usethis: usethis::use_package("ggplot2", type = "Imports") Editando manualmente el archivo DESCRIPTION. 9.3 Licencias Establece quién puede usar tu paquete. Existen diversas licencias pero hablaremos sobre las 3 más comunes: MIT (Massachusetts Institute of Technology): es simple y permisiva. Permite a cualquier persona usar y distribuir tu paquetería con una sola restricción: la distribución debe incluir la declaración de licencia del autor. Existe un texto base al cual se le pueden añadir cláusulas o excepciones. Este es un ejemplo: GPL-2 (General Public License): Permite usar y distribuir tu código con la condición que si se genera una versión modificada de tu código, su distribución debe ser también bajo esta licencia. Aunque está enfocada a la distribución de código abierto, permite dejar en claro quién es el autor del material y evitar la apropiación del código por terceros. Un ejemplo de la aplicación de esta licencia es el desarrollo de Linux. CCO: Esta licencia implica que cedes todos los derechos y el código puede ser utilizado con cualquier fin, excepto fines comerciales. Es el más utilizado en los paquetes. Concede el derecho a utilizar y distribuir el material sin requerir el permiso del autor. 9.4 Paqueterías de código fuente En algunas ocasiones necesitaremos instalar paquetes que no se encuentran compilados, por ejemplo: Paquetes en desarrollo de CRAN o Bioconductor. Versiones anteriores de paquetes de CRAN o Bioconductor. Paquetes que no se encuentran depositados en CRAN o Bioconductor, sino en repositorios personales como GitHub. Paquetes que estás desarrollando de forma local. El paquete remotes será de gran utilidad. Regularmente, los paquetes que instalamos desde algún repositorio como CRAN o Bioconductor son paquetes binarios que ya se encuentran compilados previamente. Existen algunas funciones que nos permiten instalar paquetes desde código fuente. Anteriormente, se solían utilizar las funciones install_* del paquete devtools; sin embargo, recientemente se creó el paquete remotes que contiene las mismas funciones pero está específicamente diseñado para ayudarnos a trabajar con paquetes desde código fuente. 9.5 ¿En dónde podemos encontrar el código fuente de un paquete? Si el paquete se encuentra disponible en CRAN, puedes encontrar el link al código fuente en la sección URL. Si el paquete se encuentra disponible en Bioconductor, puedes encontrar el link al código fuente en la sección Package Archives Si el paquete se encuentra en GitHub o GitLab, necesitarás conocer el nombre de usuario y el nombre del paquete. 9.6 Instalando la última versión en desarrollo Si el paquete se encuentra depositado en CRAN podemos usar la función remotes::install_dev("pkgname") Por ejemplo, para instalar la versión en desarrollo de dplyr usaremos el comando remotes::install_dev("dplyr") Si el paquete se encuentra en Bioconductor usaremos la siguiente función: remotes::install_bioc("pkgname") Por ejemplo, para instalar la versión en desarrollo de regutools, el paquete desarrollado por miembros de la CDSB, usaremos el comando remotes::install_bioc("regutools") 9.7 Instalando paquetes desde GitHub Para poder instalar un paquete desde GitHub necesitaremos conocer el usuario del creador y el nombre del repositorio. remotes::install_github("usuario/repositorio") Por ejemplo, para instalar el paquete starwarssay desarrollado por Erick Cuevas (Erickcufe) utilizaremos el siguiente comando: remotes::install_github("Erickcufe/starwarssay") Independientemente de si el paquete se encuentra en CRAN, Bioconductor, o ninguno de ellos, podemos instalar un paquete depositado en una cuenta de GitHub. Para poder instalar un paquete desde GitHub necesitaremos conocer el usuario del creador y el nombre del repositorio donde se encuentra depositado el paquete. Con esta información usaremos la siguiente función: 9.8 Instalando un paquete local Paso 1: Abre el proyecto del paquete que estás desarrollando. Paso opcional: Ejecuta la documentación si realizaste algún cambio. devtools::document() Paso 2: Construye el paquete: devtools::build() Paso 3: Instala el paquete desde tu proyecto actual: devtools::install() 9.9 Contribuyendo código Una ventaja de descargar el paquete de forma local es que puedes realizar cambios, probar que funciona de manera local y después contribuir (haciendo un pull-request). Usemos el paquete saludo Clona el repositorio en tu computadora. git clone https://github.com/ComunidadBioInfo/saludo.git Ahora puedes abrir el proyecto del paquete y agregar tu código. "],["creación-de-sitios-web-con-pkgdown.html", "10 Creación de sitios web con pkgdown 10.1 Diapositivas 10.2 Instalación 10.3 Configura el paquete para crear el sitio con pkgdown 10.4 Genera la estructura de pkgdown 10.5 Pre-visualiza el sitio de manera local 10.6 Personalizando el _pkgdown.yml 10.7 Las variables bslib 10.8 Layout 10.9 Accessibilidad 10.10 La página de inicio 10.11 La página de referencias 10.12 Articles 10.13 News 10.14 Publicando el sitio web", " 10 Creación de sitios web con pkgdown Joselyn Cristina Chávez Fuentes 31 de octubre de 2024 10.1 Diapositivas div.grey { background-color: #bfbfbf; } div.center { text-align:center; } 10.2 Instalación install.packages("pkgdown") 10.3 Configura el paquete para crear el sitio con pkgdown Este paso se ejecuta solamente una vez, dentro del proyecto del paquete. usethis::use_pkgdown_github_pages() Este paso genera las acciones automáticas de GitHub para renderizar el sitio. El archivo README.md será tu página de inicio, la documentación en man/ va a crear una sección de referencias, y las viñetas serán renderizadas como articles. 10.4 Genera la estructura de pkgdown Este paso se ejecuta solamente una vez. usethis::use_pkgdown() 10.5 Pre-visualiza el sitio de manera local Este paso lo puedes ejecutar para visualizar el sitio cada vez que hagas una modificación, antes de enviar los cambios a GitHub. pkgdown::build_site() 10.6 Personalizando el _pkgdown.yml 10.6.1 Metadatos URL Este es el link donde se va a renderizar el sitio, revisa que sea correcto y, de ser necesario, actualízalo. url: https://pkgdown.r-lib.org template Esta sección permite personalizar la apariencia general del sitio. template: bootstrap: 5 bootswatch: cerulean 10.6.2 Temas Light switch Puedes proporcionar un “light switch” para permitir a tus usuarios cambiar entre temas oscuros y claros configurando la opción de light-switch a true: template: light-switch: true Bootswatch themes La forma más fácil de cambiar toda la apariencia de tu sitio web es usar un tema de Bootswatch: template: bootstrap: 5 bootswatch: materia Puedes ver los temas disponibles en https://bootswatch.com/ Estos temas suelen no ser compatibles con el light switch, pero puedes intentar. Al cambiar el bootswatch theme necesitas renderizar el sitio para ver por completo los efectos del tema. build_site() Mientras estás experimentando, puedes acelerar las cosas simplemente reconstruyendo la página de inicio y el CSS ejecutando: build_home_index() init_site() y luego actualizando el navegador. Los bootswatch theme con barras de navegación altas (lux, pulse) también requieren que se modifique la variable pkgdown-nav-height. Debido a que los temas de bootswatch son proporcionados por el paquete bslib, se puede anidar el campo bootswatch debajo del campo bslib. template: bootstrap: 5 bslib: bootswatch: lux pkgdown-nav-height: 100px 10.7 Las variables bslib Hay tres variables clave que afectan al color: bg (fondo) determina el fondo de la página. fg (primer plano) determina el color del texto. primary establece el color del enlace y el color translúcido en la barra de navegación y la barra lateral. template: bootstrap: 5 bslib: bg: "#202123" fg: "#B8BCC2" primary: "#306cc9" También se pueden personalizar las fuentes predeterminadas utilizadas para la mayoría del texto (base_font), para los encabezados (heading_font) y para el código (code_font). La forma más fácil es proporcionar el nombre de una fuente de Google con la siguiente sintaxis: template: bootstrap: 5 bslib: base_font: {google: "Roboto"} heading_font: {google: "Roboto Slab"} code_font: {google: "JetBrains Mono"} 10.7.1 Syntax highlighting Los colores utilizados para el resaltado de sintaxis en bloques de código están controlados por la configuración theme: template: bootstrap: 5 theme: breeze-light Puedes elegir entre: a11y-dark, a11y-light, arrow-dark, arrow-light, atom-one-dark, atom-one-light, ayu-dark, ayu-light, ayu-mirage, breeze-dark, breeze-light, breezedark, dracula, espresso, github-dark, github-light, gruvbox-dark, gruvbox-light, haddock, kate, monochrome-dark, monochrome-light, monochrome, monokai, nord, oblivion, printing, pygments, radical, solarized-dark, solarized-light, solarized, tango, vim-dark, zenburn. 10.7.2 Navbar style Los campos bg y type de la barra de navegación controlan los colores del fondo y el primer plano respectivamente. Normalmente bg será light, dark, o primary: navbar: bg: primary 10.8 Layout Puedes personalizar el contenido de la barra de navegación, pie de página, utilizando los campos navbar y footer. Todos ellos utilizan una estructura similar que define por separado la estructura global y los componentes individuales. 10.8.1 Navbar Esta es la estructura default: navbar: structure: left: [intro, reference, articles, tutorials, news] right: [search, github, lightswitch] intro: “Get Started”, enlaza a una viñeta o artículo con el mismo nombre que el paquete. reference: si hay archivos . Rd. articles: si hay viñetas o artículos. tutorials: si hay algún tutorial. news: si existe NEWS.md. search: la barra de búsqueda. github: un enlace al repositorio de origen (con un icono), es determinado automáticamente a partir del archivo DESCRIPTION. lightswitch; un “interruptor de luz” para seleccionar el modo claro, modo oscuro o modo automático. Puedes utilizar el campo structure para reorganizar la barra de navegación: navbar: structure: left: [search] right: [reference, articles] Puedes usar la misma sintaxis para organizar el menú de artículos: navbar: components: articles: text: Articles menu: - text: Category A - text: Title A1 href: articles/a1.html - text: Title A2 href: articles/a2.html - text: ------- - text: "Category B" - text: Article B1 href: articles/b1.html 10.8.2 Footer Esta es la estructura por defecto:: footer: structure: left: developed_by right: built_with Que utiliza dos de los tres componentes incorporados: developed_by: una frase que describe a los principales autores del paquete. built_with: una frase que hace publicidad de la misma. package: el nombre del paquete. Puedes personalizar la organización del pie de página: footer: structure: left: pkgdown right: [developed_by, legal] components: legal: Provided without **any warranty**. 10.9 Accessibilidad Las configuraciones default de pkgdown tratan de hacer el sitio lo más accesible posible para todos, pero hay algunos puntos a tomar en cuenta: 10.9.1 Colores Si ajustas cualquier color del tema default, verifica que el contraste entre el fondo y el primer plano no haga difícil leer ningún texto. Puedes utilizar la herramienta de evaluación de accessibilidad en https://wave.webaim.org. El color default genera un contraste demasiado bajo contra el fondo gris pálido de la barra de navegación. Este color viene de la paleta “danger” de bootstrap, así que puedes arreglarlo sobreescribiendo esa variable en tu _pkgdown.yml: template: bootstrap: 5 bslib: danger: "#A6081A" Si utilizas entradas de barra de navegación personalizadas que sólo muestran un icono, asegúrate de utilizar también el campo aria-label para proporcionar una etiqueta accesible que describa el icono. cran: icon: fab fa-r-project href: https://cloud.r-project.org/package=pkgdown aria-label: View on CRAN 10.9.2 Imágenes Para hacer tu sitio completamente accessible, agrega una descripción del contenido de las imágenes en las viñetas usando el campo “fig.alt” de las opciones del chunk de R. 10.10 La página de inicio Los contenidos del home page son automáticamente generados desde el archivo index.md o el README.md. pkgdown les asigna diferentes prioridades, por lo que es possible tener contenidos diferentes en el repositorio de GitHub y la página de pkgdown si provees ambos archivos. La página de inicio también incluye una barra de contenidos con links importantes, como la guía de contribución, el código de conducta, etc. 10.11 La página de referencias pkgdown crea una página de referencia en reference/ para cada una de las funciones del paquete, basado en la documentación. pkgdown ejecuta todos los ejemplos de las funciones, insertando los resultados renderizados en los archivos HTML generados. Por defecto, pkgdown genera un índice de referencia que es sólo una lista de funciones ordenadas alfabéticamente. El índice es mucho más útil con la curación manual porque las funciones pueden agruparse y describirse en categorías. Cada entrada de referencia puede adoptar una de las tres formas siguientes: Un título, definido por los campos title y desc (descripción) opcionales. Un subtítulo, definido por los campos de subtítulo y desc (descripción) opcionales. Lista de temas definidos por un campo de contenido. Mientras editas el índice de referencias, puedes ejecuar la siguiente función para renderizar solamente el índice, lo que permite ver de forma rápida el efecto de los cambios sin tener que renderizar todo el sitio. pkgdown::build_reference_index() reference: - title: "Connecting to Spark" desc: > Functions for installing Spark components and managing connections to Spark contents: - spark_config - spark_connect - spark_disconnect - spark_install - spark_log 10.12 Articles pkgdown creará automáticamente todas las viñetas que se encuentran en la carpeta vignettes/, traduciéndolas a archivos HTML en articles/. Se puede nombrar el artículo de introducción con el nombre del paquete para generar una página “Get Started” automáticamente. 10.13 News Si el archivo NEWS.md está presente, se procesará en un changelog de una sola página basado en los títulos de las secciones del archivo. pkgdown asume que el archivo NEWS.md está formateado con encabezados de nivel uno (#) para especificar el nombre del paquete y el número de versión, y con encabezados de nivel dos (##) para proporcionar una organización temática para cada versión. # pkgdown 1.1.0 ## Bug Fixes * Lots of them 10.14 Publicando el sitio web Haz commit de los cambios y luego push. Ve al repositorio del paquete en GitHub y espera a que la acción de GitHub termine de renderizar el sitio. Ve al sitio web, el formato debe ser similar a https://usuario.github.io/paquete "],["proyectos-colaborativos-1.html", "11 Proyectos colaborativos 11.1 Propuesta 1 11.2 Propuesta 2 11.3 Propuesta 3 11.4 Propuesta 4 11.5 Propuesta 5", " 11 Proyectos colaborativos 11.1 Propuesta 1 11.2 Propuesta 2 11.3 Propuesta 3 11.4 Propuesta 4 11.5 Propuesta 5 "],["404.html", "Page not found", " Page not found The page you requested cannot be found (perhaps it was moved or renamed). You may want to try searching to find the page's new location, or use the table of contents to find the page you are looking for. "]]