1 Introducción

Este capítulo es un resumen de los métodos que proponemos para resolver un problema importante.

1.1 El paquete R: bookdown

Toda la información referente a este paquete la puede encontrar en el siguiente enlace:

https://bookdown.org/yihui/bookdown/

Este paquete se centra en facilitar la tarea de construir documentos tipo libro, en diferentes formatos: html, pdf, word, epub, etc.

1.1.1 Instalación del paquete bookdown en R

Siguiendo los pasos que se indican en https://bookdown.org/yihui/bookdown/get-started.html, la instalación se realiza al ejecutar el siguiente código R:

# install.packages("devtools") # instalarlo previamente si no está
devtools::install_github("rstudio/bookdown")

1.2 Cómo crear un documento

1.2.1 Primer paso

  1. Crear un fichero RMarkdown (con extensión: “Rmd”) llamado: “index.Rmd”. Nota: se recomienda crear un proyecto (con una carpeta asociada) en el que localizar todo el material complementario al libro.

  2. Añadir a la cabecera YAML los siguientes campos, lo que le indicará a “Knit” que cree el libro con el sistema “bookdown::render_book”, y el formato de salida el usado en primer lugar en el campo “output” (en este ejemplo, sería “bookdown::gitbook”).

---
title: "Título de mi TFG"
author: "Pedro Luis Luque Calvo"
date: "21 de septiembre de 2016"
lang: es
documentclass: book
classoption: oneside
papersize: a4
fontsize: 10pt
knit: "bookdown::render_book"
output:
  bookdown::gitbook:
    lib_dir: "book_incluir"
  bookdown::pdf_book:
    keep_tex: yes
---

Si cambiamos el orden en el campo “output” como vemos a continuación se generaría la salida “bookdown::pdf_book”:

---
title: "Título de mi TFG"
author: "Pedro Luis Luque Calvo"
date: "21 de septiembre de 2016"
lang: es
documentclass: book
classoption: oneside
papersize: a4
fontsize: 10pt
knit: "bookdown::render_book"
output:
  bookdown::pdf_book:
    keep_tex: yes
  bookdown::gitbook:
    lib_dir: "book_incluir"
---

Actualmente hay tres tipos de salidas: bookdown::pdf_book, bookdown::gitbook y bookdown::html_book.

  1. Añadiríamos el texto utilizando el lenguaje de marcado “RMarkdown” y en RStudio pulsaríamos sobre el botón “Knit” para generar el libro-documento.

  2. A continuación podemos añadir nuevos ficheros “RMarkdown” en el mismo directorio. Lo que se recomienda es que en cada fichero vaya un capítulo distinto del libro.

    • El nivel 1 # será para indicar capítulos.
    • El nivel 2 ## será para indicar secciones.
    • El nivel 3 ### será para indicar subsecciones.

Todos los ficheros deben estar codificados con el sistema de codificación “UTF-8”.

A continuación se propone un ejemplo, donde los puntos indican el nombre del fichero y el texto a continuación sería parte del contenido de ese fichero:

  • index.Rmd
# Prólogo {-}
  
En este libro, introduciremos un método interesante y nos marcamos 
los siguientes objetivos ...
  • 01_intro.Rmd
# Introducción 

Este capítulo es un resumen de los métodos que proponemos para resolver 
un **problema importante**.
  • 02_estadoarte.Rmd
# Estado del arte

En este capítulo se hace una revisión de los métodos existentes.
  • 03_metodo.Rmd
# Métodos 

Describimos nuestros métodos en este capítulo.
  • 04_aplicacion.Rmd
# Aplicaciones

En este capítulo se muestran algunas aplicaciones de los métodos estudiados.

## Ejemplo uno

## Ejemplo dos
  • 05_conclusion.Rmd
# Conclusiones

En este capítulo se redactan las conclusiones del trabajo desarrollado y 
hablamos de posibles líneas futuras de trabajo.
  • 06_apendice01.Rmd
# Apéndice A {}

En este apéndice podemos incluir material adicional, como por ejemplo, 
el código R utilizado en el trabajo.
  • 99_referencias.Rmd
# Referencias Bibliográficas {-}

En este apéndice podemos incluir material adicional, como por ejemplo, 
el código R utilizado en el trabajo.

