Bookdown Tufte

  
BookdownTutorial

In this post, I have installed the following R packages: bookdown, rmarkdown, tufte, and knitr.

7 min read

Searchable list of CRAN R packages. .-bookdown/ 01-Nov-2020 09:31 - r-cran-boolnet/ 07-Sep-2020 15:13 - r-cran-bradleyterry2/ 31-May-2020 21:25 - r-cran-brew/ 15-May-2020 22:20 - r-cran. Bookdown., tufte. Please use the canonical form R-project.org/package=knitr to link to this page. The bookdown package primarily supports three types of output formats: HTML, LaTeX/PDF, and e-books. In this chapter, we introduce the possible options for these formats. Output formats can be specified either in the YAML metadata of the first Rmd file of the book, or in a separate YAML file named output.yml under the root directory of the book.

The Apache HTTP Server ('httpd') was launched in 1995 and it has been the most popular web server on the Internet since April 1996. It has celebrated its 25th birthday as a project in February 2020. The Apache HTTP Server is a project of The Apache Software Foundation. Apache httpd 2.4.46 Released 2020-08-07 ¶. Httpd is the Apache HyperText Transfer Protocol (HTTP) server program. It is designed to be run as a standalone daemon process. When used like this it will create a pool of child processes or threads to handle requests. In general, httpd should not be invoked directly, but rather should be invoked via apachectl on Unix-based systems. Service https. A web server is a network service that serves content to a client over the web. This typically means web pages, but any other documents can be served as well. Web servers are also known as HTTP servers, as they use the hypertext transport protocol (HTTP). The Apache HTTP Server, httpd, is an open source web server developed by the Apache Software Foundation. Apache HTTPD is an HTTP server daemon produced by the Apache Foundation. It is a piece of software that listens for network requests (which are expressed using the Hypertext Transfer Protocol) and responds to them. It is open source and many entities use it to host their websites.

TL;DR: Rmarkdown and bookdown are awesome; you should use it to write papers; and here is a minimal example.

I have been using LaTex for most of the papers I have published so far (admittedly not that many), even though all of my co-authors use Microsoft Word. Why? Several reasons for this.

  1. When wrting, we should only focus on the content, not worrying about the typesetting, which we will take care later. Word, on the other hand, allows you to see what you get when you write. This makes people (me at least) hard to ignore the typesetting when writing.
  2. It is hard to update the figures and pictures inserted into the manuscript in Word. You need delete old ones and insert new ones whenever your figures are updated. Of course, you can say that do not insert figures until the submission. But wouldn’t it be easier to revise the manuscript when figures are included in the main text? Using LaTex, I can just put the path of figures there and not worry about replace them in the main text.
  3. Literature programming: LaTex allows us to mix code with text in the same file, which increases the reproducibility and decreases potential errors.
  4. Cross-references is easy in LaTex (just label and ref). With Word, it is painful to get the same thing.

However, LaTex has its learning curve and quirks. And even though it intends to make people to focus on content, we usually spend lots of time fighting with things like floats. Not to mention the collaboration barrier betwen its users to Word users. When I finished a draft of my paper, I need to convert it to Word using pandoc so my advisor can edit. Doing it this way, however, figures and tables are usually messed up, as well as cross-references. Tables will be just LaTex source codes there; cross-references will be replaced with their labels (e.g. see Table tab-labels instead of see Table 1). So everytime, I need to write something like “please do not care about the typesetting” in the email to my advisor.

Until recently, I found that the convertion from LaTex and Rmarkdown to Word is reasonably good, thanks to bookdown by Yihui. I just finished my first manuscript written in Rmarkdown 100%. Both my advisor and I are quite happy with it. Therefore, in this post, I am going to talk briefly the process of writing academic papers with Rmarkdown.

First, you need to know a little bit about the syntax. Don’t worry, I am sure you will get it in five minutes. If you use Rstudio, this can be found under “Help” menu.

In this post, I have installed the following R packages: bookdown, rmarkdown, tufte, and knitr. If you do not want to produce pdf files, then you are ready to go. If you need pdf files, then you need to install Latex. Under Windows and Linus, Texlive is good; under Mac, Mactex is available. If you do not mind the time to download and install, I recommend to install the full version, which includes all LaTex packages.

