diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..5b6a065 --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +.Rproj.user +.Rhistory +.RData +.Ruserdata diff --git a/01_sesion1.Rmd b/01_sesion1.Rmd index a799001..5506de8 100644 --- a/01_sesion1.Rmd +++ b/01_sesion1.Rmd @@ -1,4 +1,4 @@ -# Introducción al flujo de trabajo orientado a proyectos +# Trabajando con proyectos de RStudio Joselyn Cristina Chávez Fuentes diff --git a/01_sesion2.Rmd b/01_sesion2.Rmd index cfcfc5c..0e8a655 100644 --- a/01_sesion2.Rmd +++ b/01_sesion2.Rmd @@ -1,8 +1,465 @@ -# Paths seguros +# Control de versiones con GitHub y RStudio -Instructor/a: +Dra. Alejandra Medina Rivera 28 de octubre de 2024 + + + +- Este documento se basa en "Happy Git with R" de Jenny Bryan, los STAT 545 TAs, Jim Hester + + +https://happygitwithr.com + ## Diapositivas +[ +```{r,echo=FALSE} +knitr::include_url("https://amedina-liigh.github.io/GitHubIntroSlides/GitHubIntro.html", height = "380px") +``` +](https://amedina-liigh.github.io/GitHubIntroSlides/GitHubIntro.html) + +## ¿Por qué hacer control de versiones de nuestros proyectos? + +1. ✅ Los proyectos suelen cambiar y crecer. +2. 💾 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!**). +3. 🤔 Las colaboraciones se pueden complicar sin un buen control de versiones. +4. 🔐 Seguridad. + +```{r,echo=FALSE, fig.align='center'} +knitr::include_graphics("img/git_why.png") +``` + +## 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. + +### **Git vs controles de versión a mano** + +```{r,echo=FALSE, fig.align='center'} +knitr::include_graphics("img/git_vers.png") +``` + +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](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` + + +
+ +## 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**. + +## 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. + +## GitHub + +[GitHub](https://github.com/about) 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](https://github.com) y seleccionar `join`. +Es indispensable tu usuario para los ejercicios que siguen. +
+ +También existen otras plataformas como [Bitbucked](https://bitbucket.org/product/) y [GitLab](https://about.gitlab.com), las cuales funcionan de manera similar a GitHub. + +## 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) + +## 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`. + +## 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?** + +1. 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. + +2. Da click a continuación en *Developer settings* ó *Parámetros del desarrollador*. + +3. En la barra lateral izquierda da click en *Tokens de acceso personal*. + +4. Haz click en *Generar un nuevo token*. + +5. Asígna un nombre descriptivo a tu token. + +6. 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 ) + +7. Finalmente haz click en *generar token*. + +8. 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. + + +```{bash eval=FALSE, echo=TRUE} +cd myrepo +ls -la +head README.md +git remote show origin + +``` + +**Probemos haciendo un cambio en el README** + +```{bash eval=FALSE, echo=TRUE} +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 + +```{bash eval=FALSE, echo=TRUE} +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: + +```{r, eval=FALSE} +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: + +```{r, eval=FALSE} + +library(gitcreds) + +gitcreds_set() + +``` + +```{r, eval=FALSE} + +library(credentials) + +set_github_pat() + +``` + +Para eliminar credenciales utiliza la función `credentials::git_credential_forget()` + +### Actividad +Ejecuta los códigos y genera tu PAT, recuerda no perderlo! + + +## Conectando RStudio con Git y Github. + +```{r,echo=FALSE, out.width='80%', fig.align='center'} +knitr::include_graphics("img/github_rstudio.png") +``` + +
+ +Para lo que sigue a continuación, deberías tener esto: + +1. Tener una cuenta en GitHub +2. **R** y **RStudio** actualizados +3. Git instalado +4. Saber que desde la terminal puedes hacer **push** y **pull** + +
+ + +## GitHub primero, RStudio después... + +1. Crea un repositorio en GitHub: `mi_repositorio` > *Public* > *YES* initialize this repository with a *README* > `click`en el gran botón verde "Create repository" +2. 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. + +### 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? + +### Comentar, pull y push + +```{r,echo=FALSE, out.width='80%', fig.align='center'} +knitr::include_graphics("img/gitrstudio_comment.png") +``` + +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. + +```{r,echo=FALSE, out.width='80%', fig.align='center'} +knitr::include_graphics("img/gitrstudio_push.png") +``` + +Volvemos a dar `click` en *commit*, y finalizamos con *push* (flecha verde). + +## 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 + +```{r echo=TRUE, eval=FALSE} +--- +title: "RmarkwondTest" +output: + html_document: + keep_md: true +--- +``` + +### 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 `#`: + +```{r, eval=FALSE} +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. + +
+ +## 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. + + +## Proyecto existente, GitHub al final + + +```{r,echo=FALSE, out.width='80%', fig.align='center'} +knitr::include_graphics("img/elmo_hell.png") +``` + +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: +```{r, eval=FALSE} +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. + +### 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: + +```{r, eval=FALSE} +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: + +1. Elije un nombre de repositorio; probablemente debería coincidir con el nombre de su proyecto y directorio local. +2. **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"**. + +```{r,echo=FALSE, out.width='80%', fig.align='center'} +knitr::include_graphics("img/purple_cuadros.png") +``` + +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"**. + +```{r,echo=FALSE, out.width='80%', fig.align='center'} +knitr::include_graphics("img/add_remote_rstudio.png") +``` + +Ahora solo haz **commit/pull/push** y cérciorate que FUNCIONE!! + +## Git basics: commands + +- Fetch Commits +```{bash eval=FALSE, echo=TRUE} +git fetch +``` + +- Create and Switch to a branch +```{bash eval=FALSE, echo=TRUE} +git branch [branch-name] +git checkout [branch-name] +``` + +## 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? + +## Merge conflics + +- Abran ese archivo y busquen los problemas de merge. Es fácil, se ven así: + +```{r echo=TRUE, eval=FALSE} +<<<<<<< HEAD:index.html + +======= + +>>>>>>> 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! + +```{bash eval=FALSE, echo=TRUE} +git merge --abort t +``` + +## En resumen + +**¡QUE LA FUERZA TE ACOMPAÑE!** + + diff --git a/01_sesion3.Rmd b/01_sesion3.Rmd index 36caec3..c5aceb3 100644 --- a/01_sesion3.Rmd +++ b/01_sesion3.Rmd @@ -1,6 +1,6 @@ -# Buenas prácticas de configuración y mantenimiento de espacios de trabajo +# Solución de problemas con las versiones de paquetes de Rstudio -Joselyn Cristina Chávez Fuentes +Yalbi Balderas 28 de octubre de 2024 @@ -8,6 +8,6 @@ Joselyn Cristina Chávez Fuentes [ ```{r,echo=FALSE} -knitr::include_url("https://comunidadbioinfo.github.io/cdsb2023/dia1_sesion1_slides.html", height = "380px") +knitr::include_url("https://comunidadbioinfo.github.io/cdsb2023/solucion_problemas.html", height = "380px") ``` -](https://comunidadbioinfo.github.io/cdsb2023/dia1_sesion1_slides.html) +](https://comunidadbioinfo.github.io/cdsb2023/solucion_problemas.html) diff --git a/01_sesion4.Rmd b/01_sesion4.Rmd deleted file mode 100644 index 8b8040a..0000000 --- a/01_sesion4.Rmd +++ /dev/null @@ -1,13 +0,0 @@ -# Modificando los archivos de inicio de R - -Joselyn Cristina Chávez Fuentes - -28 de octubre de 2024 - -## Diapositivas - -[ -```{r,echo=FALSE} -knitr::include_url("https://comunidadbioinfo.github.io/cdsb2023/dia1_sesion1_slides.html", height = "380px") -``` -](https://comunidadbioinfo.github.io/cdsb2023/dia1_sesion1_slides.html) diff --git a/01_sesion5.Rmd b/01_sesion5.Rmd deleted file mode 100644 index b42f3d7..0000000 --- a/01_sesion5.Rmd +++ /dev/null @@ -1,13 +0,0 @@ -# Nuevas funcionalidades de RStudio, Quarto - -Erick Cuevas - -28 de octubre de 2024 - -## Diapositivas - -[ -```{r,echo=FALSE} -knitr::include_url("https://erickcufe.github.io/Novedades_Rstudio_Quarto/rstudio_quarto.html", height = "380px") -``` -]() diff --git a/02_sesion1.Rmd b/02_sesion1.Rmd index 0741e1a..22808f9 100644 --- a/02_sesion1.Rmd +++ b/02_sesion1.Rmd @@ -1,465 +1,13 @@ -# Control de versiones con GitHub y RStudio +# Creando la infraestructura de un paquete -Dra. Alejandra Medina Rivera +Instructora: Joselyn Chávez 29 de octubre de 2024 - - - -- Este documento se basa en "Happy Git with R" de Jenny Bryan, los STAT 545 TAs, Jim Hester - - -https://happygitwithr.com - ## Diapositivas [ ```{r,echo=FALSE} -knitr::include_url("https://amedina-liigh.github.io/GitHubIntroSlides/GitHubIntro.html", height = "380px") -``` -](https://amedina-liigh.github.io/GitHubIntroSlides/GitHubIntro.html) - -## ¿Por qué hacer control de versiones de nuestros proyectos? - -1. ✅ Los proyectos suelen cambiar y crecer. -2. 💾 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!**). -3. 🤔 Las colaboraciones se pueden complicar sin un buen control de versiones. -4. 🔐 Seguridad. - -```{r,echo=FALSE, fig.align='center'} -knitr::include_graphics("img/git_why.png") -``` - -## 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. - -### **Git vs controles de versión a mano** - -```{r,echo=FALSE, fig.align='center'} -knitr::include_graphics("img/git_vers.png") -``` - -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](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` - - -
- -## 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**. - -## 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. - -## GitHub - -[GitHub](https://github.com/about) 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](https://github.com) y seleccionar `join`. -Es indispensable tu usuario para los ejercicios que siguen. -
- -También existen otras plataformas como [Bitbucked](https://bitbucket.org/product/) y [GitLab](https://about.gitlab.com), las cuales funcionan de manera similar a GitHub. - -## 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) - -## 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`. - -## 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?** - -1. 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. - -2. Da click a continuación en *Developer settings* ó *Parámetros del desarrollador*. - -3. En la barra lateral izquierda da click en *Tokens de acceso personal*. - -4. Haz click en *Generar un nuevo token*. - -5. Asígna un nombre descriptivo a tu token. - -6. 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 ) - -7. Finalmente haz click en *generar token*. - -8. 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. - - -```{bash eval=FALSE, echo=TRUE} -cd myrepo -ls -la -head README.md -git remote show origin - -``` - -**Probemos haciendo un cambio en el README** - -```{bash eval=FALSE, echo=TRUE} -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 - -```{bash eval=FALSE, echo=TRUE} -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: - -```{r, eval=FALSE} -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: - -```{r, eval=FALSE} - -library(gitcreds) - -gitcreds_set() - -``` - -```{r, eval=FALSE} - -library(credentials) - -set_github_pat() - -``` - -Para eliminar credenciales utiliza la función `credentials::git_credential_forget()` - -### Actividad -Ejecuta los códigos y genera tu PAT, recuerda no perderlo! - - -## Conectando RStudio con Git y Github. - -```{r,echo=FALSE, out.width='80%', fig.align='center'} -knitr::include_graphics("img/github_rstudio.png") -``` - -
- -Para lo que sigue a continuación, deberías tener esto: - -1. Tener una cuenta en GitHub -2. **R** y **RStudio** actualizados -3. Git instalado -4. Saber que desde la terminal puedes hacer **push** y **pull** - -
- - -## GitHub primero, RStudio después... - -1. Crea un repositorio en GitHub: `mi_repositorio` > *Public* > *YES* initialize this repository with a *README* > `click`en el gran botón verde "Create repository" -2. 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. - -### 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? - -### Comentar, pull y push - -```{r,echo=FALSE, out.width='80%', fig.align='center'} -knitr::include_graphics("img/gitrstudio_comment.png") -``` - -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. - -```{r,echo=FALSE, out.width='80%', fig.align='center'} -knitr::include_graphics("img/gitrstudio_push.png") -``` - -Volvemos a dar `click` en *commit*, y finalizamos con *push* (flecha verde). - -## 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 - -```{r echo=TRUE, eval=FALSE} ---- -title: "RmarkwondTest" -output: - html_document: - keep_md: true ---- +knitr::include_url("https://comunidadbioinfo.github.io/cdsb2023/solucion_problemas.html", height = "380px") ``` - -### 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 `#`: - -```{r, eval=FALSE} -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. - -
- -## 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. - - -## Proyecto existente, GitHub al final - - -```{r,echo=FALSE, out.width='80%', fig.align='center'} -knitr::include_graphics("img/elmo_hell.png") -``` - -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: -```{r, eval=FALSE} -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. - -### 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: - -```{r, eval=FALSE} -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: - -1. Elije un nombre de repositorio; probablemente debería coincidir con el nombre de su proyecto y directorio local. -2. **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"**. - -```{r,echo=FALSE, out.width='80%', fig.align='center'} -knitr::include_graphics("img/purple_cuadros.png") -``` - -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"**. - -```{r,echo=FALSE, out.width='80%', fig.align='center'} -knitr::include_graphics("img/add_remote_rstudio.png") -``` - -Ahora solo haz **commit/pull/push** y cérciorate que FUNCIONE!! - -## Git basics: commands - -- Fetch Commits -```{bash eval=FALSE, echo=TRUE} -git fetch -``` - -- Create and Switch to a branch -```{bash eval=FALSE, echo=TRUE} -git branch [branch-name] -git checkout [branch-name] -``` - -## 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? - -## Merge conflics - -- Abran ese archivo y busquen los problemas de merge. Es fácil, se ven así: - -```{r echo=TRUE, eval=FALSE} -<<<<<<< HEAD:index.html - -======= - ->>>>>>> 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! - -```{bash eval=FALSE, echo=TRUE} -git merge --abort t -``` - -## En resumen - -**¡QUE LA FUERZA TE ACOMPAÑE!** - - +](https://comunidadbioinfo.github.io/cdsb2023/solucion_problemas.html) diff --git a/02_sesion2.Rmd b/02_sesion2.Rmd index 9c703bb..5c38ac6 100644 --- a/02_sesion2.Rmd +++ b/02_sesion2.Rmd @@ -1,6 +1,6 @@ -# Solución de problemas con las versiones de paquetes de Rstudio +# Creando mis primeras funciones -Yalbi Balderas +Instructora: Joselyn Chávez 29 de octubre de 2024 diff --git a/02_sesion3.Rmd b/02_sesion3.Rmd index 5e46d1f..ac9d312 100644 --- a/02_sesion3.Rmd +++ b/02_sesion3.Rmd @@ -1,4 +1,4 @@ -# Infraestructura de un paquete de R/Bioconductor +# Documentación de funciones Instructor/a: @@ -8,6 +8,338 @@ Instructor/a: [ ```{r,echo=FALSE} -knitr::include_url("https://comunidadbioinfo.github.io/cdsb2023/solucion_problemas.html", height = "380px") +knitr::include_url("https://comunidadbioinfo.github.io/cdsb2023/Documentacion_slides_03_sesion5.html", height = "380px") ``` -](https://comunidadbioinfo.github.io/cdsb2023/solucion_problemas.html) +](https://comunidadbioinfo.github.io/cdsb2023/Documentacion_slides_03_sesion5.html) + + +## Links importantes: + +Esta lección está basada en algunos manuales sobre documentación: + ++ [Una viñeta del cranproject](https://cran.r-project.org/web/packages/roxygen2/vignettes/rd.html) ++ [El manual de paqutes de r](https://r-pkgs.org/man.html#sec-man-key-md-features) ++ [En esta viñeta de cranproject](https://combine-australia.github.io/r-pkg-dev/documenting-functions.html) + +## ¿Qué es la documentación de una función y por qué es importante? + +1. 🙇️ 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`. + +2. 📁 La documentación se almacena como un archivo .Rd ("R documentation) en la +carpeta `man/`. + +3. 🔎 La documentación usa una síntesis especial, que es distinta a la de r y +que está ligeramente basada en LaTeX. + +4. 📄 Se puede renderizar como html, pdf o texto sin formato según se necesite. + +## 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: + +1. ✅ 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. +2. 🎉 Puedes usar markdown en lugar de la síntesis especial para los archivos +``.Rd`` + +## 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: + +```{r, fig.align='center'} +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: + +```{r, fig.align='center'} +serie_numeros <- c(1, 2, 2, 2, 2, 3, 3, 4, 4, 4) +resultado <- getmode(serie_numeros) +print(resultado) +``` +Bien ahora si podemos podemos empezar a usar el paquete de roxygen para documentar nuestra función.. comencemos. + +## 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. + +```{r, fig.align='center'} +#' 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: + +```{r, fig.align='center'} +#' @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``: + +```{r, fig.align='center'} +#' @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. + +```{r, fig.align='center'} +#' @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: + +```{r, fig.align='center'} +#' @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: + +```{r, fig.align='center'} +serie_numeros <- c(0,2,2,"d", "d","d") +resultado <- getmode(serie_numeros) +print(resultado) +``` +```{r, fig.align='center'} +serie_numeros <- c() +resultado <- getmode(serie_numeros) +print(resultado) +``` +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 + +```{r, fig.align='center'} +#' @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: + +```{r, fig.align='center'} +#' @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()``. + +```{r, fig.align='center'} +#' @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: + +```{r, fig.align='center'} +#' @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. + +## 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. diff --git a/02_sesion4.Rmd b/02_sesion4.Rmd deleted file mode 100644 index 137d847..0000000 --- a/02_sesion4.Rmd +++ /dev/null @@ -1,16 +0,0 @@ -# Keynote: Convirtiendo tu flujo de análisis en un paquete de R/Bioconductor. - -Dr. Leonardo Collado Torres - -29 de octubre de 2024 - -## Diapositivas - -[ -```{r,echo=FALSE} -knitr::include_url("https://tinyurl.com/cdsb2021pkg", height = "380px") -``` -](https://tinyurl.com/cdsb2021pkg) - -Puedes encontrar las diapositivas [aquí](https://tinyurl.com/cdsb2021pkg). - diff --git a/02_sesion5.Rmd b/02_sesion5.Rmd deleted file mode 100644 index ac9d312..0000000 --- a/02_sesion5.Rmd +++ /dev/null @@ -1,345 +0,0 @@ -# Documentación de funciones - -Instructor/a: - -29 de octubre de 2024 - -## Diapositivas - -[ -```{r,echo=FALSE} -knitr::include_url("https://comunidadbioinfo.github.io/cdsb2023/Documentacion_slides_03_sesion5.html", height = "380px") -``` -](https://comunidadbioinfo.github.io/cdsb2023/Documentacion_slides_03_sesion5.html) - - -## Links importantes: - -Esta lección está basada en algunos manuales sobre documentación: - -+ [Una viñeta del cranproject](https://cran.r-project.org/web/packages/roxygen2/vignettes/rd.html) -+ [El manual de paqutes de r](https://r-pkgs.org/man.html#sec-man-key-md-features) -+ [En esta viñeta de cranproject](https://combine-australia.github.io/r-pkg-dev/documenting-functions.html) - -## ¿Qué es la documentación de una función y por qué es importante? - -1. 🙇️ 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`. - -2. 📁 La documentación se almacena como un archivo .Rd ("R documentation) en la -carpeta `man/`. - -3. 🔎 La documentación usa una síntesis especial, que es distinta a la de r y -que está ligeramente basada en LaTeX. - -4. 📄 Se puede renderizar como html, pdf o texto sin formato según se necesite. - -## 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: - -1. ✅ 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. -2. 🎉 Puedes usar markdown en lugar de la síntesis especial para los archivos -``.Rd`` - -## 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: - -```{r, fig.align='center'} -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: - -```{r, fig.align='center'} -serie_numeros <- c(1, 2, 2, 2, 2, 3, 3, 4, 4, 4) -resultado <- getmode(serie_numeros) -print(resultado) -``` -Bien ahora si podemos podemos empezar a usar el paquete de roxygen para documentar nuestra función.. comencemos. - -## 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. - -```{r, fig.align='center'} -#' 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: - -```{r, fig.align='center'} -#' @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``: - -```{r, fig.align='center'} -#' @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. - -```{r, fig.align='center'} -#' @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: - -```{r, fig.align='center'} -#' @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: - -```{r, fig.align='center'} -serie_numeros <- c(0,2,2,"d", "d","d") -resultado <- getmode(serie_numeros) -print(resultado) -``` -```{r, fig.align='center'} -serie_numeros <- c() -resultado <- getmode(serie_numeros) -print(resultado) -``` -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 - -```{r, fig.align='center'} -#' @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: - -```{r, fig.align='center'} -#' @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()``. - -```{r, fig.align='center'} -#' @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: - -```{r, fig.align='center'} -#' @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. - -## 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. diff --git a/02_sesionn.Rmd b/02_sesionn.Rmd new file mode 100644 index 0000000..cfcfc5c --- /dev/null +++ b/02_sesionn.Rmd @@ -0,0 +1,8 @@ +# Paths seguros + +Instructor/a: + +28 de octubre de 2024 + +## Diapositivas +