iheid-library/iheiddown

An R package for writing Geneva Graduate Institute documents

iheiddown

Table of Contents

• iheiddown
  • Write your dissertation
  • But not only !
  • Installation
  • Quick start guide
  • Feedback

{iheiddown} is a package that provides templates for writing documents in styles consistent with the Geneva Graduate Institute/ Institut de Hautes Etudes Internationales et du Developpement (IHEID) in (R) markdown.

The main use case for {iheiddown} is for writing a Masters or PhD Dissertation at IHEID, as it offers a user-friendly, simple, and straightforward way to write a well-formatted and consistent dissertation that weaves together argument, evidence, and interpretation. However, it also integrates templates for creating IHEID themed presentations powered by {xaringan} as well as a template for IHEID course syllabi.

Write your dissertation

The package is built upon the IHEID LaTeX dissertation template, which offers versus common word processors:

• less prone to corruption or crashing
• more internal consistency
• ensured consistency with the IHEID dissertation and other guidelines, e.g. dedication, abstract, abbreviations, tables of contents, figures, and tables
• automatic figure and table referencing
• automatic compilation of your references and bibliography (under different styles)
• compilation chapter-by-chapter (for sending to your supervisor) or whole dissertation (for submission)
• cross-referencing
• smaller files
• automatic versioning
• and much more!

Though you may have never had problems using Word in the past, the size and structure of most theses tax Word’s capabilities.

However, {iheiddown} helps you avoid the need to (learn how to) write in LaTeX. LaTeX can be daunting for first time users, and many users often feel it would only pay off if they were writing very complex dissertations. {iheiddown} allows students to write their dissertations in RMarkdown. Markdown is a simple and easy-to-use way to ‘markup’ parts of plain text as headings, bold or italics (and much more) in ways that remain very readable and thus editable as you write. {iheiddown}, R, and LaTeX do the work to turn this into a beautiful dissertation. You write in minimally marked-up plain text and you get a correctly-formatted dissertation out at the end.

But wait, there’s more! Because {iheiddown} is an R package, it especially shines for those who are analysing data. R is a free statistical programme and language that has a huge range of packages available for most current methods of analysis and visualisation. RStudio is a typical frontend that makes working in R and especially with {iheiddown} easy. So though {iheiddown} is especially attractive to those writing dissertations with many tables and figures, the user-friendly nature and pretty output should make it of great benefit to nearly anyone writing a thesis project.

You can see an example of the kind of dissertation output on the package website.

But not only !

Not quite done yet, there is even more! Take a look at the following table for all available templates:

Templates	Format	Status
Thesis	PDF	👍
Syllabus	PDF	👍
{xaringan} presentations	HTML (can be printed to PDF)	👍
Problem set	PDF	👍
Posters	HTML (+ print to PDF)	🌟 🆕 🌟
Your idea	Open a PR!	✨

Installation

Prerequisites

You will first need to install the following software on your system²:

• R
• RStudio version 1.2 or higher, and
• LaTeX or MiKTeX¹

Installing the Stable Version

The easiest way to install the latest stable version of {iheiddown} is via CRAN. Simply open the R console and enter the following to install and load {iheiddown}

install.packages('iheiddown')
library(iheiddown)

That’s it! iheiddown is now installed and ready to go.

Installing the Development Version

To get access to the latest features, you may want to install the development version of the package.

An easy way of getting access to this version is to install the latest main version of {iheiddown} from Github. To do that, please install the {remotes} package from CRAN and then enter the following commands into the console:

• For latest stable version: remotes::install_github("jhollway/iheiddown")
• For latest development version: remotes::install_github("jhollway/iheiddown@develop")

Alternatively, you can find the binaries for all major OSes – Windows, Mac, and Linux – by looking up the latest release of the package here. Manually download the appropriate binary for your operating system, and install using an adapted version of the following commands:

• For Windows: install.packages("~/Downloads/iheiddown_winOS.zip", repos = NULL)
• For Mac: install.packages("~/Downloads/iheiddown_macOS.tgz", repos = NULL)
• For Unix: install.packages("~/Downloads/iheiddown_linuxOS.tar.gz", repos = NULL)

Quick start guide

{iheiddown}, among other things, sets up a thesis template that you can then modify for your dissertation. It’s very easy to get started!

Since the process is similar for theses, presentations, problem sets and syllabi let us take a look at how to set up a thesis project.

1. Open RStudio (if it is not already).
2. Click the new document symbol at the very top left and choose R Markdown....
3. Then from the options on the left From Template.
4. Scroll down through the options on the right until you find Thesis {iheiddown}.
5. Name your thesis project index, i.e. your main .Rmd should be named index.Rmd
6. Select where the project should be saved on your hard drive.

