Home

Awesome

aggiedown <img src="https://upload.wikimedia.org/wikipedia/commons/thumb/f/f3/The_University_of_California_Davis.svg/128px-The_University_of_California_Davis.svg.png" style="width:175px;height:175px;" align="right" />

This project provides a template for writing a PhD thesis in R Markdown, and rendering those files into a PDF formatted according to the requirements of the University of California, Davis. It uses an amalgamation of the University of Washington Thesis class and the University of California Thesis Class to convert R Markdown files into a PDF formatted ready for submission. This project was started by the thesisdown and bookdown packages, but has since followed a very winding path through many other excellent renditions (please see the University of Washington huskydown and UCSB gauchodown) before ending up here.

Currently, the PDF and gitbook versions are fully-functional, and are the focus of this package. The word and epub versions are in development, have no templates behind them, and are essentially calls to the appropriate functions in bookdown.

If you are new to working with bookdown and rmarkdown, please read over the documentation available in aggiedown PDF template (which you can create by following the simple instructions below) and the bookdown book.

At the same time, composition and formatting can be done using lightweight markdown syntax, and R code and its output can be seamlessly included using rmarkdown.

Using aggiedown to write your dissertation

For an alternate setup (not in R), check out Luiz's conda based approach with full Github Actions CI!

Initial setup

Using aggiedown has some prerequisites, such as Pandoc, LaTeX and some fonts. To compile PDF documents using R, you need to have Pandoc, LaTeX and several related packages installed. If you have a recent version of RStudio, then you already have Pandoc and don't need to do anything more about that.

Next is LaTeX. By far the easiest way to install LaTeX on any platform is with the tinytex package:

install.packages(c('tinytex', 'rmarkdown'))
tinytex::install_tinytex()
# after restarting RStudio, confirm that you have LaTeX with 
tinytex:::is_tinytex()

However, if for some reason you are running into trouble, you can use a full install of MiKTeX for any system, or MacTeX for MacOSX systems, and typically things should function.

The PDF template requires some specific fonts, EB Garamond, Source Code Pro and Lato. These are included in this repository, however, you need to install these before proceeding, either by using your usual method of installing fonts, or following these instructions:

On a Linux system here's the simplest way to install the fonts:

git clone https://github.com/ryanpeek/aggiedown
cd aggiedown && unzip inst/fonts.zip
cp inst/fonts -r ~/usr/local/share/fonts
sudo fc-cache -f -v

On an OSX system you can download a copy of the fonts in this repository with https://github.com/ryanpeek/aggiedown/raw/master/inst/fonts.zip, unzip and move them to your fonts directory, or, assuming homebrew is installed and updated, this will get you the fonts needed for this template:

brew update
brew tap homebrew/cask-fonts
brew install font-eb-garamond font-source-code-pro font-lato

On Windows the usual pointing and clicking is required to install the fonts listed above. You can download a copy of the fonts in this repository at https://github.com/ryanpeek/aggiedown/raw/master/inst/fonts.zip, unzip and move them to your fonts directory.

Starting to write your thesis

To use aggiedown from RStudio:

  1. Ensure that you have already installed LaTeX and the fonts described above, and are using the latest version of RStudio and R. You can use aggiedown without RStudio. For example, you can write the Rmd files in your favourite text editor (e.g. Atom, Notepad++). But RStudio is probably the easiest tool for writing both R code and text in your thesis.

  2. Install the bookdown and aggiedown packages:

if (!require("devtools")) install.packages("devtools", repos = "http://cran.rstudio.org")
install.packages("bookdown")
devtools::install_github("ryanpeek/aggiedown")
  1. Use the New R Markdown dialog to select UCD-Dissertation, here are the steps, and a screenshot below:

File -> New File -> R Markdown... then choose 'From template', then choose 'UCD-Dissertation, and enter index as the Name. Note that this will currently only Knit if you name the directory index at this step.

Or if you're not using RStudio, run this line in your R console to create a new PhD dissertation from the template:

rmarkdown::draft('index.Rmd', template = 'UCD-Dissertation', package = 'aggiedown', create_dir = TRUE)

Starting your first draft

Hopefully now you've got a nice looking repo and your index.Rmd file. The YAML (YAML ain't markup language) material at the start of index.Rmd contains a bunch of metadata for your dissertation. This is where you can enter your name, dissertation title, committee members, abstract, dedication, acknowledgements, etc.

