Get started

tl;dr:

  • To open and use this book’s project just download it’s source files from GitHub http://statistify.de/thesiswritingUsingRStudioAndBookdown_repo , run _installPackages.r and then open the .Rproj-file in RStudio (of course you need R and RStudio).

  • After successfully installing bookdown (see Rstudio und Packrat; maybe you need to restart RStudio) you should find the button “Build Book” in the “Build”-tab in RStudio. “Build Book” creates the book in all output formats. You can find the index.html, pdf etc. in the docs-folder.

beta:

In theory the only thing you need to do is to download the .zip-folder of this RProject from my Github Repository (or clone or fork it if your familiar with GitHub) and open the .RProject-file. As the R packages contained in the folder need to be installed for your machine (see RStudio und Packrat ), opening the RProject may take a few seconds or actually even some minutes. If you move or share your own project, it migth be a good idea to delete the folder /packrat/lib/ before starting the RProject on a new machine in order to have a clean installation of the packages.
There is also a zip-file containing the RProject downloadable via the download button on top of this book, if your reading it online. As I haven’t been implementing a routine creating the latter zip automatically or figured out how to link to my GitHub repo for now, I cannot promise that it will be the current version of this project.

Direct link to the RProject:
https://github.com/kreflix/thesiswritingUsingRStudioAndBookdown/archive/master.zip
Be patient while opening the project the first time. Also you might need an internet connection. Check R Console for what is happening.

stable:

You have to install all required packages manually or run the _installPackages.r-file.

Especially you have to install the bookdown-package in R or could install the development versions of bookdown from Github:

install.packages("bookdown")
library(bookdown)
#devtools::install_github("rstudio/bookdown")

Remember each Rmd file contains one and only one chapter, and a chapter is defined by the first-level heading #.

To compile this example to PDF, you need to install XeLaTeX. Pandoc assumes some LaTeX packages to be availabe. See http://pandoc.org/MANUAL.html#creating-a-pdf.

I assume you have already installed R and RStudio and you know how to install any other package this RProject may need (see _Auswertungsskript.r).

RStudio und Packrat

Da Packrat in Vergangenheit Probleme bereitet hat, enthält diese Version ein Skript, das zunächst ausgeführt werden muss, um die notwendigen Pakete zu installieren. Die folgenden Infos zu Packrat sind interessant, betreffen aber die beta-Version dieses Templates.

Führe das Skript _installPackages.r aus, um alle Pakete zu laden und zu installieren, die zum Kompilieren dieses Buches/Templates notwendig sind.

Wenn du den Projektordner dieses Buches heruntergeladen hast (siehe Links und Tipps), verwendest du automatisch Packrat, da die entsprechende Projekt-Option bereits aktiviert ist. Das bedeutet, dass sich die für dieses Buch verwendeten R-Pakete in einer private library direkt im Projektordner installieren (somit hat jedes Projekt seine eigenen Pakete).

Da die Pakete auf jedem Computer neu installiert werden müssen, beinhaltet der Unterordner /packrat anfangs nur die Infos, welche Pakete du benötigst (einen sogenannten Snapshot). Der Ordner /src beinhaltet die package tarballs und sollte der Versionskontrolle unterliegen, wenn du z.B. Git verwendest, sodass das Projekt auch langfristig reproduzierbar bleibt, selbst dann, wenn die Pakete nicht mehr online zur Verfügung stehen.4 Die Pakete werden in den Ordner /packrat/lib installiert, sodass du bei jedem Umzug des Projektes auf einen neuen PC diesen Ordner zunächst löschen solltest.

Tipp: In der Developer-Version von packrat gibt es die Möglichkeit, die Pakete zu cachen, sodass sie außerhalb des Project Folders gespeichert werden und im private library nur ein Link zum jeweiligen Paket verweist5. Dies kann den Ordner um mehrere 100mb leichter machen.

install.packages("devtools")
devtools::install_github("rstudio/packrat")

Beim erstmaligen Start des Projektes wird R versuchen, Packrat und alle notwendigen Pakete auf deinem Computer zu installieren. Dies kann einige Minuten dauern und eine Internetverbindung benötigen. Beobachte währenddessen die Meldungen in der Console. Sollte es nicht automatisch klappen, dann probiere

  1. packrat::restore()
  2. packrat manuelle zu installieren
  3. oder schaue in _Auswertungsskript.r, welche Pakete für dieses Buch geladen werden müssen.

Weitere packrat-Befehle:

#packrat::set_opts(external.packages=installed.packages()[,"Package"])  #install all packages outside the project'S folder if you want a lightweight folder. But be aware: packages installed in this way aren't included in the packrat/src folder and so your project might become unreproducible in the future!
#packrat::set_opts(use.cache = TRUE)  #use.cache=TRUE might be useful, but only enabled under windows in the developer version of packrat
packrat::get_opts()  #aktuelle Packrat-Einstellungen
#packrat::init()  #Initializes the current working directory as a Packrat project.
packrat::status()
packrat::restore()  #also good for syncing wiht library changes made by a collaborator
packrat::clean()  #löscht scheinbar nicht benötigte Pakete (erkennt Pakete an library() und require() )

After successfully installing R, RStudio, all R packages and LaTeX6 (if you want to create PDF files), you should find the button “Build Book” in the “Build”-tab in RStudio. “Build Book” creates the book in all output formats. You can find the index.html, pdf etc. in the docs-folder.

  1. tbd: Packrat lädt in meinem Falle trotz hinterlegter tarballs die Pakete aus dem Internet.↩

  2. https://github.com/rstudio/packrat/issues/338#issuecomment-320553343↩

  3. How to correctly install and set up LaTeX is another chapter, that I can’t cover by now, because it is still some sort of a mystery for me, why some things work while others don’t.↩