After installing all dependencies, we can open Rstudio (or any text editor) and start writing. I use Rstudio to start the file and work with R code chucks. For the remaining, however, I use Sublime text or Atom. This is mainly because the lack of distraction free function in Rstudio.

Yaml head

Here is the Yaml head I am using now:

Bookdown tufte pdf

A few notes here:

Bookdown tufte example
  • I use the bookdown::pdf_document2, and other bookdown::..document2, which allow cross-references and other features possible.
  • For pdf files, I included some tex files (preamble.tex, which includes some packages I use, e.g. lineno to add line numbers; and doc_prefix.tex, which allows text align at left only).
  • References are put in the bib file. You can use common reference management software to create a bib file. Or you can search through Google Scholar and click on cite under the paper and choose bibtex form, then copy and paste the information into a bib file.
  • link-citations: yes allows you click on a citation/table/figure and jumpo to the corresponding location.
  • csl files are journal style files and can be a url like here or a local file.

R chunks

In my project set up, I have .Rproj file in the project folder, then I have R, Doc, etc. folders. R scripts are located within the R folder while the Rmarkdown file for the manuscript is in the Doc folder. By default, when you knit the Rmarkdown file with Rstudio, it will treat the folder where the Rmarkdown file seated as work space even though the .Rproj file is in the folder one level up. This is a little bit annoying because the path will be different if you click the knit button from running part of the chunks within Rstudio.

To let Rstudio know that we want use the parent folder as the work space, we can add this chunk at the beginning of the file:

Then in a separate R code chunk, we can use source R script with source('R/script.r').

Citations

After put the sources you want to cite in a .bib file, we can cite them in the main text. The idea is that each source will have one unique key, and you can cite it with the key. See the rmarkdown website for details and examples.

Cross-references

Tables

Insert tables by knitr::kable function (:: tells that the kable function is from knitr package in R. Then cross-reference it back with: see Table @ref(tab:tableName), which will return something like see Table 1. The number of the table will depends on its order in the manuscript, therefore, whenever you reorder your tables, you do not need to worry about change their numbers by hand. And the R code chunk for the table looks like this:

The awesome R package kableExtra can be used to customize tables and figures. When render into Word document, if you used library(kableExtra) earlier, this may mess up the tables. I added the following code in the set up chunk so that the package won’t be loaded if knit to Word document.

Figures

Bookdown Tufte Book

Figures are very similar to cross-refer with tables. Basically, you use Figure @ref(fig:figName) to refer to it. And you put the lable (figName here) and caption in the R code chunk:

See more examples in the github file.

For complex figure or table captions, we can use text references. But make sure that no space at the end of the text! Otherwise, the captions won’t be repaced by the text references in Word document.

These pretty much cover most of the common features of scientific writing: citations, cross-references, tables, figures. You can checkout bookdown website for details. Even though bookdown is made for writing books, it is actually very good for writing papers too!

How do you set up Rmarkdown for writing? What tips do you have? Issues? Comments are very welcome. Or even better, you can click the pen on paper button at the top right of the post and edit it.

Thanks for reading and commenting!

6.9 Customize CSS styles

Bookdown Tufte

You can turn on/off some features of the Tufte style in HTML output. The default features enabled are:

If you do not want the page background to be lightyellow, you can remove background from tufte_features. You can also customize the style of the HTML page via a CSS file. For example, if you do not want the subtitle to be italic, you can define

in, say, a CSS file my-style.css (under the same directory of your Rmd document), and apply it to your HTML output via the css option, e.g.,

R Bookdown Tufte

There is also a variant of the Tufte style in HTML/CSS named “Envisioned CSS.” This style can be enabled by specifying the argument tufte_variant = 'envisioned' in tufte_html(),7, e.g.,

You can see a live example at https://rstudio.github.io/tufte/. It is also available in Simplified Chinese: https://rstudio.github.io/tufte/cn/, and its envisioned style can be found at https://rstudio.github.io/tufte/envisioned/.

  1. The actual Envisioned CSS was not used in the tufte package. Only the fonts, background color, and text color are changed based on the default Tufte style.↩︎