Congratulations! You have now set up your first thesis project. For a more detailed walkthrough of the different functionalities and how to get started with each one, please check out the different articles on the package website.

Feedback

Please raise an issue for this repo if you encounter any bugs or if you have any feature requests. You can also vote on existing issues that you would like to see addressed soon. If you would like to contribute to the repo, please fork this repository and open a pull request when your changes are ready, or get in touch with me directly.

¹ For Windows users, make sure you have the latest MiKTeX version installed on you computer. From the MiKTeX console, you should regularly check for updates as “MiKTeX user mode”, this will prevent issues when generating your pdf document from your Markdown template.
² Note that, for unclear reasons, Yihui Xie’s TinyTeX is causing trouble. Try tinytex::uninstall_tinytex() and install a local copy. Unfortunately, full LaTeX installations are large.

iheiddown's Issues

Error to generate PDF

Describe bug 1
The following message appears:
Error: Input files not all in same directory, please supply explicit wd
The problem seems to be with Bookdown 0.20

The solution is discussed here:
https://stackoverflow.com/questions/62578811/error-input-files-not-all-in-same-directory-please-supply-explicit-wd

To solve the problem I just used a Rprofile in the same folder as index.Rmd with the following command:
options(bookdown.render.file_scope = FALSE)

Describe bug 2 (related)
After using the Rprofile the pdf is generated but with the following error in the console:

Translated and Original, respectively:

Error in merge_lists(as.list(formals(format_function)), format$options, :
argument "base" missing, no standard
Error in merge_lists(as.list(formals(format_function)), format$options, :
argumento "base" ausente, sem padrão

The solution was to replace this original output options in the YAML Metadata :
output: bookdown::render_book: input: "Untitled/Untitled.Rmd" output_format: iheiddown::thesis_pdf link-citations: true documentclass: book
for this output options:

knit: "bookdown::render_book"; output: iheiddown::thesis_pdf; link-citations: true; documentclass: book;

Expected behavior
The document is not knited and there is no pdf document.

Desktop (please complete the following information):

• OS: Windows 10
• R Version 4.0.2
• RStudio Version 1.3.959

Additional context
The Thesis {iheiddown} template was used and installed as suggested in the README.md.

Create an appendix Rmd file

Create an appendix Rmd file to dump tables, graphs, and more tables that would otherwise clutter the main corpus of the thesis.

iheiddown ggplot theme

Add syllabus template

Create open graph image

Better citations for syllabus

Page numbers do not display when "draft option" is selected

Description:

Page numbers at the bottom of the pages in the chapters do not display if the draft option is selected. This should be addressed for ease of communication between parties when correcting the draft of the thesis.

Revising the formatting of the bibliography

Currently, the bibliography displays with the same style as the rest of the document instead of having a neater "bibliography like" indentation and overall style.

Improve on iheiddown::theme_iheid()

https://github.com/hrbrmstr/hrbrthemes

Add CSS font scaling to xaringan slides

https://stackoverflow.com/questions/16056591/font-scaling-based-on-width-of-container

Citation style: page number in citations

I would need to add the page number in my in-text citation.
For instance, instead of (Eising 2007), I would like (Eising 2007, p.330–31)

Is the feature already available?

I found this explanation on Stackoverflow, but I don't know if the feature depends on the csl file, or something else.

Add presentations slides template

Issue with the multiline thesis title on macOS

Describe the bug
On macOS, the thesis title displays as "Conclusion" instead of the multiline title defined in the YAML header macro. We have managed to alleviate the issue by replacing the name of the YAML macro by something else than "title".

Desktop:

• OS: MacOS Big Sur 11.1
• R Version: 4.0.3
• RStudio Version 1.4

Solved by renaming the "title macro" to "doctitle" in the Yaml header.

Converting tables to word

For those who wish to export (e.g. individual chapters) to Word, tables can be a problem.

Look further into kableExtra, Huxtable, and flextable

Encoding Issue on Windows

This issue is specific to Windows. It arises when the user knits the document (using the thesis_pdf() function of the {iheiddown} package. Basically, the generated Latex file by the aforementioned function and Pandoc contains badly encoded special characters such as ö ä ü from the German alphabet.

Consider further export parameters

https://www.r-bloggers.com/2020/09/bookdown-not-bookout/?utm_source=feedburner&utm_medium=feed&utm_campaign=Feed%3A%20RBloggers%20%28R%20bloggers%29

Add NEWS/changelog

Users need to track changes

Create as a package template for ease of use

See here

Update thesis template

Add IHEID letter template

https://github.com/eddelbuettel/linl

Add automatic rendering for syllabi and presentation

https://github.com/jhollway/iheiddown/blob/c6505f2c943719bcdec64cf1e19f4b7bd3ed1880/R/_render.R#L20

---

This issue was generated by todo based on a TODO comment in c6505f2 when #58 was merged. cc @jhollway.

Test theme_iheid() output

• https://github.com/r-lib/vdiffr

• https://stackoverflow.com/questions/31038709/how-to-write-a-test-for-a-ggplot-plot

Excution halted when kniting the template on Linux

Hi,

Thank you very much for your template. I am really looking forward to writing my thesis with it.

When trying to knit the template, the following error appears on my console:

    Output created: versions/Name_Thesis_2021-03-10.pdf
    Error: Format is not of class rmarkdown_output_format
    Execution halted

I followed the instructions under the section "Getting Started" and "Output options". Nevertheless,Ii somehow renders the new PDF file (Name_Thesis_2021-03-01.pdf).

Could you please take a look at it? I've tried a couple of things but none of them worked. Thanks in advance!

---

    Session information:
    
    R version 4.0.4 (2021-02-15)
    Platform: x86_64-pc-linux-gnu (64-bit)
    Running under: Ubuntu 20.04.2 LTS
    
    Matrix products: default
    BLAS:   /usr/lib/x86_64-linux-gnu/blas/libblas.so.3.9.0
    LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.9.0
    
    locale:
     [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C               LC_TIME=en_US.UTF-8       
     [4] LC_COLLATE=en_US.UTF-8     LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
     [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                  LC_ADDRESS=C              
    [10] LC_TELEPHONE=C             LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
    
    attached base packages:
    [1] stats     graphics  grDevices utils     datasets  methods   base     
    
    loaded via a namespace (and not attached):
     [1] knitr_1.31        magrittr_2.0.1    tidyselect_1.1.0  munsell_0.5.0     colorspace_2.0-0 
     [6] R6_2.5.0          rlang_0.4.10      fansi_0.4.2       dplyr_1.0.5       tools_4.0.4      
    [11] grid_4.0.4        gtable_0.3.0      xfun_0.21         utf8_1.1.4        DBI_1.1.1        
    [16] htmltools_0.5.1.1 ellipsis_0.3.1    assertthat_0.2.1  yaml_2.2.1        digest_0.6.27    
    [21] tibble_3.1.0      lifecycle_1.0.0   crayon_1.4.1      bookdown_0.21     purrr_0.3.4      
    [26] ggplot2_3.3.3     vctrs_0.3.6       glue_1.4.2        evaluate_0.14     iheiddown_0.8.0  
    [31] rmarkdown_2.7     compiler_4.0.4    pillar_1.5.1      generics_0.1.0    scales_1.1.1     
    [36] pkgconfig_2.0.3  

Change the placeholder text

When printing just a single chapter with chapter_pdf(), the section titles of all the other chapters are included in addition and some 'placeholder' text is entered under some of these extra section titles. These extra section titles either should not appear or appear only in the table of contents printed at the start of the chapter preview.

Add zzz

Paper based dissertation: Add abstract at the beginning of every chapter/paper

I am writing a paper-based dissertation and I would like to add the paper's abstract at the beginning of every chapter/paper. The current YAML section for the individual chapters is the following and does not include an "abstract" heading:
title: Theory # or name of the section i.e. Introduction, Method, Results, etc
knit: iheiddown::chapter_pdf

I tried adding the abstract heading in the YAML section of each chapter as follow:
abstract: \singlespacing _Here goes my abstract_, or
\abstract{Here goes my abstract}, or
abstract: "Here goes my abstract".

However, the rendering of the individual chapters halted, or when I tried to render the whole thesis, it did not include the abstract at all. I temporarily fixed the problem by using a previous version of iheiddown and rendering the individual chapters using the following YAML section:

title: "Paper One"
author: ...
output:
pdf_document: default
html_document: default
citation_package: natbib
bibliography: ...
bibliography-heading-in-pdf: ...
bib-humanities: ...
doi-in-bibliography: ...
header-includes:
- \usepackage{setspace}\doublespacing
- \usepackage{float}
abstract: \singlespacing _Here goes my abstract_

However, I can only render the individual chapters and not the whole thesis. Is there a way to include three separate abstracts at the beginning of each chapter? Should the abstract heading go under each chapter's YAML section? Or in the YAML section with the metadata of the thesis?
The current YAML section with the metadata of the thesis includes a "resume" heading; however, it is included on the front page only. Any suggestion on how I could proceed?

Offer option to print figures and tables at the end of the paper/chapter

http://www.texdoc.net/texmf-dist/doc/latex/preprint/figcaps.pdf

preview_chapter() replacement

Allow users of the presentation template to reference online/installed logos

iheiddown palette

Test whether thesis, syllabus outputs are as expected

https://github.com/r-lib/vdiffr

Add instructions for installing with MiKTeX

Maybe add to the Wiki so that it can be updated for/by users?

Issue when knitting chapter 4 and 5 individually

Describe the bug
An error message appears when the user knits chapter 4 and 5 individually. It is due to the shaded environment that is not defined.

To Reproduce
Steps to reproduce the behavior:

1. Go to create new file, rmarkdown, template option, define "00-Untitled", create
2. Click on the file "00-Untitled" that has been created, click on chapter 4, and "knit"
3. Scroll down in the rmarkdown window
4. See error

Expected behavior
The shaded environment are supposed to be defined to allow the commands to appear in the PDF. When the user click "knit", the PDF of the chapter should appear, with the commands and the graphs. The shaded environment should be defined appropriately.

Screenshots
If applicable, add screenshots to help explain your problem.

Desktop (please complete the following information):

• MacOS Big Sur 11.1
• R Version 4.03
• RStudio Version 1.4

Additional context
Add any other context about the problem here.

Reconsider fonts

% Fonts \usepackage[charter]{mathdesign} \usepackage[scaled]{helvet} \usepackage[scaled=0.5]{beramono} \allsectionsfont{\sffamily}

Header of the bibliography section displays the name of the previous chapter

Description:

The header of the "References" section of the thesis template displays "5.Conclusion" which is the header of the previous chapter instead of "References". Note that I was able to mitigate the issue if I defined the YAML header and the setcounter like in other chapters of the thesis. However, this leads to the reference being considered as "Chapter 6, References" which is not very elegant.

Presentations

Set up package releases

Choose a new body text font

Need to replace the body font with something more readable and pretty

Add thesis PDFs as artifacts to each release

Modifying the Github workflows to knit and add what the current thesis output looks like to each release/tag helps keep the version current and helps check whether the output is as expected (perhaps also under different systems).

! LaTeX Error: Environment CSLReferences undefined.

Describe the bug
In some situations (e.g. when knitting the entire thesis and not just a single chapter), after knitting all the files to markdown and compiling to a LaTeX document, an error is printed to the console e.g.:

output file: _main.knit.md

! LaTeX Error: Environment CSLReferences undefined.

Error: LaTeX failed to compile Thesis_2020-11-23.tex. See https://yihui.org/tinytex/r/#debugging for debugging tips. See Thesis_2020-11-23.log for more info.
Execution halted

Add poster template

https://github.com/rstudio/pagedown

Add xaringan_columns

https://github.com/emilyriederer/xaringan_columns

Could be a summon_multicolumns() function to install libraries locally, similar to xaringan::summon_remark()

Add gantt plots to thesis template

giocomai/ganttrify

add cite_packages() function

https://github.com/easystats/report/blob/master/R/cite_packages.R

Make better progressive slides

https://www.garrickadenbuie.com/blog/better-progressive-xaringan/?panelset2=slides3

Calculate workload in a syllabus based on readings etc

https://cat.wfu.edu/resources/tools/estimator2/

Chapter by chapter preview outputs titles of unpreviewed sections/chapters

When printing just a single chapter with chapter_pdf(), the section titles of all the other chapters are included in addition and some 'placeholder' text is entered under some of these extra section titles. These extra section titles either should not appear or appear only in the table of contents printed at the start of the chapter preview.

Links:

The issue seems to stem from the bookdown function preview_chapter() Doc Here. The documentation, as well as previous issues, have mentionned it on Github and the response from Yi Hui is that this is done by design. Also see, this issue and this issue

Tables for pdf

I'm currently using the tab_model function from the knitr package to include my model outputs in a nicely formatted table. These are the two commands I am using (they are included in two separate chunks of code because they come from two different models):

tab_model(logit1, logit2, logit3, vcov.fun = "HC", vcov.type = "HC3", digits = 4, show.aic = T, show.loglik = T)

tab_model(poi1, poi2, poi3, vcov.fun = "HC", vcov.type = "HC3", digits = 4, show.aic = T, show.loglik = T)

They do not seem to work when I render my paper in pdf format. What is the function I can use to wrap my model outputs in a nicely formatted table for pdf?
It also appears that, when I render in html, only the second table works. The table from the first chunk of code blocks the rendering in html and gives an error message:

Error in tab_model(logit1, logit2, logit3, vcov.fun = "HC", vcov.type = "HC3", digits = 4, show.aic = T, show.loglik = T) : could not find function "tab_model" Calls: <Anonymous> ... handle ->withCallingHandlers -> withVisible -> eval -> eval

Any ideas on how I might solve this issue?

Create a package vignette

Creating sound documentation as well as a set of tutorials or "get started guides" on a dedicated website would be a nice way to get less tech-savvy students onboard.

Make available on CRAN

https://jef.works/blog/2018/06/18/get-your-package-on-cran-in-10-steps/