The gauchodown template has a CV section that includes education and publications, I've commented it out in the aggiedown package as UC Davis currently doesn't require this in dissertations. If you want this to appear in your dissertation you'll need to edit this section inside the folder created from your template in the template.tex file, and modify the block labeled "CV" (should be around line 147).

Chapter Short Titles

Let's face it, chapter titles are often long (of course to reflect all the amazing research inside). This can create a bit of a mess in the header of your chapters, as "Chapter 1. The Dynamics of Monological Imperatives in Dick and Jane: A Study in Phsycic Transrelational Gender Modes" spills over your margins. To that end, you can provide a short title for each chapter that will appear by including \chaptermark{My Short Title} below the actual title of each chapter's .Rmd. For example, this template will generate a file called 01-chap1.Rmd. Inside there, the full title of this chapter is # R Markdown Basics {#rmd-basics}, and below that I added in a short title called "Basics" by including \chaptermark{Basics} in 01-chap1.Rmd.

Day-to-day writing of your thesis

You need to edit the individual chapter R Markdown files to write your thesis.

You can write in the Rmd files without RStudio (in fact RStudio lacks some conveniences for writing, such as live spell-checking and live word count). So you may prefer to do some writing and editing your Rmd files in your favourite text editor. I frequently use Atom, Notepad++, and Emacs. But I come back to RStudio to create the PDF and work on the R code in my documents.

While writing, you should git commit your work frequently, after every major activity on your thesis. For example, every few paragraphs or section of text, and after major step of analysis development. You should git push at the end of each work session before you leave your computer or change task. For gentle novice-friendly guide to getting starting with using Git with R and RStudio, see http://happygitwithr.com/.

Organizing with knitr::knit_child

You can certainly use the same project to house all of the data and code for each of your chapters (and if your analysis runs fast enough you could of course simply do all of your analysis and writing for a chapter in the .Rmd for that chapter). I personally find this to be a bit cumbersome though, and since the end goal of the research in your dissertation isn't the dissertation, but (presumably) papers produced from your dissertation, I preferered to keep each of my chapters in their own projects, which I then knitted together for the final dissertation. Let me explain.

My dissertation had three chapters. For each chapter, I created a separate RStudio project and folder on my computer, for example, call it "Documents/PhD/zissou" . Inside that folder I stored the data, code, and paper .Rmd for the zissou chapter. When I wanted to actually knit the dissertation, rather than copy-and-pasting all the required results or data from zissou over to my dissertation folder, I simply used knit_child (and some voodoo in the chunk options).

Rendering

To render your thesis into a PDF, open index.Rmd in RStudio and then click the "knit" button. To change the output formats between PDF, gitbook and Word , look at the output: field in index.Rmdand comment-out the formats you don't want.

Alternatively, if you're not using RStudio, you can use this from the R console, assuming your have set the 'index/ directory as your working directory:

bookdown::render_book('index.Rmd', aggiedown::thesis_pdf(latex_engine = 'xelatex'))

The PDF file of your thesis will be deposited in the _book/ directory.

Components

The following components are ones you should edit to customize your thesis:

_bookdown.yml

This is the main configuration file for your thesis. It determines what Rmd files are included in the output, and in what order. Arrange the order of your chapters in this file and ensure that the names match the names in your folders.

index.Rmd

This file contains all the meta information that goes at the beginning of your document. You'll need to edit this to put your name on the first page, the title of your thesis, etc.

01-chap1.Rmd, 02-chap2.Rmd, etc.

These are the Rmd files for each chapter in your dissertation. Write your thesis in these. If you're writing in RStudio, you may find the wordcount addin useful for getting word counts and readability statistics in R markdown documents. You might also enjoy writing in these Rmd files with Atom, Notepad++, Sublime Text, and Emacs.

bib/

Store your bibliography (as bibtex files) here. We recommend using the citr addin and Zotero to efficiently manage and insert citations.

csl/

Specific style files for bibliographies should be stored here. A good source for citation styles is https://github.com/citation-style-language/styles#readme

figure/ and data/

Store your figures and data here and reference them in your R Markdown files. See the bookdown book for details on cross-referencing items using R Markdown.

Related projects

This project has drawn directly on code and ideas in the following:

Other relevant projects:

Contributing

If you would like to contribute to this project, please start by reading our Guide to Contributing. Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

<!-- To update the PDF template stored in inst/ assuming we are at top level: rmarkdown::draft('index.Rmd', template = 'thesis', package = 'aggiedown', create_dir = TRUE, edit = FALSE) setwd('index') bookdown::render_book('index.Rmd', aggiedown::thesis_pdf(latex_engine = 'xelatex')) -->