Por defecto, “bookdown” une todos los ficheros Rmd en la carpeta del fichero “index.Rmd” por el orden del nombre de los ficheros (primero añadirá: “01_intro.Rmd”“, luego:”02_estadoarte.Rmd“, etc.) Los ficheros que comiencen por”_" no se incluirán.

Este comportamiento se podrá modificar si incluimos un fichero llamado “_bookdown.yml" en el directorio del libro. Se puede usar un campo llamado “rmd_files” para definir tu propia lista y el orden de los ficheros Rmd que se utilizarán para crear el libro. Por ejemplo:

rmd_files: ["index.Rmd", "01-intro.Rmd", "03-metodo.Rmd"]

Si se quiere producir la salida HTML y la salida LaTeX/PDF del libro, y usar diferentes ficheros Rmd para la salida HTML y LaTeX/PDF, puede especificarse esos ficheros para los formatos de forma separada, por ejemplo:

rmd_files:
  html: ["index.Rmd", "resumen.Rmd", "01_intro.Rmd"]
  latex: ["resumen.Rmd", "01_intro.Rmd"]

La función bookdown::render_book() es una función similar a la función rmarkdown::render(), lo único que cambia es que la primera está pensada para crear documentos con múltiples ficheros Rmd. Se puede usar tanto en la consola de R:

bookdown::render_book("index.Rmd", "bookdown::gitbook")
bookdown::render_book("foo.Rmd", "bookdown::pdf_book") # u otro fichero principal
bookdown::render_book("foo.Rmd", bookdown::gitbook(lib_dir = "book_assets"))
bookdown::render_book("foo.Rmd", bookdown::pdf_book(keep_tex = TRUE))

Como también desde RStudio pulsando el botón “Knit”, pero en este caso debe existir una cabecera YAML con el campo llamado knit tomando el valor: bookdown::render_book, con el correspondiente campo output para seleccionar el formato de salida del libro:

---
knit: "bookdown::render_book"
output:
  bookdown::gitbook:
    lib_dir: "book_incluir"
  bookdown::pdf_book:
    keep_tex: yes
---
Ficheros en la carpeta del proyecto para generar un TFG-libro

Figure 1.1: Ficheros en la carpeta del proyecto para generar un TFG-libro

1.2.2 El fichero de configuración “_bookdown.yml"

Podrían incluirse opciones en este fichero, como por ejemplo:

---
book_filename: "milibro.Rmd"
#chapter_name: "CAPÍTULO "
before_chapter_script: ["script1.R", "script2.R"]
after_chapter_script: "script3.R"
edit:
  link: https://github.com/rstudio/bookdown/edit/master/inst/examples/%s
  text: "Edit"
output_dir: "book-salida"
clean: ["my-book.bbl", "R-packages.bib"]
---

O también estas otras opciones:

--- 
title: "Escribiendo un TFG con R Markdown"
author: "Yihui Xie"
date: "2016-09-23"
knit: "bookdown::render_book"
output:
  bookdown::gitbook: default
documentclass: book
bibliography: ["book.bib", "packages.bib"]
#biblio-style: apalike
csl: academy-of-management-proceedings.csl
link-citations: yes
---

1.2.3 Algunos consejos

  1. Trabaja con la salida HTML para ver el resultado provisional del libro. Trabaja sobre la salida libro-PDF después de haber finalizado el contenido del libro, o queden pocas revisiones.

  2. Si usas trozos de código R en el fichero R Markdown que requieren mucho tiempo de proceso de cálculo es aconsejable que uses la opción en la cabecera del “chunk” de código: cache=TRUE, y etiqueta también ese “chunk” para localizarlo fácilmente. Por ejemplo:

      ` ``{r calculo-importante, cache=TRUE}

  1. Construir un libro entero puede ser muy lento cuando el tamaño del libro es muy grande. Dos cosas pueden afectar a la velocidad en la construcción de un libro: los cálculos en los “chunk” con R, y la conversión de Markdown a otros formatos vía “Pandoc”.

    Una primera forma de mejorar esto es utilizando cache=TRUE. Sin embargo, puede elegirse procesar (“render”) solamente un capítulo usando la función preview_chapter() del paquete “bookdown”, y usualmente será mucho más rápido, ya que solamente se procesan los ficheros pasados a esta función. Nota: bookdown añade un plugin (addins) a RStudio que facilita este proceso (con la ayuda del paquete “servr”).

    Una desventaja de procesar capítulos individuales por este camino que la referencia cruzada a otros capítulos no funcionará.