--- title: "Writing your thesis" author: "Bernhard Bieri" date: "`r Sys.Date()`" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Writing your thesis} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r global.options, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>", fig.align = 'center', fig.width = 6, fig.height = 4 ) ``` ```{r setup, include=FALSE} pkgs <- c("iheiddown", "magrittr", "ggplot2") lapply(pkgs, library, character.only = TRUE) ``` `{iheiddown}`'s primary feature is to enable students of the Institute to write their thesis in R-Markdown. It takes care of the annoying formatting process and automates the most repetitive tasks a student faces when writing scholarly documents. In short, `{iheiddown}` allows its users to focus on the *content* rather than the *formatting* of a thesis. This guide will show you how to get up and running and start writing your thesis in R while providing you with helpful tips and tricks to make you familiar with the workflow of writing your very own scholarly documents in R. ## Installation The installation process is the same than for the thesis template. You'll need the following software: 1. Install [R](https://cran.r-project.org) and [R-Studio](https://posit.co/) 2. Install a LATEX distribution: - [For MacOS](https://www.tug.org/mactex/) - [For Windows](https://miktex.org/) - [For Linux](https://www.tug.org/texlive/) 3. Install `{iheiddown}` by typing the following command `install.packages("iheiddown") ` in the R-Studio console. Note: typing `remotes::install_github("jhollway/iheiddown")` will provide you with the latest version from GitHub. ## Create your first thesis project Creating your first thesis is easy! Let's look at how it is done. Before we begin, we have to create a new R project by clicking on the file tab in the top of the RStudio window and following the instructions of the prompt that appears. Now that we have created an R project for our presentation, we can open a new R-Markdown file. To do this click on the "plus file" logo in the top left corner and then on "R-Markdown". ```{r, echo = FALSE, out.width="80%", fig.cap="Step 1: Open a project"} knitr::include_graphics("images/thesis/0-OpenProject.png", dpi = 144) ``` After you have done this, a little pop-up helper will appear. The first thing we will do is to select the `{iheiddown}` template for our thesis. To do so, click on the "From Template" option on the left and select the "Thesis {iheiddown}" template. Now give your thesis a name and click on "OK". Important note! Name your project `index`. This makes sure that the main Rmd file is called `index.Rmd` which is required to render your thesis with our `{bookdown}` based rendering function. Don't worry though, you can rename the folder to your project name after creating it. ```{r, echo = FALSE, out.width="80%", fig.cap="Step 2: Select a template"} knitr::include_graphics("images/thesis/1-CreateThesis.png", dpi = 144) ``` Congrats! You just created your first thesis project! Hold on, this doesn't look anything like a Word processor!? To see your thesis, you have to "knit" the code by clicking on the little "knit" button while viewing the `00-MyThesis.Rmd` file. This will run all the code chunks in every chapter and convert the Markdown code to a correctly formatted PDF document that you will find in the `\versions` folder of your project. Take a moment to read through the generated PDF to get acquainted with the `{R-Markdown}` syntax and to get a feel of the possibilities of `{iheiddown}`'s thesis template. This first document is as much a tutorial as this vignette! ## Edit your thesis This section will focus on giving you an overview of the elements of an `{iheiddown}` thesis and give you a few tips and tricks to edit it. ### The different elements of a `{iheiddown}` thesis After this initial preview, let's look at how the thesis project is structured to better understand how to edit it. #### The index file The index file contains two things: the YAML header and the preface of your thesis. It is also the backbone of your thesis in the sense that this is where you will want to knit your whole thesis from. The YAML header is the place where the main options, metadata and formatting parameters are set. You can set the title of your presentation here, add your name, change the front matter of your thesis (abstract, acknowledgments, table of content, etc.). The second element in this file is the preface. The only crucial thing to know here is that in order to create your package bibliography (the software you use to render your thesis) you need to leave the first code chunk there. #### The chapters The chapters contain the meat of your thesis, this is where you will outline your idea, run your analyses and draw your conclusions. Chapters are structured in a similar way, so let us open the `01-introduction.Rmd` chapter. In it, you will first find a YAML header that where you can set various chapter level metadata and options. Note that if for some reason you rename the chapter, you will need to specify the new name in the YAML header too under the `input` option. Once you have done this you can write away! The last thing to know about individual chapters is that you can knit them individually. This comes in handy when you want to generate only one part of your thesis for preview purposes. #### The appendix and the references files These files are a bit special as you might notice when you open them. The `99-references.Rmd` file generates the bibliography. This happens automatically, so you will most likely not need to alter this file. Just know that you can set the title of the reference section in the first line. The `98-appendix.Rmd` file allows you to showcase code, additional outputs and more in a separate section to avoid unnecessarily cluttering the main body of your thesis. This can be done by [referencing code chunks](https://bookdown.org/yihui/rmarkdown-cookbook/reuse-chunks.html) from your main body and printing the computations you did in your R chunks or by adding new ones. #### The `_bookdown.yml` file The `_bookdown.yml` file contains additional information for the YAML header of the main `.Rmd` file. A standard user should not have to edit it. If for some reason or another you still feel like it, you need to know that you can set additional `.Rmd` subdirectories, set another output file than the standard `\versions` file, and toggle the deletion of merged files after the knitting process ended here. #### The `\bib` folder The bibliography folder contains two files; `packages.bib` and `references.bib`. The former is automatically generated by the first code chunk in the `index.Rmd` file and cites the packages you have loaded when running your code chunks. You will not need to alter this. On the other hand, the `references.bib` file is the place to dump the bibtex citations that you will cite in your thesis. #### The `\data` folder The data folder is the place to put all the data that you use in the code chunk of your analysis. Remember to keep it tidy so you can easily link data to outputs down the line such as graphs and tables. #### The `\figures` folder The figures folder will contain all the graphical elements that you may want to include in your thesis e.g. figures, graphs, or images. It also contains a file named `SecretariatDocument.pdf` that you will need to replace with the one that was handed to you by the PhD or Master's secretariat. Remember to rename the file you got from the secretariat as `SecretariatDocument.pdf`. Otherwise `{iheiddown}` will not recognize it. #### The `\front-matter` folder The front matter folder contains the front matter of your thesis. This is where you will be able to edit the abbreviations part in the corresponding Latex file, the acknowledgments section or the abstract of your thesis in their respective `.Rmd` files. #### The `\versions` folder This is where you will find the pdf file after your thesis has been knitted by `{iheiddown}`. ## Additional resources Here is a list of additional links that will help you get familiar with our `{iheiddown}` thesis template, `{bookdown}` and `Markdown` syntax. - [R-Markdown Cookbook](https://bookdown.org/yihui/rmarkdown-cookbook/) - [Bookdown book](https://bookdown.org/yihui/bookdown/) - [Markdown guide](https://www.markdownguide.org/)