zewwwwecon

Quarto Templates for Applied Economic Research Projects

https://github.com/simonreif/zewwwwecon

Repository

Quarto Templates for Applied Economic Research Projects

README.Rmd

---
output: github_document
---



# zewwwwEcon Quarto Templates 

The `zewwwwEcon` package allows to start a new project in [RStudio](https://posit.co/download/rstudio-desktop/){target="_blank"} that contains the basic setup for an empirical research project. It features [Quarto](https://quarto.org/){target="_blank"} templates and some `ggplot2` style adjustments to generate nice looking PDFs for Slides and Paper in an environment that makes reproducibility easy. While this setup uses R, [Quarto also works well with Python](https://quarto.org/docs/computations/python.html){target="_blank"}. This is an unbranded version to be shared on the `www` based on the `zewEcon` package developed for internal use at the [ZEW - Leibniz Centre for European Economic Research](https://www.zew.de/en/){target="_blank"} in Mannheim, Germany. For a preview of the PDF versions, have a look at the [Paper](../../blob/main/examples/FullProject/Paper/example_paper.pdf){target="_blank"} and [Slides](../../blob/main/examples/FullProject/Slides/example_slides.pdf){target="_blank"}.

![](pics/preview.png)

## Motivation

While there are a lot of examples out there of how people use Quarto for their empirical research projects we found no solution out there that contains all the details required for the idiosyncrasies of applied economics research output.[^1]

[^1]: Examples are the [Journal templates](https://quarto.org/docs/journals/formats.html){target="_blank"} maintained by Quarto, the [Hikmah templates](https://github.com/andrewheiss/hikmah-academic-quarto){target="_blank"} by Andrew Heiss, the [research template](https://github.com/AaronGullickson/research-template/){target="_blank"} by Aaron Gullickson or the [froggeR](http://azimuth-project.tech/froggeR/index.html){target="_blank"} package by Kyle Grealis. There is also the excellent [econ-project-template](https://econ-project-templates.readthedocs.io/){target="_blank"} by Hans-Martin von Gaudecker, Tim Mensinger, Tobias Raabe and Max Jahn which provides a full Python setup and a lot of cool features but has less focus on the design of final outpu

## Requirements

For the package to work properly, [R](https://cran.r-project.org/){target="_blank"} (≥ 4.0), [Rstudio](https://posit.co/download/rstudio-desktop/){target="_blank"}, [Quarto](https://quarto.org/docs/get-started/){target="_blank"} (≥ 1.6) and [LaTeX](https://quarto.org/docs/output-formats/pdf-engine.html){target="_blank"} (e.g. TeX Live or tinytex, but definitely a distribution that features XeLaTex) need to be installed.

## Installation

For those only interested in the details of our implementation, the `examples` folder in this repository contains standalone documents for [Paper](../../blob/main/examples/Paper){target="_blank"} and [Slides](../../blob/main/examples/Slides){target="_blank"}. If you download the folder, you can render the `.qmd` files. There is also an example for a [FullProject](../../blob/main/examples/FullProject){target="_blank"} setup which will be fully rendered by typing `make` to the terminal after pointing to the folder (this is automatically set correctly when `FullProject.Rproj` is opened). To have the full setup automatically produced in the RStudio project wizard, please install the package. The package can be installed in R using `devtools` (which you need to install, in case you have not yet).

Option 1: Install from github

``` r
devtools::install_git("https://github.com/simonreif/zewwwwEcon")
```

Option 2: Install a local `.zip` copy of the repository. This is useful if you want to make changes to the package for yourself.

``` r
devtools::install_local("/Users/YOURPATH/thename.zip")
```

## Initiate a new project

After installing the package and restarting R Studio new projects can be created in the project wizard. First select `New Project`.

![](pics/wizz1.png){width="50%"}

You probably want to initiate the Project in a new directory.

![](pics/wizz2.png){width="50%"}

The `zewwwwEcon` template should be somewhere down there.

![](pics/wizz3.png){width="50%"}

You can then add the folder to GitHub by creating a [local git repository](https://docs.github.com/en/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github#initializing-a-git-repository){target="_blank"} and then adding the [local repository to GitHub](https://docs.github.com/en/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github#adding-a-local-repository-to-github-using-git){target="_blank"}.

## Project structure

When you initiate a project under the name `Project_Title` you get the following folder structure:

```         
/Project_Title
├── A_Orig
├── B_Prog
│   └── 0setup.R
├── C_Temp
├── D_Out
├── Paper
│   └── Paper_TITLE.qmd
│   └── zewwwwPaperTemplate.tex
├── Slides
│   └── Slides_TITLE.qmd
│   └── zewwwwSlidesTemplate.tex
│   └── zewwwwImages
├── .lintr
├── .gitignore
├── Project_Title.Rproj
├── references.bib
├── Makefile
```

In the Paper and Slides folder, the `.qmd` files are the Quarto documents to produce the respective output (you might want to replace `TITLE` with some better name for your project). After you open a `.qmd` file, it can be rendered to generate the output `.pdf` documents either by using the `Render` button or by `CMD + Shift + k`. Under the hood, Quarto uses `knitr` to turn code output into formats that can be used for the final document (e.g. PDF files for graphs). Then an intermediate markdown file is generated and taken up by `pandoc` which in turn uses the intermediate markdown file and the respective `*template.tex` file to produce a `LaTeX` document. This `LaTeX` document is then compiled to the final PDF. The cool thing is: you do not need to worry about these details since Quarto is taking care of everything.

![](pics/quarto_flow_current.png){width="50%"}

### Intended flow of things

For a full working example of the project setup and codes, see the `examples/FullProject` folder in this repository. The idea is:

-   Raw data from `A_Orig` is used for data wrangling and estimations through scripts in `B_Prog`.
-   Intermediate files are stored in `C_Temp` and the final output goes into `D_Out` as `.rds` files.
-   The `.qmd` documents in `Paper` and `Slides` take the results from `D_Out` and integrate them in the final documents. Using `.rds` files here allows for final adjustments if outputs need to be different between slides and paper.
-   `0setup.R` loads all packages needed in the project and defines the ggplot2 style.
-   Each script sources the setup, but does not load any additional packages.
-   Each script starts with a fresh environment and ends with an empty environment.

### YAML headers

The YAML header at the beginning of the `.qmd` document contains information that is used either by Quarto to render the document or pasted into the `tex` file from which the final PDF is generated. Most of the entries are self-explanatory.

#### Options for Slides and Paper

-   `pdf-engine:` Which LaTeX distribution to use. Everything works fine with `XeLaTeX` while other engines have caused problems.
-   `cap-location:` While Quarto allows for figure and table captions to be at the bottom of the output, the very sensible default here is `top` since we have notes to write at the bottom.
-   `add-tex:` We do automatically load the most common `TeX` packages in the template files. However, if you need something in addition or want to input some raw `TeX` in the document preamble, this is the space to do it.
-   `editor:` Quarto has a `visual` editor that can be helpful. It can however also mess around with your code, so the default is `source`.

#### Options for Paper

-   `affiliation:` This input is used to identify the corresponding author.
-   `thanks:` Is for the acknowledgement note. We have separated this from the corresponding author note since usually all authors share the acknowledgement.
-   `prelim-note:` Papers are often distributed at very early stages (e.g. for internal workshops) and you can print on the title page that you do not wish this version to get redistributed
-   `number:` Usually the paper is not finished after the first release. You can use this to indicate the current iteration.
-   `repohash:` When using git, you can print the last digits of the hash code for the current commit of the repository to be able to see how your code looked like for the specific version of the paper.

#### Options for Slides

-   `presenter:` If you want your name to appear on every slide at the bottom right, add it here.
-   `partner-logo:` This is a placeholder in case you want to add more logos on the title page.
-   `totalnumber:` If `true` then the total number of slides in the presentation is printed next to the current slide number at the bottom right.
-   `references:` If `yes` then a bibliography will get printed as the last slide(s).

### References

You can use the [pandoc syntax](https://pandoc.org/MANUAL.html#citation-syntax){target="_blank"} for referencing, so `@key` is for text cites and `[@key]` is for indirect references. [Zotero](https://www.zotero.org/){target="_blank"} is well [integrated in Quarto](https://quarto.org/docs/visual-editor/technical.html#citations-from-zotero){target="_blank"}.

### Lintr

To produce consistent code, [lintr](https://lintr.r-lib.org/){target="_blank"} and [styler](https://github.com/r-lib/styler){target="_blank"} can be a great tool. The package includes a `.lintr` file that takes the [default tidyverse linter](https://style.tidyverse.org/){target="_blank"} but loosens the line length restriction to 120.

### gitignore

We have tried to come up with a sensible default for the `.gitignore` file. When working with sensitive data, it might be useful to add `A_Orig` and `C_Temp` to `.gitignore` so that raw data is not accidentally made public.

### Makefile

A makefile automates the execution of the full project. In the file, the full flow from raw data to final output is specified. `make` checks parts have changed and only executes those files and the files that depend on them. When correctly specified, you can just type `make` in the terminal and wait for the output to get updated. For a good introduction to makefiles, see [here](https://third-bit.com/py-rse/automate.html){target="_blank"}. On Windows, you need to install [GNU Make](https://www.gnu.org/software/make/){target="_blank"} for the makefile to run.

## Implementation details

In designing the templates we made some decisions that we believe are sensible but might cause problems.

### Template and Tex Files directly in project folder

Technically, Quarto allows for a way less cluttered project folder than what we implement here. The template files could be stored at a central place and the temporary `.tex` output could be deleted automatically by Quarto. Our implementation has the advantages that 1) it is simple to twist and 2) it is easier to debug things since everything is in one place.

### TeX-Templates from scratch

-   The workflow probably intended by the Quarto developers is to work on the baseline implementation that comes with Quarto and adjust the *parts* as needed
-   Up to now it feels easier to twist everything from scratch (just change `template.tex`)
-   **Caveats:** 1) There are things that generally work in Quarto that do not work with the templates (e.g. Callout Blocks). 2) When something changes for Quarto or R under the hood, the templates need to get updated manually.

### Use TeX fragments in markdown

-   The beauty of Quarto via pandoc is that you can render any document into any format. This does not work if you use raw TeX.
-   But: Arriving at desired PDF outputs is however often simpler using TeX
-   **Future solution:** Use lua filters (e.g. figure notes)

### Clunky Fixes

All programs used in this template are still being developed and therefore some things do not work as we wish by default. Therefore some workarounds were implemented. They should not (but may) cause other problems:

#### Notes for Figures and Tables

**Problem:** When notes are added as a minipage (directly via `LaTeX` or indirectly via `gt`) then we must force `LaTeX` to run them next to each other. Just adding a minipage below an output can lead to a series of graphs followed by a series of graph notes.

**Solution:** All output is generated in a dedicated `:::` environment. At the beginning, we define the label (`fig` / `tbl`) s.t. internal referencing works in Quarto. Then comes the main output. For reasons... then the very last text line in the `:::` environment is used as the title of the Table or Figure.

#### Spacing between Notes and Figures or Tables

**Problem:** When notes are added as a `minipage` (directly via `LaTeX` or indirectly via `gt`) then they appear directly with no space below the output.

**Solution:** For the `LaTeX` code for the minipage below Figures, we can just add `\vspace{}` to solve this. For table notes from `gt`, we need to add an additional source note with an empty unicode character. This empty source code then is displayed as some space below the Table (). As output from `gt` is automatically put into a minipage and there is no way to change the style there, the template defines the font size of all minipage content to scriptsize. This means that if you want to use a normal size minipage, you have to set normalsize in the beginning of your minipage!

#### Caching in Quarto chunks

**Problem:** Caching in Quarto does not realize when a file that is loaded into a chunk has changed. Since we normally create tables and graphs in dedicated scripts and import the script output as `.rds` files into the chunk, a change to the RDS file as a result of a code change in the script will not get realized by the default caching option.

**Solution:** We cache the input `.rds` file in the chunk using its MD5 hash as `cache.extra=tools::md5sum('name_of_output.rds')`. This means when the underlying file changes, the chunk is run. If the code is unchanged the chunk is not re-run. An alternative would be to use `file.mtime()`().

## Package development

This package is developed and maintained by Simon Reif and Benedikt Stelter. We are grateful for the feedback from the early test users Sabrina Schubert, Yasemin Karamik, Jan Köhler, Paul Peters and Theresa Bolz. If you experience bugs, or have ideas on how to improve the templates (functionality, examples, ...), let us know via Email, Issues or pull-request.

Our current plans for future development are:

-   typst implementation

-   Revealjs slides

-   Word output for paper

These add-ons will require some work and coming up with specific lua filters. So this will take some time. If you have cool ideas or want to contribute, let us know!

Owner

Citation (CITATION.cff)

cff-version: 1.2.0
message: "If you want to cite this template, use the reference below."
authors:
- family-names: "Reif"
  given-names: "Simon"
  orcid: "https://orcid.org/0000-0001-6842-289X"
- family-names: "Stelter"
  given-names: "Benedikt"
title: "zewwwwwEcon: Quarto Templates for Applied Economic Research Projects"
version: 0.1.0
doi: 10.5281/zenodo.14800284
date-released: 2025-02-05
url: "https://github.com/simonreif/zewwwwEcon"

GitHub Events