index.Rmd

--- 
title: "Working with R"
author: "Eric Marcon"
date: "`r format(Sys.Date(), '%m/%d/%Y')`"
url: https://ericmarcon.github.io/WorkingWithR/
github-repo: EricMarcon/WorkingWithR
description: Organization of work around R and RStudio
# Title page...
maintitlepage:
  epigraph: |
    This document is made in a dynamic and reproducible way thanks to:

    \begin{itemize}
      \item \LaTeX, in its Miktex distribution (\url{http://miktex.org/}) and the memoir class (\url{http://www.ctan.org/pkg/memoir}).
      \item R (\url{http://www.r-project.org/}) and RStudio (\url{http://www.rstudio.com/})
      \item bookdown (\url{http://bookdown.org/}) and memoiR (\url{https://ericmarcon.github.io/memoiR/})
    \end{itemize}
    
    Its source code is on GitHub: \url{https://github.com/EricMarcon/WorkingWithR/}.
    
    The continuously updated text can be read at \url{https://ericmarcon.github.io/WorkingWithR/}.
    
  credits: |
    Cover photograph: Hadrien Lalagüe
  filigrane: filigrane
# Language
lang: en-US
# Paper, font
papersize: A4
fontsize: 12pt
mainfont: texgyretermes
mainfontoptions:
  - Extension=.otf
  - UprightFont=*-regular
  - BoldFont=*-bold
  - BoldItalicFont=*-bolditalic
  - ItalicFont=*-italic
mathfont: texgyretermes-math.otf
# memoir Style
MemoirChapStyle: daleif1
MemoirPageStyle: Ruled
# Margins
largemargins: false 
smallmargin: 1.5in
largemargin: 3in
marginnote:  1.8in
spinemargin: 1.5in
uppermargin: 1.5in
lowermargin: 1in
# Table of contents
toc-depth: 2
# Section numbering
secnum-depth: subsection
# List of tables / Figures
lot: false
lof: true
# Bibliography
bibliography: references.bib
biblatexoptions:
  - backend=biber
  - style=authoryear-ibid
  - isbn=false
  - backref=true
  - giveninits=true
  - uniquename=init
  - maxcitenames=2
  - maxbibnames=150
  - sorting=nyt
  - sortcites=false
# Chapter summary text
chaptersummary: "L'essentiel"
# Back Cover
backcover:
  - language: english
    abstract: |
      This book proposes an organization of work around R and RStudio to, beyond statistics, write documents efficiently with R Markdown, in various formats (memos, scientific articles, student theses, books, slideshows), create websites and online R applications (Shiny), produce packages and use R for teaching.
    abstractlabel: Abstract
backcoverfontsize: normalsize
# Figure cropping may be set to no if ghostscript is not installed
fig_crop: true
# Do not modify
documentclass: memoir
classoption:
  - extrafontsizes
  - onecolumn
  - openright
site: bookdown::bookdown_site
always_allow_html: true
graphics: true
link-citations: true
colorlinks: true
csquotes: true
---

<!-- Mandatory command to copy the "Take Home Message" icon in HTML--> 
<img src="images/trombone.png" alt="image" hidden/>

```{r}
#| label: DoNotModify
#| include: false
### Utilities. Do not modify.
# Installation of packages if necessary
install_packages <- function(packages) {
  install_package <- function(package) {
    if (!package %in% installed.packages()[, 1]) {
      install.packages(package, repos = "https://cran.rstudio.com/")
    }
  }
  invisible(sapply(packages, install_package))
}

# Basic packages
install_packages(c("bookdown", "formatR", "kableExtra", "magick", "ragg"))

# Chunk font size hook: allows size='small' or any valid Latex font size in chunk options
def.chunk.hook  <- knitr::knit_hooks$get("chunk")
knitr::knit_hooks$set(chunk = function(x, options) {
  x <- def.chunk.hook(x, options)
  ifelse(
    options$size != "normalsize", 
    paste0("\n \\", options$size,"\n\n", x, "\n\n \\normalsize"), 
    x
  )
})

# Output hook for full-width figures
defOut <- knitr::knit_hooks$get("plot")
knitr::knit_hooks$set(
  plot = function(x, options) {
    # Apply the original hook
    x <- defOut(x, options)
    # Only full-width figures
    if (options$out.width == "\\widthw") {
      # Modify output of the original hook, see code on:
      # https://github.com/yihui/knitr/blob/master/R/hooks-latex.R
      # Modify align1 output with align=center. Original code:
      # switch(a, left = '\n\n', center = '\n\n{\\centering ', right = '\n\n\\hfill{}', '\n')
      # replace centering by a minipage
      x  <- gsub(
        "\\n\\n\\{\\\\centering",
        "\\\\setbox0=\\\\hbox\\{\\\\begin\\{minipage\\}\\[h\\]\\{\\\\widthw\\}\\\\centering",
        x
      )
      # Modify align2 output with align=center. Original code:
      # switch(a, left = '\\hfill{}\n\n', '\n\n}\n\n', right = '\n\n', '')
      # replace } by the necessary code to place the minipage
      x  <- gsub(
        "\\n\\n\\}\\n\\n",
        "\\\\end\\{minipage\\}\\}\\\\needspace\\{\\\\ht0+\\\\dp0+2\\\\baselineskip\\}
          \\\\definesHSpace\\\\hspace\\{-\\\\rf\\}\\\\box0",
        x
      )
    }
    return(x)
  }
)

# Figures with side captions
if (rmarkdown::metadata$largemargins)
  knitr::opts_chunk$set(fig.env = 'SCfigure')
```

```{r}
#| label: Options
#| include: false
### Customized options for this document
# Add necessary packages here
packages <- c(
  "compiler", "dbmss", "doFuture", "doParallel", "entropart", "flextable",
  "foreach", "future", "future.apply", "gridExtra", "htmlwidgets", "magrittr",
  "methods", "microbenchmark", "parallel", "profvis", "pryr", "ragg", "R6",
  "Rcpp", "RcppParallel", "secret", "spatstat", "targets", "testthat",
  "tidyverse", "usethis", "visNetwork"
)
# Install them
install_packages(packages)
# Create packages.bib file to reference them as @R-package
knitr::write_bib(packages, file = "packages.bib")

# knitr options
knitr::opts_chunk$set(
  cache =   FALSE,    # Cache chunk results
  include = TRUE,     # Show/Hide chunks
  echo =    TRUE,     # Show/Hide code
  warning = FALSE,    # Show/Hide warnings
  message = FALSE,    # Show/Hide messages
  # Figure alignment and size
  fig.align = 'center', out.width = '80%', fig.asp = .75,
  # Graphic devices (ragg_png is better than standard png)
  dev = c("ragg_png", "pdf"),
  # Code chunk format
  tidy = FALSE, tidy.opts = list(blank = FALSE, width.cutoff = 60),
  size = "scriptsize", knitr.graphics.auto_pdf = TRUE
  )
options(width = 60)

# ggplot style
library("tidyverse")
theme_set(theme_bw())
theme_update(
  panel.background = element_rect(fill = "transparent", colour = NA),
  plot.background = element_rect(fill = "transparent", colour = NA)
)
knitr::opts_chunk$set(dev.args = list(bg = "transparent"))

# Random seed
set.seed(973)

# Create packages.bib file to reference them as @R-package
knitr::write_bib(packages, file = "packages.bib")
```


# Presentation {-}

## Objectives {-}

This document is the support of the course *Working with R*.

`r if (knitr:::is_html_output()) 'It can be <a href="https://ericmarcon.github.io/WorkingWithR/WwR.pdf" target="_blank">downloaded as a PDF file</a>.'`

It proposes an organization of the work around R and RStudio in order to, beyond statistics, write documents efficiently with R Markdown, in various formats (memos, scientific articles, student theses, books, slideshows), create a web site and online R applications (Shiny), produce packages and use R for teaching.
It complements *Reproducible Research with R and R Studio* [@Gandrud2013] with a more hands-on approach, with ready-to-use solutions.  

Optimizing the use of the many tools available is covered in detail: **rmarkdown**, **bookdown** and **blogdown** for writing, **roxygen2**, **testthat** and **pkgdown** for packages, source control with git and GitHub, continuous integration with GitHub Actions and Codecov.
Examples are presented at each step, and the necessary code is provided.

Chapter \@ref(chap-logiciels) is dedicated to the installation of the necessary tools: R, git and LaTeX.
Chapter \@ref(chap-utiliseR) details some advanced aspects of using R: the different languages, the environments, the performance of the code. 
The basic use of R is not covered here: good courses are suggested.
Chapter \@ref(chap-git) presents source control with git and GitHub.

Chapter \@ref(chap-rediger) shows how to write simple (articles) or complex (books) documents with R Markdown, integrating the data, the code to process them and the text to present them. 
Chapter \@ref(chap-package) presents a step-by-step method to efficiently create a package. 
Chapter \@ref(chap-ci) introduces the use of continuous integration to automatically produce documents, verify package code and produce package vignettes. 
Chapter \@ref(chap-shiny) introduces Shiny to develop R interactive applications.
Finally, chapter \@ref(chap-enseigner) introduces the tools for teaching R.


## Conventions {-}

Package names are in bold in the text, for example: **ggplot2**.

The identifier used on GitHub is noted *GitHubID*.
Project names are the same as their GitHub repository, noted *RepoID*.

The sign `|>` in the code of the examples indicates that the rest of the code should be on the same line, but is cut for the formatting of this document.
Its use is limited to YAML configuration files, mostly in chapter \@ref(chap-ci).
In all other cases, the code can be copied directly.

<!-- The \mainmatter command marks the beginning of the body of the LaTeX document--> 
<!-- It should not be deleted-->
\mainmatter